Merge pull request #1133 from radiantearth/title-rec

added best practice to include title, updated examples
radiantearth · May 25, 2021 · c197acb · c197acb
2 parents 45d0789 + 24ec4a2
commit c197acb
Show file tree

Hide file tree

Showing 11 changed files with 58 additions and 26 deletions.
diff --git a/best-practices.md b/best-practices.md
@@ -483,6 +483,11 @@ if you follow these recommendations.
    For example, if levels 2 and 4 of the hierarchy only contain Collections, 
    don't add a Catalog at levels 2 and 4.
 
+One further recommendation to help tools is to always include the 'title' field when including a link, especially in the 
+`item`, `child`, `parent` and `root` links, even if it repeats several times. This should be the same as the 'title' in the 
+link destination. Having this enables clients to display a nice human readable name of the link without having  to open the 
+link destination. 
+
 #### Dynamic Catalog Layout
 
 While these recommendations were primarily written for [static catalogs](#static-catalogs), they apply

diff --git a/examples/catalog.json b/examples/catalog.json
@@ -1,6 +1,7 @@
 {
   "id": "examples",
   "type": "Catalog",
+  "title": "Example Catalog",
   "stac_version": "1.0.0-rc.4",
   "description": "This catalog is a simple demonstration of an example catalog that is used to organize a hierarchy of collections and their items.",
   "links": [

diff --git a/examples/collection-only/collection-with-schemas.json b/examples/collection-only/collection-with-schemas.json
@@ -33,11 +33,15 @@
   "links": [
     {
       "rel": "parent",
-      "href": "../catalog.json"
+      "href": "../catalog.json",
+      "type": "application/json",
+      "title": "Example Catalog"
     },
     {
       "rel": "root",
-      "href": "../catalog.json"
+      "href": "../catalog.json",
+      "type": "application/json",
+      "title": "Example Catalog"
     },
     {
       "rel": "license",

diff --git a/examples/collection-only/collection.json b/examples/collection-only/collection.json
@@ -214,11 +214,15 @@
   "links": [
     {
       "rel": "parent",
-      "href": "../catalog.json"
+      "href": "../catalog.json",
+      "type": "application/json",
+      "title": "Example Catalog"
     },
     {
       "rel": "root",
-      "href": "../catalog.json"
+      "href": "../catalog.json",
+      "type": "application/json",
+      "title": "Example Catalog"
     },
     {
       "rel": "license",

diff --git a/examples/collection.json b/examples/collection.json
@@ -82,7 +82,8 @@
     {
       "rel": "root",
       "href": "./collection.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Simple Example Collection"
     },
     {
       "rel": "item",

diff --git a/examples/collectionless-item.json b/examples/collectionless-item.json
@@ -75,22 +75,26 @@
     {
       "rel": "root",
       "href": "./catalog.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Example Catalog"
     },
     {
       "rel": "parent",
       "href": "./catalog.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Example Catalog"
     },
     {
       "rel": "alternate",
       "type": "text/html",
-      "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.html"
+      "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.html",
+      "title": "HTML representation of this STAC Item"
     },
     {
       "rel": "license",
       "type": "text/html",
-      "href": "http://remotedata.io/license.html"
+      "href": "http://remotedata.io/license.html",
+      "title": "Data License for Remote Data, Inc."
     }
   ],
   "assets": {

diff --git a/examples/core-item.json b/examples/core-item.json
@@ -63,17 +63,20 @@
     {
       "rel": "root",
       "href": "./collection.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Simple Example Collection"
     },
     {
       "rel": "parent",
       "href": "./collection.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Simple Example Collection"
     },
     {
       "rel": "alternate",
       "type": "text/html",
-      "href": "http://remotedata.io/catalog/20201211_223832_CS2/index.html"
+      "href": "http://remotedata.io/catalog/20201211_223832_CS2/index.html",
+      "title": "HTML version of this STAC Item"
     }
   ],
   "assets": {

diff --git a/examples/extended-item.json b/examples/extended-item.json
@@ -91,17 +91,20 @@
     {
       "rel": "root",
       "href": "./collection.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Simple Example Collection"
     },
     {
       "rel": "parent",
       "href": "./collection.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Simple Example Collection"
     },
     {
       "rel": "alternate",
       "type": "text/html",
-      "href": "http://remotedata.io/catalog/20201211_223832_CS2/index.html"
+      "href": "http://remotedata.io/catalog/20201211_223832_CS2/index.html",
+      "title": "HTML version of this STAC Item"
     }
   ],
   "assets": {

diff --git a/examples/extensions-collection/collection.json b/examples/extensions-collection/collection.json
@@ -4,10 +4,17 @@
   "stac_version": "1.0.0-rc.4",
   "description": "A heterogenous collection containing deeper examples of various extensions",
   "links": [
+    {
+      "rel": "parent",
+      "href": "../catalog.json",
+      "type": "application/json",
+      "title": "Example Catalog"
+    },
     {
       "rel": "root",
       "href": "../catalog.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Example Catalog"
     },
     {
       "rel": "item",
@@ -18,11 +25,6 @@
       "rel": "license",
       "href": "https://remotedata.io/license.html",
       "title": "Remote Data License Terms"
-    },
-    {
-      "rel": "parent",
-      "href": "../catalog.json",
-      "type": "application/json"
     }
   ],
   "stac_extensions": [],

diff --git a/examples/extensions-collection/proj-example/proj-example.json b/examples/extensions-collection/proj-example/proj-example.json
@@ -213,17 +213,20 @@
     {
       "rel": "root",
       "href": "../../catalog.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Example Catalog"
     },
     {
       "rel": "parent",
       "href": "../collection.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Collection of Extension Items"
     },
     {
       "rel": "collection",
       "href": "../collection.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Collection of Extension Items"
     }
   ],
   "assets": {

diff --git a/examples/simple-item.json b/examples/simple-item.json
@@ -50,12 +50,14 @@
     {
       "rel": "root",
       "href": "./collection.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Simple Example Collection"
     },
     {
       "rel": "parent",
       "href": "./collection.json",
-      "type": "application/json"
+      "type": "application/json",
+      "title": "Simple Example Collection"
     }
   ],
   "assets": {