Draft: Migrate to OpenAPI 3.1

CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## Changed
+
+- OpenAPI schemas are now OpenAPI 3.1 instead of OpenAPI 3.0.
+
 ## Added
 
 - Added authentication status code recommendations.

core/README.md

@@ -158,11 +158,12 @@ The service description endpoint may return any specification format. It is reco
 with media types `application/vnd.oai.openapi` (YAML), `application/vnd.oai.openapi+json;version=3.0` (3.0 JSON),
 or `application/vnd.oai.openapi+json;version=3.1` (3.1 JSON). Whichever format or formats are used, the link
 with relation `service-desc` must have a `type` field that matches an `Accept` header value to which the service
-responds, and the `Content-Type` header in the response should contain the same media type. If the OpenAPI 3.0
-format is used, the conformance class `http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30` should be
-advertised. All service descriptions provided as part of the STAC API spec use OpenAPI 3.0 YAML format, and can
-easily be used to return either YAML or JSON from this endpoint. OAFeat does not currently define a conformance
-class for OpenAPI 3.1, but may in the future. 
+responds, and the `Content-Type` header in the response should contain the same media type.
+All service descriptions provided as part of the STAC API spec use OpenAPI 3.1 YAML format, and
+can easily be used to return either YAML or JSON from this endpoint. OAFeat does not currently define a conformance
+class for OpenAPI 3.1, but may in the future. If the OpenAPI 3.0
+format is used instead, the conformance class `http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30` should be
+advertised.
 
 If sub-catalogs are used, it is **recommended** that these use the endpoint `/catalogs/{catalogId}` to avoid conflicting
 with other endpoints from the root.
@@ -207,7 +208,7 @@ different conformance classes and a different set of links.
         },
         {
             "rel": "service-desc",
-            "type": "application/vnd.oai.openapi+json;version=3.0",
+            "type": "application/vnd.oai.openapi+json;version=3.1",
             "href": "https://stac-api.example.com/api"
         },
         {

core/commons.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.3
+openapi: 3.1.0
 info:
   title: The SpatioTemporal Asset Catalog API - Commons
   description: This is the OpenAPI version of the core STAC spec JSON Schemas.
@@ -313,7 +313,7 @@ components:
                 maxItems: 6
                 items:
                   type: number
-                example:
+                examples:
                   - -180
                   - -90
                   - 180
@@ -361,7 +361,7 @@ components:
                   type: string
                   format: date-time
                   nullable: true
-                example:
+                examples:
                   - '2011-11-11T12:22:11Z'
                   - null
             trs:
@@ -409,8 +409,8 @@ components:
         headers:
           type: object
           description: Object key values pairs they map to headers
-          example:
-            Accept: application/json
+          examples:
+            - Accept: application/json
         body:
           type: object
           description: For POST requests, the resource can specify the HTTP body as a JSON object.
@@ -443,7 +443,8 @@ components:
         provided as a value of this field. If there is no public license URL
         available, it is RECOMMENDED to host the license text and
         link to it.
-      example: Apache-2.0
+      examples:
+        - Apache-2.0
     providers:
       type: array
       description: >-
@@ -537,7 +538,7 @@ components:
       maxItems: 6
       items:
         type: number
-      example:
+      examples:
         - -110
         - 39.5
         - -105
@@ -550,11 +551,13 @@ components:
         The searchable date and time of the assets, in UTC.
         It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).
         `null` is allowed, but requires `start_datetime` and `end_datetime` from common metadata to be set.
-      example: '2018-02-12T00:00:00Z'
+      examples:
+        - '2018-02-12T00:00:00Z'
     stac_version:
       title: STAC version
       type: string
-      example: 1.0.0
+      examples:
+        - 1.0.0
     stac_extensions:
       title: STAC extensions
       type: array
@@ -688,12 +691,13 @@ components:
             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
+            examples:
+              - http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
           title:
             type: string
             description: Displayed title
-            example: Thumbnail
+            examples:
+              - Thumbnail
           description:
             type: string
             description: >-
@@ -702,17 +706,19 @@ components:
 
               [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for
               rich text representation.
-            example: Small 256x256px PNG thumbnail for a preview.
+            examples:
+              - Small 256x256px PNG thumbnail for a preview.
           type:
             type: string
             description: Media type of the asset
-            example: image/png
+            examples:
+              - image/png
           roles:
             type: array
             items:
               type: string
             description: Purposes of the asset
-            example:
+            examples:
               - thumbnail
     geometryGeoJSON:
       oneOf:

core/openapi.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.3
+openapi: 3.1.0
 info:
   title: STAC API - Core
   version: 1.0.0-rc.2
@@ -74,7 +74,7 @@ components:
                 title: this document
               - href: 'http://data.example.org/api'
                 rel: service-desc
-                type: application/vnd.oai.openapi+json;version=3.0
+                type: application/vnd.oai.openapi+json;version=3.1
                 title: the API definition
               - href: 'http://data.example.org/api.html'
                 rel: service-doc

fragments/itemcollection/openapi.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.3
+openapi: 3.1.0
 info:
   title: The SpatioTemporal Asset Catalog API - Item Collection
   description: The specification for a set of items, e.g. returned by a search.
@@ -29,7 +29,7 @@ components:
             with the `next` relation type.
           items:
             $ref: '../../core/commons.yaml#/components/schemas/link'
-          example:
+          examples:
             - rel: next
               href: >-
                 http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk

item-search/README.md

@@ -282,7 +282,7 @@ the [overview](../overview.md#example-landing-page) document.
         },
         {
             "rel": "service-desc",
-            "type": "application/vnd.oai.openapi+json;version=3.0",
+            "type": "application/vnd.oai.openapi+json;version=3.1",
             "href": "https://stac-api.example.com/api"
         },
         {

item-search/openapi.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.3
+openapi: 3.1.0
 info:
   title: STAC API - Item Search
   version: 1.0.0-rc.2
@@ -11,6 +11,7 @@ info:
   license:
     name: Apache License 2.0
     url: 'http://www.apache.org/licenses/LICENSE-2.0'
+  x-conformance-classes: [ "https://api.stacspec.org/v1.0.0-rc.2/item-search" ]
 tags:
   - name: Item Search
     description: essential characteristics of a STAC API
@@ -222,7 +223,8 @@ components:
     limit:
       type: integer
       minimum: 1
-      example: 10
+      examples: 
+        - 10
       default: 10
       maximum: 10000
       description: |-
@@ -302,4 +304,5 @@ components:
         If a feature has multiple temporal properties, it is the decision of the
         server whether only a single temporal property is used to determine
         the extent or all relevant temporal properties.
-      example: '2018-02-12T00:00:00Z/2018-03-18T12:31:12Z'
+      examples:
+        - '2018-02-12T00:00:00Z/2018-03-18T12:31:12Z'

ogcapi-features/README.md

@@ -93,7 +93,9 @@ This conformance class should be advertised to OAFeat clients so they will know
 If OpenAPI 3.0 is used for the endpoint referenced by the `service-desc` link relation in the landing page defined
 by *STAC API - Core*, the
 [OGC API - Features - Part 1 Requirements Class OpenAPI 3.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rc_oas30)
-(<http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30>) can be advertised. 
+(<http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30>) can be advertised. STAC API specifications
+are defined in OpenAPI 3.1 instead of 3.0, so implementations using these documents should not advertise
+this conformance class.
 
 ## Link Relations
 
@@ -377,7 +379,7 @@ the [overview](../overview.md#example-landing-page) document.
         },
         {
             "rel": "service-desc",
-            "type": "application/vnd.oai.openapi+json;version=3.0",
+            "type": "application/vnd.oai.openapi+json;version=3.1",
             "href": "https://stac-api.example.com/api"
         },
         {

ogcapi-features/openapi-collections.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.3
+openapi: 3.1.0
 info:
   title: STAC API - Collections
   version: 1.0.0-rc.2
@@ -48,7 +48,6 @@ paths:
                 conformsTo:
                   - 'https://api.stacspec.org/v1.0.0-rc.2/core'
                   - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core'
-                  - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30'
                   - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson'
                 links:
                   - href: 'http://data.example.org/'
@@ -57,7 +56,7 @@ paths:
                     title: this document
                   - href: 'http://data.example.org/api'
                     rel: service-desc
-                    type: application/vnd.oai.openapi+json;version=3.0
+                    type: application/vnd.oai.openapi+json;version=3.1
                     title: the API definition
                   - href: 'http://data.example.org/api.html'
                     rel: service-doc

ogcapi-features/openapi-features.yaml

@@ -1,4 +1,4 @@
-openapi: 3.0.3
+openapi: 3.1.0
 info:
   title: STAC API - Features
   version: 1.0.0-rc.2
@@ -47,7 +47,6 @@ paths:
                 conformsTo:
                   - 'https://api.stacspec.org/v1.0.0-rc.2/core'
                   - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core'
-                  - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30'
                   - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson'
                 links:
                   - href: 'http://data.example.org/'
@@ -56,7 +55,7 @@ paths:
                     title: this document
                   - href: 'http://data.example.org/api'
                     rel: service-desc
-                    type: application/vnd.oai.openapi+json;version=3.0
+                    type: application/vnd.oai.openapi+json;version=3.1
                     title: the API definition
                   - href: 'http://data.example.org/api.html'
                     rel: service-doc
@@ -99,7 +98,7 @@ paths:
         '200':
           $ref: '#/components/responses/Collections'
         '4XX':
-          $ref: '../core/commons.yaml#/components/responses/Error'          
+          $ref: '../core/commons.yaml#/components/responses/Error'
         '5XX':
           $ref: '../core/commons.yaml#/components/responses/Error'
   '/collections/{collectionId}':
@@ -310,7 +309,8 @@ components:
         parameters like `bbox`.
       type: integer
       minimum: 0
-      example: 127
+      examples: 
+        - 127
     numberReturned:
       description: |-
         The number of features in the feature collection.
@@ -322,12 +322,14 @@ components:
         of items in the "features" array.
       type: integer
       minimum: 0
-      example: 10
+      examples: 
+        - 10
     timeStamp:
       description: This property indicates the time and date when the response was generated.
       type: string
       format: date-time
-      example: '2017-08-17T08:05:32Z'
+      examples: 
+        - '2017-08-17T08:05:32Z'
   responses:
     ConformanceDeclaration:
       description: |-
@@ -344,7 +346,6 @@ components:
           example:
             conformsTo:
               - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core'
-              - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30'
               - 'http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson'
     Collections:
       description: |-

overview.md

@@ -151,7 +151,6 @@ The Landing Page will at least have the following `conformsTo` and `links`:
         "https://api.stacspec.org/v1.0.0-rc.2/ogcapi-features",
         "https://api.stacspec.org/v1.0.0-rc.2/item-search",
         "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
-        "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
         "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
     ],
     "links": [
@@ -172,7 +171,7 @@ The Landing Page will at least have the following `conformsTo` and `links`:
         },
         {
             "rel": "service-desc",
-            "type": "application/vnd.oai.openapi+json;version=3.0",
+            "type": "application/vnd.oai.openapi+json;version=3.1",
             "href": "https://stac-api.example.com/api"
         },
         {