diff --git a/CHANGELOG.md b/CHANGELOG.md index 7298b66d7..14b8488be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Clarified the role of geometries on items in the label extension - Data Cube Extension: Units for STAC dimensions in should now be compliant to UDUNITS-2 units (singular) whenever available. +- URIs (usually found int properties like `href`, `url`) are now validated using the `iri-reference` format in JSON Schema (allows international characters in URIs) - Relaxed the regular expression for DOIs in the scientific extension ([#910](https://github.com/radiantearth/stac-spec/issues/910)) ### Removed diff --git a/best-practices.md b/best-practices.md index 0198410d7..e27314af6 100644 --- a/best-practices.md +++ b/best-practices.md @@ -254,10 +254,10 @@ STAC version. Otherwise some behaviour of functionality may be unpredictable (e. ## Use of links -The main catalog specification allows both relative and absolute links, and says that `self` links are not required, but are +The STAC specifications allow both relative and absolute links, and says that `self` links are not required, but are strongly recommended. This is what the spec must say to enable the various use cases, but there is more subtlety for when it -is essential to use different link types. The best practice is to use one of the below -catalog types, applying the link recommendations consistently, instead of just haphazardly applying anything the spec allows. +is essential to use different link types. The best practice is to use one of the below catalog types, applying the link +recommendations consistently, instead of just haphazardly applying relative links in some places and absolute ones in other places. ### Self-contained Catalogs diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index bac9a2ffe..97a3266ef 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -56,11 +56,8 @@ with links. | type | string | [Media type](../item-spec/item-spec.md#media-types) of the referenced entity. | | title | string | A human readable title to be used in rendered displays of the link. | -A more complete list of possible 'rel' types can be seen at the [IANA page of Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - -Please see the chapter 'relative vs absolute links' in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links) -for a discussion on that topic, as well as the [use of links](../best-practices.md#use-of-links) section of the -catalog best practices document. +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. #### Relation types diff --git a/catalog-spec/json-schema/catalog.json b/catalog-spec/json-schema/catalog.json index 48d32d469..9d345b019 100644 --- a/catalog-spec/json-schema/catalog.json +++ b/catalog-spec/json-schema/catalog.json @@ -33,7 +33,7 @@ { "title": "Reference to a JSON Schema", "type": "string", - "format": "uri" + "format": "iri" }, { "title": "Reference to a core extension", @@ -72,7 +72,8 @@ "properties": { "href": { "title": "Link reference", - "type": "string" + "type": "string", + "format": "iri-reference" }, "rel": { "title": "Link relation type", diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 533dc265b..21d342fa7 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -118,15 +118,15 @@ This object describes a relationship with another entity. Data providers are adv | type | string | [Media type](../item-spec/item-spec.md#media-types) of the referenced entity. | | title | string | A human readable title to be used in rendered displays of the link. | -Please see the chapter 'relative vs absolute links' in the [Item spec](../item-spec/item-spec.md#relative-vs-absolute-links) for a discussion on that topic. +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. #### Relation types -STAC Collections use a variety of `rel` types in the link object, to describe the exact nature of the link between this collection -and the entity it is linking to. It is recommended to use the official [IANA Link Relation -Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible. 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. +STAC Collections use a variety of `rel` types in the link object, to describe the exact nature of the link between this collection and the entity it is linking to. +It is recommended to use the official [IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible. +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 | | ------- | ------------------------------------------------------------ | @@ -138,8 +138,7 @@ STAC uses an official type but adds additional meaning for the STAC context. | 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 supplement the STAC catalog with 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. | -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. +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. **Note:** The [STAC Catalog specification](../catalog-spec/catalog-spec.md) requires a link to at least one `item` or `child` catalog. This is *not* a requirement for collections, but *recommended*. In contrast to catalogs, it is **REQUIRED** that items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index e6d1fcb08..bdfe8b6cc 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -30,7 +30,7 @@ { "title": "Reference to a JSON Schema", "type": "string", - "format": "uri" + "format": "iri" }, { "title": "Reference to a core extension", @@ -83,7 +83,7 @@ "url": { "title": "Organization homepage", "type": "string", - "format": "url" + "format": "iri" } } } diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 0d3f17c0e..26390d1ed 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -114,21 +114,15 @@ It is allowed to add additional fields such as a `title` and `type`. | 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. | -#### Relative vs Absolute links - -Currently, the JSON schema for links does not require them to be formatted as URIs, to allow -implementors to provide relative links. In general, Catalog APIs should aim to provide absolute links -whenever possible. Static Catalogs are potentially more portable if they incorporate only -relative links, so that every link doesn't need to be rewritten when the data is copied. Additional -recommendations for particular `rel` types are given in the `rel` type description. +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. #### Relation types -STAC Items use a variety of `rel` types in the link object, to describe the exact nature of the link between this item -and the entity it is linking to. It is recommended to use the official [IANA Link Relation -Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible. 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. +STAC Items use a variety of `rel` types in the link object, to describe the exact nature of the link between this item and the entity it is linking to. +It is recommended to use the official [IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible. +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 | | ------------ | ------------------------------------------------------------ | diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index 00496a76d..a9325655d 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -104,7 +104,7 @@ { "title": "Reference to a JSON Schema", "type": "string", - "format": "uri" + "format": "iri" }, { "title": "Reference to a core extension", @@ -150,7 +150,8 @@ "properties": { "href": { "title": "Link reference", - "type": "string" + "type": "string", + "format": "iri-reference" }, "rel": { "title": "Link relation type", @@ -188,7 +189,8 @@ "properties": { "href": { "title": "Asset reference", - "type": "string" + "type": "string", + "format": "iri-reference" }, "title": { "title": "Asset title", diff --git a/item-spec/json-schema/provider.json b/item-spec/json-schema/provider.json index ec90c05c2..ffcaf234f 100644 --- a/item-spec/json-schema/provider.json +++ b/item-spec/json-schema/provider.json @@ -37,7 +37,7 @@ "url": { "title": "Organization homepage", "type": "string", - "format": "url" + "format": "iri" } } }