Skip to content

Commit

Permalink
New field in links (method, headers, body) (#1253)
Browse files Browse the repository at this point in the history 
* Initial new field in links

* updated changelog

* format table

* links moved to common metadata

* Map<string, *>

* Update item-spec/common-metadata.md

Co-authored-by: Matthias Mohr <[email protected]>

* Update common-metadata.md with HTTP headers description

* Update item-spec/json-schema/item.json

Co-authored-by: Matthias Mohr <[email protected]>

* Update item-spec/common-metadata.md

Co-authored-by: Matthias Mohr <[email protected]>

* Update item-spec/common-metadata.md

Co-authored-by: Matthias Mohr <[email protected]>

* Update item-spec/common-metadata.md

Co-authored-by: Matthias Mohr <[email protected]>

* Update item-spec/common-metadata.md

Co-authored-by: Matthias Mohr <[email protected]>

* link object section review

* link headers schema

* Update item-spec/common-metadata.md

Co-authored-by: Matthias Mohr <[email protected]>

* Update item-spec/json-schema/item.json

Co-authored-by: Matthias Mohr <[email protected]>

---------

Co-authored-by: Matthias Mohr <[email protected]>
  • Loading branch information
@emmanuelmathot @m-mohr
emmanuelmathot and m-mohr authored Jul 17, 2024
1 parent e6161f6 commit 155ccc3
Show file tree
Hide file tree
Showing 7 changed files with 59 additions and 39 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
### Added

- The `keywords` field known from Collections is available in common metadata. ([#1187](https://github.com/radiantearth/stac-spec/issues/1187))
- New fields `method`, `headers` and `body` in the Link Object. ([#1198](https://github.com/radiantearth/stac-spec/issues/1198))
- The `license` field additionally supports SPDX expressions and the value `other`.
- The `roles` field known from Assets and Providers is available in common metadata. ([#1267](https://github.com/radiantearth/stac-spec/issues/1267))
- Validation for absolute self link in item schema. ([#1281](https://github.com/radiantearth/stac-spec/issues/1281))
Expand Down
13 changes: 1 addition & 12 deletions catalog-spec/catalog-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,18 +68,7 @@ This must **not** declare the extensions that are only implemented in child Coll

### Link Object

This object describes a relationship with another entity. Data providers are advised to be liberal
with links.

| Field Name | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) |
| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter ["Relation types"](#relation-types) for more information. |
| type | string | [Media type](#media-types) of the referenced entity. |
| title | string | A human readable title to be used in rendered displays of the link. |

For a full discussion of the situations where relative and absolute links are recommended see the
['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices.
This object is described in the [STAC Common Metadata](../item-spec/common-metadata.md#link-object) section.

#### Relation types

Expand Down
12 changes: 1 addition & 11 deletions collection-spec/collection-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -249,17 +249,7 @@ May also include information about the final storage provider hosting the data.

### Link Object

This object describes a relationship with another entity. Data providers are advised to be liberal with links.

| Field Name | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) |
| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "[Relation types](#relation-types)" for more information. |
| type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. |
| title | string | A human readable title to be used in rendered displays of the link. |

For a full discussion of the situations where relative and absolute links are recommended see the
['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices.
This object is described in the [STAC Common Metadata](../item-spec/common-metadata.md#link-object) section.

#### Relation types

Expand Down
26 changes: 26 additions & 0 deletions item-spec/common-metadata.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ or [Collection Asset](../collection-spec/collection-spec.md#asset-object).
- [constellation](#constellation)
- [mission](#mission)
- [gsd](#gsd)
- [Link](#link-object)

Various *examples* are available in the folder [`examples`](../examples/).
*JSON Schemas* can be found in the folder [`json-schema`](json-schema/).
Expand Down Expand Up @@ -212,3 +213,28 @@ optical and short-wave IR bands are all 30 meters, but the panchromatic band is
PlanetScope Ortho Tile Product has an `gsd` of 3.7 (or 4 if rounding), even though the pixel size of the images is 3.125.
For example, one might choose for WorldView-2 the Multispectral 20° off-nadir value of 2.07
and for WorldView-3 the Multispectral 20° off-nadir value of 1.38.

### Link Object

This object describes a relationship with another entity. Data providers are advised to be liberal
with the links section, to describe things like the Catalog an Item is in, related Items, parent or
child Items (modeled in different ways, like an 'acquisition' or derived data).

| Field Name | Type | Description |
| ---------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) |
| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "Relation types" for more information. |
| type | string | Media type of the referenced entity. |
| title | string | A human readable title to be used in rendered displays of the link. |
| method | string | The HTTP method that shall be used for the request to the target resource, in uppercase. `GET` by default |
| headers | Map<string, string \| \[string]> | The HTTP headers to be sent for the request to the target resource. |
| body | any | The HTTP body to be sent to the target resource. |

For a full discussion of the situations where relative and absolute links are recommended see the
['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices.

#### HTTP headers

The field `headers` allows to describe a dictionary of HTTP headers that are required to be sent by the client.
The keys of the dictionary are the header names, and the values are either a single string or an array of strings.
In case of an array, the header is expected to be sent multiple times with the different values.
15 changes: 1 addition & 14 deletions item-spec/item-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -186,20 +186,7 @@ only be used when the data itself is nested, as with `eo:bands`.

### Link Object

This object describes a relationship with another entity. Data providers are advised to be liberal
with the links section, to describe things like the Catalog an Item is in, related Items, parent or
child Items (modeled in different ways, like an 'acquisition' or derived data).
It is allowed to add additional fields such as a `title` and `type`.

| Field Name | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) |
| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "Relation types" for more information. |
| type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. |
| title | string | A human readable title to be used in rendered displays of the link. |

For a full discussion of the situations where relative and absolute links are recommended see the
['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices.
This object is described in the [STAC Common Metadata](common-metadata.md#link-object) section.

#### Relation types

Expand Down
29 changes: 28 additions & 1 deletion item-spec/json-schema/item.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,33 @@
"title": {
"title": "Link title",
"type": "string"
},
"method": {
"title": "Link method",
"type": "string",
"pattern": "^[A-Z]+$",
"default": "GET"
},
"headers": {
"title": "Link headers",
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
},
"body": {
"title": "Link body",
"$comment": "Any type is allowed."
}
},
"$comment": "Link with relationship `self` must be absolute URI",
Expand Down Expand Up @@ -275,4 +302,4 @@
]
}
}
}
}
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,4 +92,4 @@
]
]
}
}
}

0 comments on commit 155ccc3

Please sign in to comment.