#257: Update OpenAPI definition to catalog / dataset definition

api-spec/STAC-query.yaml

@@ -23,7 +23,13 @@ servers:
 paths:
   /stac:
     get:
-      summary: Return a catalog definition json
+      summary: Return the root catalog or collection.
+      description: >-
+        Returns the root STAC Catalog or STAC Collection that is the entry point
+        for users to browse with STAC Browser or for search engines to crawl.
+        This can either return a single STAC Collection or more commonly a STAC
+        catalog that usually lists sub-catalogs of STAC Collections, i.e. a
+        simple catalog that lists all collections available through the API.
       tags:
         - STAC
       responses:
@@ -35,8 +41,9 @@ paths:
                 $ref: '#/components/schemas/catalogDefinition'
   /stac/search:
     get:
-      summary: >-
-        retrieve items matching filters. Intended as a shorthand API for simple
+      summary: Search STAC items by simple filtering.
+      description: >-
+        Retrieve Items matching filters. Intended as a shorthand API for simple
         queries. This method is optional.
       operationId: getSearchSTAC
       tags:
@@ -68,7 +75,8 @@ paths:
               schema:
                 type: string
     post:
-      summary: >-
+      summary: Search STAC items by full-featured filtering.
+      description: >-
         retrieve items matching filters. Intended as the standard, full-featured
         query API. This method is mandatory.
       operationId: postSearchSTAC
@@ -239,16 +247,30 @@ components:
           type: string
         description:
           type: string
+    links:
+      type: array
+      items:
+        $ref: '#/components/schemas/link'
     link:
       type: object
       required:
         - href
+        - rel
+      additionalProperties: true
       properties:
         href:
           type: string
+          format: url
+          example: 'http://www.geoserver.example/stac/naip/child/catalog.json'
         rel:
           type: string
-          example: prev
+          example: child
+        type:
+          type: string
+          example: application/json
+        title:
+          type: string
+          example: NAIP Child Catalog
     searchBody:
       description: The search criteria
       type: object
@@ -351,55 +373,26 @@ components:
     catalogDefinition:
       type: object
       required:
-        - name
+        - stac_version
+        - id
         - description
         - links
       additionalProperties: true
       properties:
-        name:
+        stac_version:
           type: string
-          example: NAIP
-        description:
+          example: 0.6.0
+        id:
           type: string
-          example: Catalog of NAIP Imagery
-        license:
+          example: naip
+        title:
           type: string
-          example: PDDL-1.0
-        links:
-          type: array
-          items:
-            type: object
-            additionalProperties: true
-            properties:
-              rel:
-                type: string
-                example: child
-              href:
-                type: string
-        contact:
-          type: object
-          properties:
-            name:
-              type: string
-            email:
-              type: string
-            phone:
-              type: string
-            url:
-              type: string
-        formats:
-          type: array
-          items:
-            type: string
-        keywords:
-          type: array
-          items:
-            type: string
-        homepage:
+          example: NAIP Imagery
+        description:
           type: string
-        provider:
-          type: object
-          additionalProperties: true
+          example: Catalog of NAIP Imagery.
+        links:
+          $ref: '#/components/schemas/links'
     itemCollection:
       type: object
       required:
@@ -422,48 +415,25 @@ components:
         - id
         - type
         - geometry
+        - bbox
         - links
         - properties
         - assets
       properties:
         id:
-          type: string
-          example: path/to/example.tif
-          description: 'unique ID, potentially link to file'
+          $ref: '#/components/schemas/itemId'
         bbox:
           $ref: '#/components/schemas/bbox'
         geometry:
           $ref: 'http://geojson.org/schema/Geometry.json'
         type:
-          type: string
-          description: The GeoJSON type
-          enum:
-            - Feature
+          $ref: '#/components/schemas/itemType'
         properties:
           $ref: '#/components/schemas/itemProperties'
         links:
-          type: object
-          additionalProperties:
-            type: object
-            required:
-              - href
-              - rel
-            properties:
-              href:
-                type: string
-              rel:
-                type: string
+          $ref: '#/components/schemas/links'
         assets:
-          type: object
-          additionalProperties:
-            type: object
-            required:
-              - href
-            properties:
-              href:
-                type: string
-              name:
-                type: string
+          $ref: '#/components/schemas/itemAssets'
       example:
         type: Feature
         id: CS3-20160503_132130_04
@@ -487,22 +457,50 @@ components:
                 - 37.488035566
         properties:
           datetime: '2016-05-03T13:21:30.040Z'
-          provider: 'http://www.cool-sat.com'
-          license: CC-BY-4.0
         links:
-          self:
-            rel: self
+          - rel: self
             href: >-
               http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04.json
         assets:
           analytic:
-            name: 4-Band Analytic
+            title: 4-Band Analytic
             href: >-
               http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/analytic.tif
           thumbnail:
-            name: thumbnail
+            title: Thumbnail
             href: >-
               http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
+            type: image/png
+    itemId:
+      type: string
+      example: path/to/example.tif
+      description: 'Provider identifier, a unique ID, potentially a link to a file.'
+    itemType:
+      type: string
+      description: The GeoJSON type
+      enum:
+        - Feature
+    itemAssets:
+      type: object
+      additionalProperties:
+        type: object
+        required:
+          - href
+        properties:
+          href:
+            type: string
+            format: url
+            description: Link to the asset object
+            example: >-
+              http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
+          title:
+            type: string
+            description: Displayed title
+            example: Thumbnail
+          type:
+            type: string
+            description: Media type of the asset
+            example: image/png
     itemProperties:
       type: object
       required:
@@ -511,14 +509,8 @@ components:
       properties:
         datetime:
           $ref: '#/components/schemas/time'
-        provider:
-          type: string
-          description: Information about the provider
-        license:
-          type: string
-          description: Data license name based on SPDX License List
       additionalProperties:
-        type: object
+        description: Any additional properties added in via extensions.
     itemCollectionLinks:
       type: object
       properties: