PB-2354: OpenAPI: Group properties by extension

Changed the schema of "properties" to group the fields by STAC
extension:

- Core Properties
    - created
    - datetime
    - start_datetime
    - end_datetime
    - updated
    - title
- Timestamps extension
    - expires
- Forecast extension
    - forecast:reference_datetime
    - forecast:horizon
    - forecast:duration
    - forecast:variable
    - forecast:perturbed
- CF extension
    - cf:standard_name
    - unit

With the `anyOf`, SwaggerUI renders these groups into groups that can be
clicked. That should make the understanding easier.

On the other side, technically the OpenAPI specs are now incorrect: As
it is now, you could, for example, have this:

```json
{
"properties":
"expires": "2018-02-12T23:20:50Z"
}
```

while in fact some of the core properties are always mandatory and you
would rather have something like this:

```json
{
"properties":
"created": "2018-02-12T23:20:50Z",
"updated": "2018-02-12T23:20:50Z",
"datetime": "2018-02-12T23:20:50Z",
"expires": "2018-02-12T23:20:50Z",
}
```

Another sideeffect of this change is that the example payload only shows
the core properties, not all properties anymore:

```json
"properties": {
"created": "2018-02-12T23:20:50Z",
"updated": "2018-02-12T23:20:50Z",
"datetime": "2018-02-12T23:20:50Z",
"start_datetime": "2018-02-12T23:20:50Z",
"end_datetime": "2018-02-12T23:20:50Z",
"title": "Feature title"
},
```

We decided to still go with the incorrect OpenAPI schema because it
makes it more explicit.

Author: asteiner-swisstopo

spec/components/schemas.yaml

@@ -1130,41 +1130,39 @@ components:
                 minItems: 2
                 items:
                   type: number
-    itemProperties:
-      title: Properties
-      description: >-
-        Provides the core metadata fields plus extensions
-
-
-        The item's data timing information can be specified either with
-
-        * One datetime value in the field `datetime`
-
-        * A datetime range with a `start_datetime` and an `end_datetime`
-
-
-        One of the two is required.
-
-
-        **Note on STAC extensions:** When a STAC extension is listed in the `stac_extensions` field,
-        certain properties may be required. For example, when using the
-        [Forecast extension](`https://github.com/stac-extensions/forecast`), the
-        `forecast:reference_datetime` property is required.
+    itemPropertiesCore:
+      title: Core Properties
+      description: Core STAC metadata fields for Items
       properties:
         created:
           $ref: "#/components/schemas/created"
+        updated:
+          $ref: "#/components/schemas/updated"
         datetime:
           $ref: "#/components/schemas/datetime"
         start_datetime:
           $ref: "#/components/schemas/datetime"
         end_datetime:
           $ref: "#/components/schemas/datetime"
-        expires:
-          $ref: "#/components/schemas/datetime"
-        updated:
-          $ref: "#/components/schemas/updated"
         title:
           $ref: "#/components/schemas/featureTitle"
+      required:
+        - created
+        - updated
+
+    itemPropertiesTimestamps:
+      title: Timestamps Extension
+      description: >-
+        Properties from the [STAC Timestamps extension](https://github.com/stac-extensions/timestamps)
+      properties:
+        expires:
+          $ref: "#/components/schemas/datetime"
+
+    itemPropertiesForecast:
+      title: Forecast Extension
+      description: >-
+        Properties from the [STAC Forecast extension](https://github.com/stac-extensions/forecast)
+      properties:
         forecast:reference_datetime:
           $ref: "#/components/schemas/datetime"
         forecast:horizon:
@@ -1175,14 +1173,48 @@ components:
           $ref: "#/components/schemas/forecast_variable"
         forecast:perturbed:
           $ref: "#/components/schemas/forecast_perturbed"
+      required:
+        - forecast:reference_datetime
+
+    itemPropertiesCF:
+      title: CF Extension
+      description: >-
+        Properties from the [STAC CF extension](https://github.com/stac-extensions/cf.
+      properties:
         cf:standard_name:
           $ref: "#/components/schemas/cf_standard_name"
         unit:
           $ref: "#/components/schemas/unit"
-      required:
-        - created
-        - updated
+
+    itemProperties:
+      title: Properties
+      description: |-
+        Provides the core metadata fields for a feature together with additional
+        fields from the declared STAC extensions.
+
+
+        An feature's temporal information is expressed either as a single point
+        in time through `datetime`, or as a range through `start_datetime`
+        and `end_datetime` (in which case `datetime` is `null`). One of these
+        two forms is required.
+
+
+        STAC extensions:
+
+        * Every feature carries the mandatory core properties.
+        * To use an extension's additional fields, list that extension in the
+          `stac_extensions` array.
+        * Declaring an extension may make some of its properties required.
+          For example, the
+          [Forecast extension](`https://github.com/stac-extensions/forecast`)
+          requires `forecast:reference_datetime`.
+
       type: object
+      anyOf:
+        - $ref: "#/components/schemas/itemPropertiesCore"
+        - $ref: "#/components/schemas/itemPropertiesTimestamps"
+        - $ref: "#/components/schemas/itemPropertiesForecast"
+        - $ref: "#/components/schemas/itemPropertiesCF"
     itemType:
       title: type
       description: The GeoJSON type

spec/static/spec/v1/openapi.yaml

@@ -1399,38 +1399,37 @@ components:
                 minItems: 2
                 items:
                   type: number
-    itemProperties:
-      title: Properties
-      description: >-
-        Provides the core metadata fields plus extensions
-
-
-        The item's data timing information can be specified either with
-
-        * One datetime value in the field `datetime`
-
-        * A datetime range with a `start_datetime` and an `end_datetime`
-
-
-        One of the two is required.
-
-
-        **Note on STAC extensions:** When a STAC extension is listed in the `stac_extensions` field, certain properties may be required. For example, when using the [Forecast extension](`https://github.com/stac-extensions/forecast`), the `forecast:reference_datetime` property is required.
+    itemPropertiesCore:
+      title: Core Properties
+      description: Core STAC metadata fields for Items
       properties:
         created:
           $ref: "#/components/schemas/created"
+        updated:
+          $ref: "#/components/schemas/updated"
         datetime:
           $ref: "#/components/schemas/datetime"
         start_datetime:
           $ref: "#/components/schemas/datetime"
         end_datetime:
           $ref: "#/components/schemas/datetime"
-        expires:
-          $ref: "#/components/schemas/datetime"
-        updated:
-          $ref: "#/components/schemas/updated"
         title:
           $ref: "#/components/schemas/featureTitle"
+      required:
+        - created
+        - updated
+    itemPropertiesTimestamps:
+      title: Timestamps Extension
+      description: >-
+        Properties from the [STAC Timestamps extension](https://github.com/stac-extensions/timestamps)
+      properties:
+        expires:
+          $ref: "#/components/schemas/datetime"
+    itemPropertiesForecast:
+      title: Forecast Extension
+      description: >-
+        Properties from the [STAC Forecast extension](https://github.com/stac-extensions/forecast)
+      properties:
         forecast:reference_datetime:
           $ref: "#/components/schemas/datetime"
         forecast:horizon:
@@ -1441,14 +1440,45 @@ components:
           $ref: "#/components/schemas/forecast_variable"
         forecast:perturbed:
           $ref: "#/components/schemas/forecast_perturbed"
+      required:
+        - forecast:reference_datetime
+    itemPropertiesCF:
+      title: CF Extension
+      description: >-
+        Properties from the [STAC CF extension](https://github.com/stac-extensions/cf.
+      properties:
         cf:standard_name:
           $ref: "#/components/schemas/cf_standard_name"
         unit:
           $ref: "#/components/schemas/unit"
-      required:
-        - created
-        - updated
+    itemProperties:
+      title: Properties
+      description: |-
+        Provides the core metadata fields for a feature together with additional
+        fields from the declared STAC extensions.
+
+
+        An feature's temporal information is expressed either as a single point
+        in time through `datetime`, or as a range through `start_datetime`
+        and `end_datetime` (in which case `datetime` is `null`). One of these
+        two forms is required.
+
+
+        STAC extensions:
+
+        * Every feature carries the mandatory core properties.
+        * To use an extension's additional fields, list that extension in the
+          `stac_extensions` array.
+        * Declaring an extension may make some of its properties required.
+          For example, the
+          [Forecast extension](`https://github.com/stac-extensions/forecast`)
+          requires `forecast:reference_datetime`.
       type: object
+      anyOf:
+        - $ref: "#/components/schemas/itemPropertiesCore"
+        - $ref: "#/components/schemas/itemPropertiesTimestamps"
+        - $ref: "#/components/schemas/itemPropertiesForecast"
+        - $ref: "#/components/schemas/itemPropertiesCF"
     itemType:
       title: type
       description: The GeoJSON type

spec/static/spec/v1/openapitransactional.yaml

@@ -1479,38 +1479,37 @@ components:
                 minItems: 2
                 items:
                   type: number
-    itemProperties:
-      title: Properties
-      description: >-
-        Provides the core metadata fields plus extensions
-
-
-        The item's data timing information can be specified either with
-
-        * One datetime value in the field `datetime`
-
-        * A datetime range with a `start_datetime` and an `end_datetime`
-
-
-        One of the two is required.
-
-
-        **Note on STAC extensions:** When a STAC extension is listed in the `stac_extensions` field, certain properties may be required. For example, when using the [Forecast extension](`https://github.com/stac-extensions/forecast`), the `forecast:reference_datetime` property is required.
+    itemPropertiesCore:
+      title: Core Properties
+      description: Core STAC metadata fields for Items
       properties:
         created:
           $ref: "#/components/schemas/created"
+        updated:
+          $ref: "#/components/schemas/updated"
         datetime:
           $ref: "#/components/schemas/datetime"
         start_datetime:
           $ref: "#/components/schemas/datetime"
         end_datetime:
           $ref: "#/components/schemas/datetime"
-        expires:
-          $ref: "#/components/schemas/datetime"
-        updated:
-          $ref: "#/components/schemas/updated"
         title:
           $ref: "#/components/schemas/featureTitle"
+      required:
+        - created
+        - updated
+    itemPropertiesTimestamps:
+      title: Timestamps Extension
+      description: >-
+        Properties from the [STAC Timestamps extension](https://github.com/stac-extensions/timestamps)
+      properties:
+        expires:
+          $ref: "#/components/schemas/datetime"
+    itemPropertiesForecast:
+      title: Forecast Extension
+      description: >-
+        Properties from the [STAC Forecast extension](https://github.com/stac-extensions/forecast)
+      properties:
         forecast:reference_datetime:
           $ref: "#/components/schemas/datetime"
         forecast:horizon:
@@ -1521,14 +1520,45 @@ components:
           $ref: "#/components/schemas/forecast_variable"
         forecast:perturbed:
           $ref: "#/components/schemas/forecast_perturbed"
+      required:
+        - forecast:reference_datetime
+    itemPropertiesCF:
+      title: CF Extension
+      description: >-
+        Properties from the [STAC CF extension](https://github.com/stac-extensions/cf.
+      properties:
         cf:standard_name:
           $ref: "#/components/schemas/cf_standard_name"
         unit:
           $ref: "#/components/schemas/unit"
-      required:
-        - created
-        - updated
+    itemProperties:
+      title: Properties
+      description: |-
+        Provides the core metadata fields for a feature together with additional
+        fields from the declared STAC extensions.
+
+
+        An feature's temporal information is expressed either as a single point
+        in time through `datetime`, or as a range through `start_datetime`
+        and `end_datetime` (in which case `datetime` is `null`). One of these
+        two forms is required.
+
+
+        STAC extensions:
+
+        * Every feature carries the mandatory core properties.
+        * To use an extension's additional fields, list that extension in the
+          `stac_extensions` array.
+        * Declaring an extension may make some of its properties required.
+          For example, the
+          [Forecast extension](`https://github.com/stac-extensions/forecast`)
+          requires `forecast:reference_datetime`.
       type: object
+      anyOf:
+        - $ref: "#/components/schemas/itemPropertiesCore"
+        - $ref: "#/components/schemas/itemPropertiesTimestamps"
+        - $ref: "#/components/schemas/itemPropertiesForecast"
+        - $ref: "#/components/schemas/itemPropertiesCF"
     itemType:
       title: type
       description: The GeoJSON type