From 47f8e2dc70d50466161c05a1f08dd3bb3fd16175 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 5 Oct 2023 16:30:48 +0200 Subject: [PATCH 1/6] Clarified which media types should be used for the hierarchical relation types --- CHANGELOG.md | 4 +--- catalog-spec/catalog-spec.md | 14 +++++++------- collection-spec/collection-spec.md | 18 +++++++++--------- item-spec/item-spec.md | 14 +++++++------- 4 files changed, 24 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e9cc1f8..cd97b446 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,10 +25,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Fixed - Several typos and minor language changes - -### Fixed - - Clarified that collection IDs should be unique across all collections in the corresponding root catalog. +- Clarified which media types should be used for the hierarchical relation types ## [v1.0.0] - 2021-05-25 diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index e457aad1..713be393 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -85,13 +85,13 @@ For a full discussion of the situations where relative and absolute links are re The following types are commonly used as `rel` types in the Link Object of a STAC Catalog: -| Type | Description | -| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | -| root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | -| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | -| child | URL to a child STAC entity (Catalog or Collection). | -| item | URL to a STAC Item. | +| Type | Description | Media Type | +| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | +| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/json | +| root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | application/json | +| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | application/json | +| child | URL to a child STAC entity (Catalog or Collection). | application/json | +| item | URL to a STAC Item. | application/geo+json (or application/json) | **Note:** A link to at least one `item` or `child` (Catalog or Collection) is **RECOMMENDED**, but empty catalogs are allowed if there is an intent to populate it or its children were removed. diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 853f396e..ce73679a 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -259,15 +259,15 @@ It is recommended to use the official The following table explains places where custom STAC `rel` types are used for Collections. This is done where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. -| Type | Description | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | -| root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. | -| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. | -| child | URL to a child STAC entity (Catalog or Collection). | -| item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | -| license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. | -| derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | +| Type | Description | Media Type | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | +| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/json | +| root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. | application/json | +| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. | application/json | +| child | URL to a child STAC entity (Catalog or Collection). | application/json | +| item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | application/geo+json (or application/json) | +| license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. | Any | +| derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | application/json | A more complete list of possible `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 04f8af64..f9053d76 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -190,13 +190,13 @@ It is recommended to use the official The following table explains places where STAC use custom `rel` types are used with Items. This happens where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. -| Type | Description | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | -| root | URL to the root STAC entity (Catalog or Collection). | -| parent | URL to the parent STAC entity (Catalog or Collection). | -| collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. | -| derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | +| Type | Description | | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | +| self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/geo+json (or application/json) | +| root | URL to the root STAC entity (Catalog or Collection). | application/json | +| parent | URL to the parent STAC entity (Catalog or Collection). | application/json | +| collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. | application/json | +| derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | application/geo+json (or application/json) | A more complete list of potential `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. From 6c92e40a88fdc5f6c1dfd0ff26f27d8a4380b655 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 9 Oct 2023 17:33:12 +0200 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Pete Gadomski --- catalog-spec/catalog-spec.md | 2 +- collection-spec/collection-spec.md | 2 +- item-spec/item-spec.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 713be393..47dc790e 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -91,7 +91,7 @@ The following types are commonly used as `rel` types in the Link Object of a STA | root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | application/json | | parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | application/json | | child | URL to a child STAC entity (Catalog or Collection). | application/json | -| item | URL to a STAC Item. | application/geo+json (or application/json) | +| item | URL to a STAC Item. | application/geo+json (preferred) or application/json | **Note:** A link to at least one `item` or `child` (Catalog or Collection) is **RECOMMENDED**, but empty catalogs are allowed if there is an intent to populate it or its children were removed. diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index ce73679a..a0cf6677 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -265,7 +265,7 @@ This is done where there is not a clear official option, or where STAC uses an o | root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. | application/json | | parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. | application/json | | child | URL to a child STAC entity (Catalog or Collection). | application/json | -| item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | application/geo+json (or application/json) | +| item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | application/geo+json (preferred) or application/json | | license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. | Any | | derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | application/json | diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index f9053d76..52b3a20e 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -192,11 +192,11 @@ This happens where there is not a clear official option, or where STAC uses an o | Type | Description | | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -| self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/geo+json (or application/json) | +| self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/geo+json (preferred) or application/json | | root | URL to the root STAC entity (Catalog or Collection). | application/json | | parent | URL to the parent STAC entity (Catalog or Collection). | application/json | | collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. | application/json | -| derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | application/geo+json (or application/json) | +| derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | application/geo+json (preferred) or application/json | A more complete list of potential `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. From 3ea38b2d03e777bb267abba71668f524db8f2813 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Thu, 9 Nov 2023 11:47:46 +0100 Subject: [PATCH 3/6] tables formatted --- catalog-spec/catalog-spec.md | 12 ++++++------ collection-spec/collection-spec.md | 16 ++++++++-------- item-spec/item-spec.md | 10 +++++----- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 47dc790e..c29e45ee 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -85,12 +85,12 @@ For a full discussion of the situations where relative and absolute links are re The following types are commonly used as `rel` types in the Link Object of a STAC Catalog: -| Type | Description | Media Type | -| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/json | -| root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | application/json | -| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | application/json | -| child | URL to a child STAC entity (Catalog or Collection). | application/json | +| Type | Description | Media Type | +| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/json | +| root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | application/json | +| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | application/json | +| child | URL to a child STAC entity (Catalog or Collection). | application/json | | item | URL to a STAC Item. | application/geo+json (preferred) or application/json | **Note:** A link to at least one `item` or `child` (Catalog or Collection) is **RECOMMENDED**, but empty catalogs are diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index a0cf6677..9c3c38b1 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -259,15 +259,15 @@ It is recommended to use the official The following table explains places where custom STAC `rel` types are used for Collections. This is done where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. -| Type | Description | Media Type | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | -| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/json | -| root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. | application/json | -| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. | application/json | -| child | URL to a child STAC entity (Catalog or Collection). | application/json | +| Type | Description | Media Type | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | +| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/json | +| root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. | application/json | +| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. | application/json | +| child | URL to a child STAC entity (Catalog or Collection). | application/json | | item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | application/geo+json (preferred) or application/json | -| license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. | Any | -| derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | application/json | +| license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. | Any | +| derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | application/json | A more complete list of possible `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 52b3a20e..59c05557 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -190,12 +190,12 @@ It is recommended to use the official The following table explains places where STAC use custom `rel` types are used with Items. This happens where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. -| Type | Description | | -| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | +| Type | Description | | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/geo+json (preferred) or application/json | -| root | URL to the root STAC entity (Catalog or Collection). | application/json | -| parent | URL to the parent STAC entity (Catalog or Collection). | application/json | -| collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. | application/json | +| root | URL to the root STAC entity (Catalog or Collection). | application/json | +| parent | URL to the parent STAC entity (Catalog or Collection). | application/json | +| collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. | application/json | | derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | application/geo+json (preferred) or application/json | A more complete list of potential `rel` types and their meaning in STAC can be found in the [Using Relation From 80b75c98c923769ca2b5021b5b3baafcc3596a0d Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 14 May 2024 23:41:37 +0200 Subject: [PATCH 4/6] Add notes about OGC APIs --- best-practices.md | 24 +++++++++++++--------- principles.md | 51 +++++++++++++++++++++++------------------------ 2 files changed, 40 insertions(+), 35 deletions(-) diff --git a/best-practices.md b/best-practices.md index a6577745..c7b78e5b 100644 --- a/best-practices.md +++ b/best-practices.md @@ -18,7 +18,7 @@ - [Unrectified Satellite Data](#unrectified-satellite-data) - [Data that is not spatial](#data-that-is-not-spatial) - [Representing Vector Layers in STAC](#representing-vector-layers-in-stac) -- **[Asset Best Practices](#asset-practices)** +- **[Asset (and Link) Best Practices](#asset-and-link-best-practices)** - [Common Use Cases of Additional Fields for Assets](#common-use-cases-of-additional-fields-for-assets) - [Working with Media Types](#working-with-media-types) - [Common Media Types in STAC](#common-media-types-in-stac) @@ -270,7 +270,7 @@ that is not possible then the appropriate way to handle Collection-level search [OGC API - Records](https://github.com/opengeospatial/ogcapi-records) standard, which is a 'brother' specification of STAC API. Both are compliant with OGC API - Features, adding richer search capabilities to enable finding of data. -## Asset Practices +## Asset (and Link) Bests Practices ### Common Use Cases of Additional Fields for Assets @@ -305,8 +305,12 @@ providing them at the Asset level can prove to be very useful for using the data [Media Types](https://en.wikipedia.org/wiki/Media_type) are a key element that enables STAC to be a rich source of information for clients. The best practice is to use as specific of a media type as possible (so if a file is a GeoJSON then don't use a JSON media type), and to use [registered](https://www.iana.org/assignments/media-types/media-types.xhtml) IANA types as much as possible. -The following table lists types that commonly show up in STAC assets. And the [section](#formats-with-no-registered-media-type) -past that gives recommendations on what to do if you have a format in your asset that does not have an IANA registered type. + +For hierarchical links (e.g. relation types `root`, `parent`, `child`, `item`) it is important that +clients filter for the corresponding STAC media types +(e.g. `application/json` for all relation types and/or `application/geo+json` for relation type `item`). +Hierarchical links with other media types (e.g. `text/html`) may be present for hierarchical links, +especially in STAC implementations that are also implementing OGC API - Records. #### Common Media Types in STAC @@ -331,15 +335,17 @@ following table lists some of the most common ones you may encounter or use. *Deprecation notice: GeoTiff previously used the media type `image/vnd.stac.geotiff` and Cloud Optimized GeoTiffs used `image/vnd.stac.geotiff; profile=cloud-optimized`. -Both can still appear in old STAC implementations, but are deprecated and should be replaced. This will, unfortunately, likely shift in the future as -[OGC sorts out the media types](https://github.com/opengeospatial/geotiff/issues/34).* +Both can still appear in old STAC implementations, but are deprecated and should be replaced. #### Formats with no registered media type +This section gives recommendations on what to do if you have a format in your links or assets +that does not have an IANA registered type. Ideally every media type used is on the [IANA registry](https://www.iana.org/assignments/media-types/media-types.xhtml). If -you are using a format that is not on that list we recommend you use [custom content -type](https://restcookbook.com/Resources/using-custom-content-types/). These typically use the `vnd.` prefix, see [RFC 6838 -section-3.2](https://tools.ietf.org/html/rfc6838#section-3.2). Ideally the format provider will actually +you are using a format that is not on that list we recommend you use +[custom content type](https://restcookbook.com/Resources/using-custom-content-types/). +These typically use the `vnd.` prefix, see [RFC 6838 section-3.2](https://tools.ietf.org/html/rfc6838#section-3.2). +Ideally the format provider will actually register the media type with IANA, so that other STAC clients can find it easily. But if you are only using it internally it is [acceptable to not register](https://stackoverflow.com/questions/29121241/custom-content-type-is-registering-with-iana-mandatory) it. It is relatively easy to [register](https://www.iana.org/form/media-types) a `vnd` media type. diff --git a/principles.md b/principles.md index 42c9a3ab..eb89e76e 100644 --- a/principles.md +++ b/principles.md @@ -5,37 +5,36 @@ reviewed in pull requests, approved by consensus. The goal of the principles is core geospatial standards. - **Creation and evolution of specs in Github**, using Open Source principles -(please read [Producing OSS](http://producingoss.com/) if that phrase doesn't immediately make sense to you). -The collaboration facilities of Github should be used to their full extent. All proposed improvements and -changes should come in the form of pull requests, using code review functionality to discuss changes. - + (please read [Producing OSS](http://producingoss.com/) if that phrase doesn't immediately make sense to you). + The collaboration facilities of Github should be used to their full extent. All proposed improvements and + changes should come in the form of pull requests, using code review functionality to discuss changes. - **JSON + REST + HTTP at the core.** JSON has won over XML, and REST over SOAP. We embrace them and -are not considering legacy options. Forward looking protocols can be considered as extensions, -but the default specifications should be in JSON, following best REST practices. HTTP caching and -error codes should be leveraged at the core. GeoJSON has already defined the core geospatial JSON response, -so it should also be core. [JSON API](http://jsonapi.org/) should be used as basis of decisions where possible. - + are not considering legacy options. Forward looking protocols can be considered as extensions, + but the default specifications should be in JSON, following best REST practices. HTTP caching and + error codes should be leveraged at the core. GeoJSON has already defined the core geospatial JSON response, + so it should also be core. + + [OGC APIs](https://ogcapi.ogc.org/) (especially Common, Features, and Records) + and/or [JSON API](https://jsonapi.org/) should be used as basis of decisions where possible. + There's a strong desire to be as compatible as possible with OGC API - Features and OGC API - Records. - **Small Reusable Pieces Loosely Coupled** - Each specification should be as focused as possible, -defining one core concept and refraining from describing lots of options. Additional options can be made -as separate specifications that build on the core. But the core specs should be small and easily understandable, -with clear defaults for any choice. Handling complex cases should be possible by combining discrete pieces. -Implementors should not be forced to implement lots of options just for basic compliance - they should be -able to pick and choose which pieces are relevant to the problems they are trying to solve. - + defining one core concept and refraining from describing lots of options. Additional options can be made + as separate specifications that build on the core. But the core specs should be small and easily understandable, + with clear defaults for any choice. Handling complex cases should be possible by combining discrete pieces. + Implementors should not be forced to implement lots of options just for basic compliance - they should be + able to pick and choose which pieces are relevant to the problems they are trying to solve. - **Focus on the developer**. Specifications should aim for implementability - any explanation or design choice -should be considered with a developer audience. And specifications should be accessible to developers who do not -have geospatial background. A developer should not need to understand 'projections' to implement a simple feature -access service. But we should think through the spec extensions they could use in the future when their client asks -for data in a different projection. - + should be considered with a developer audience. And specifications should be accessible to developers who do not + have geospatial background. A developer should not need to understand 'projections' to implement a simple feature + access service. But we should think through the spec extensions they could use in the future when their client asks + for data in a different projection. - **Working code required.** Proposed changes should be accompanied by working code -(ideally with a link to an online service running the code). A reference implementation should be available -online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations -that cover the entire specification. Extensions have their own [Extension Maturity](./extensions/README.md#extension-maturity) model. - + (ideally with a link to an online service running the code). A reference implementation should be available + online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations + that cover the entire specification. Extensions have their own [Extension Maturity](./extensions/README.md#extension-maturity) model. - **Design for scale.** The design should work great with more data than can be imagined right now. -Ideally implementations are built with large test data sets to validate that they will work. -Everything should be compatible with content distribution network (CDN) caching. + Ideally implementations are built with large test data sets to validate that they will work. + Everything should be compatible with content distribution network (CDN) caching. ## Resources From b07cd6ad875a5ba56b128357536084cb4013e120 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 14 May 2024 23:54:23 +0200 Subject: [PATCH 5/6] Fix CI --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index c7b78e5b..c80a360b 100644 --- a/best-practices.md +++ b/best-practices.md @@ -270,7 +270,7 @@ that is not possible then the appropriate way to handle Collection-level search [OGC API - Records](https://github.com/opengeospatial/ogcapi-records) standard, which is a 'brother' specification of STAC API. Both are compliant with OGC API - Features, adding richer search capabilities to enable finding of data. -## Asset (and Link) Bests Practices +## Asset (and Link) Best Practices ### Common Use Cases of Additional Fields for Assets From 9d8c00bc081e45777a3c2e22be697dbed52dddd1 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 15 May 2024 17:20:05 +0200 Subject: [PATCH 6/6] Update item-spec/item-spec.md --- item-spec/item-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 59c05557..c1fde3aa 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -190,7 +190,7 @@ It is recommended to use the official The following table explains places where STAC use custom `rel` types are used with Items. This happens where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. -| Type | Description | | +| Type | Description | Media Type | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | application/geo+json (preferred) or application/json | | root | URL to the root STAC entity (Catalog or Collection). | application/json |