Merge pull request #953 from radiantearth/rel-abs-edits

Relative vs absolute link edits

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

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
 

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
 

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",

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).
 

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"
               }
             }
           }

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                                                  |
 | ------------ | ------------------------------------------------------------ |

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",

item-spec/json-schema/provider.json

@@ -37,7 +37,7 @@
           "url": {
             "title": "Organization homepage",
             "type": "string",
-            "format": "url"
+            "format": "iri"
           }
         }
       }