Add ItemCollection fragment #25

core/commons.yaml

@@ -858,36 +858,4 @@ components:
           $ref: "#/components/schemas/geometryGeoJSON"
         properties:
           type: object
-          nullable: true
-    itemCollection:
-      description: >-
-        A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity
-      type: object
-      required:
-        - stac_version
-        - features
-        - type
-      properties:
-        stac_version:
-          $ref: '#/components/schemas/stac_version'
-        stac_extensions:
-          $ref: '#/components/schemas/stac_extensions'
-        type:
-          type: string
-          enum:
-            - FeatureCollection
-        features:
-          type: array
-          items:
-            $ref: '#/components/schemas/item'
-        links:
-          type: array
-          description: >-
-            An array of links. Can be used for pagination, e.g. by providing a link
-            with the `next` relation type.
-          items:
-            $ref: '#/components/schemas/link'
-          example:
-            - rel: next
-              href: >-
-                http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
+          nullable: true

core/examples/itemcollection-sample-full.json

@@ -0,0 +1,89 @@
+{
+  "stac_version": "1.0.0-beta.2",
+  "stac_extensions": [],
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "stac_version": "1.0.0-beta.2",
+      "stac_extensions": [],
+      "type": "Feature",
+      "id": "CS3-20160503_132131_05",
+      "bbox": [
+        -122.59750209,
+        37.48803556,
+        -122.2880486,
+        37.613537207
+      ],
+      "geometry": {
+        "type": "Polygon",
+        "coordinates": [
+          [
+            [
+              -122.308150179,
+              37.488035566
+            ],
+            [
+              -122.597502109,
+              37.538869539
+            ],
+            [
+              -122.576687533,
+              37.613537207
+            ],
+            [
+              -122.288048600,
+              37.562818007
+            ],
+            [
+              -122.308150179,
+              37.488035566
+            ]
+          ]
+        ]
+      },
+      "properties": {
+        "datetime": "2016-05-03T13:22:30.040Z",
+        "title": "A CS3 item",
+        "license": "PDDL-1.0",
+        "providers": [
+          {
+            "name": "CoolSat",
+            "roles": [
+              "producer",
+              "licensor"
+            ],
+            "url": "https://cool-sat.com/"
+          }
+        ]
+      },
+      "collection": "CS3",
+      "links": [
+        {
+          "rel": "self",
+          "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.json"
+        },
+        {
+          "rel": "collection",
+          "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/catalog.json"
+        }
+      ],
+      "assets": {
+        "analytic": {
+          "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/analytic.tif",
+          "title": "4-Band Analytic"
+        },
+        "thumbnail": {
+          "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/thumbnail.png",
+          "title": "Thumbnail",
+          "roles": [ "thumbnail" ]
+        }
+      }
+    }
+  ],
+  "links": [
+    {
+      "rel": "self",
+      "href": "http://stac.example.com/search?collection=CS3"
+    }
+  ]
+}

core/examples/itemcollection-sample-minimal.json

@@ -0,0 +1,6 @@
+{
+  "stac_version": "1.0.0-beta.2",
+  "stac_extensions": [],
+  "type": "FeatureCollection",
+  "features": []
+}

core/itemcollection-spec.md

@@ -0,0 +1,45 @@
+# STAC API - ItemCollection Fragment
+
+This document explains the structure and content of a SpatioTemporal Asset Catalog (STAC) ItemCollection. 
+An **ItemCollection** is a [GeoJSON](http://geojson.org/) [FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) 
+that is augmented with [foreign members](https://tools.ietf.org/html/rfc7946#section-6) relevant to a STAC entity.
+
+Similarly to the relationship between a GeoJSON Feature and a STAC Item, a STAC ItemCollection should be a valid GeoJSON 
+FeatureCollection to allow interoperability with existing tools that support GeoJSON. 
+
+Items are represented in JSON format and are very flexible. Any JSON object that contains all the
+required fields is a valid STAC ItemCollection.
+
+- Examples:
+  - See the [minimal example](examples/itemcollection-sample-minimal.json), as well as a [more complete 
+    example](examples/itemcollection-sample-full.json). There are more real world inspired samples in the [examples/](examples/) folder.
+- [OpenAPI YAML](openapi.yaml)
+
+## ItemCollection fields
+
+This object describes a STAC ItemCollection. The fields `type` and `features` are inherited from GeoJSON FeatureCollection.
+
+| Field Name      | Type                                    | Description |
+| --------------- | --------------------------------------- | ----------- |
+| stac_version    | string                                  | **REQUIRED.** The STAC version the ItemCollection implements. |
+| stac_extensions | \[string\]                                | A list of extensions the ItemCollection implements. |
+| type            | string                                  | **REQUIRED.** Always "FeatureCollection" to provide compatibility with GeoJSON. |
+| features        | [STAC Item](../stac-spec/item-spec/item-spec.md)               | **REQUIRED** A possibly-empty array of Items. |
+| links           | [Link Object](../stac-spec/item-spec/item-spec.md#link-object) | An array of Links related to this ItemCollection. |
+
+**stac_version**: In general, STAC versions can be mixed, but please keep the [recommended best 
+practices](../stac-spec/best-practices.md#mixing-stac-versions) in mind.
+
+**stac_extensions**: A list of STAC content extensions the ItemCollection implements. The list contains URLs to the JSON Schema files it 
+can be validated against. For official [content extensions](../stac-spec/extensions/README.md#list-of-content-extensions), a "shortcut"
+can be used. This means you can specify the folder name of the extension, for example `single-file-stac` for the Single File 
+STAC extension. This does *not* apply for [API extensions](../extensions.md). If the versions of the extension and the item diverge, 
+you can specify the URL of the JSON schema file. This list must only contain extensions that extend the ItemCollection itself, see the 
+the 'Scope' column in the list of extensions. It must not contain extensions that extend the Items, these must be specified in the Items directly.
+
+## Extensions
+
+- The [Context Extension](../item-search/README.md#context) adds additional fields to STAC ItemCollection relevant 
+  to their use as search results.
+- The [Single File STAC Extension](../stac-spec/extensions/single-file-stac/README.md) provides a set of Collections and Items 
+  as a single file catalog.

extensions.md

@@ -36,7 +36,7 @@ stable for over a year and are used in twenty or more implementations.
 |--------------------------------------------------------|----------------|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|------------|
 | [Fields](fragments/fields/README.md)                             | *None*         | <http://stacspec.org/spec/api/1.0.0-beta.1/req/fields>          | Adds parameter to control which fields are returned in the response.                                                                    | *Pilot*    |
 | [Query](fragments/query/README.md)                               | *None*         | <http://stacspec.org/spec/api/1.0.0-beta.1/req/query>           | Adds parameter to search Item and Collection properties.                                                                                | *Pilot*    |
-| [Context](fragments/context/README.md)                           | ItemCollection | <http://stacspec.org/spec/api/1.0.0-beta.1/req/context>         | Adds search related metadata (context) to ItemCollection.                                                                               | *Proposal* |
+| [Context](fragments/context/README.md)                           | [ItemCollection](core/itemcollection-spec.md) | <http://stacspec.org/spec/api/1.0.0-beta.1/req/context>         | Adds search related metadata (context) to ItemCollection.                                                                               | *Proposal* |
 | [Sort](fragments/sort/README.md)                                 | *None*         | <http://stacspec.org/spec/api/1.0.0-beta.1/req/sort>            | Adds Parameter to control sorting of returns results.                                                                                   | *Pilot*    |
 | [Transaction](ogcapi-features/extensions/transaction/README.md)                   | *None*         | <http://www.opengis.net/spec/ogcapi-features-4/1.0/conf/simpletx> | Adds PUT and DELETE endpoints for the creation, editing, and deleting of items and Collections.                                         | *Pilot*    |
 | [Items and Collections API Version](ogcapi-features/extensions/version/README.md) | *None*         | <http://stacspec.org/spec/api/1.0.0-beta.1/req/version>         | Adds GET versions resource to collections and items endpoints and provides semantics for a versioning scheme for collections and items. | *Proposal* |

fragments/context/README.md

@@ -5,7 +5,7 @@
 - **Dependents:**
   - [Item Search](../../item-search)
 
-This extension is intended to augment the core ItemCollection
+This extension is intended to augment the core [ItemCollection](../../core/itemcollection-spec.md)
 object when the ItemCollection is the result of a search, for example, from calling the `/search` API endpoint.
 
 **Note**: *This extension is currently only used by [STAC Item Search](../../item-search) functionality.
@@ -21,7 +21,7 @@ implementing OGC API - Features.*
 
 | Element   | Type                              | Description |
 | --------- | --------------------------------- | ----------- |
-| `context` | [Context Object](#context-object) | **REQUIRED.** The search-related metadata for the ItemCollection. |
+| `context` | [Context Object](#context-object) | **REQUIRED.** The search-related metadata for the [ItemCollection](../../core/itemcollection-spec.md). |
 
 ## Context Object
 
@@ -31,9 +31,9 @@ implementing OGC API - Features.*
 | limit    | integer \| null | The maximum number of results to which the result was limited. |
 | matched  | integer         | The count of total number of results that match for this query, possibly estimated, particularly in the context of NoSQL data stores. |
 
-  The default sort of query results should be stable, but may not be depending on the data store's sorting performance.
-   It is recommended that the [Sort API Extension](../sort/README.md) be implemented in conjunction with this extension
-   and that fields conducive to stable sorting have sorting enabled over them.
+The default sort of query results should be stable, but may not be depending on the data store's sorting performance.
+It is recommended that the [Sort API Extension](../sort/README.md) be implemented in conjunction with this extension
+and that fields conducive to stable sorting have sorting enabled over them.
 
 **limit** - The maximum number of results requested explicitly, the default limit used by the service implementation
 if no parameter was provided, or the maximum limit used by the service implementation if the limit parameter was larger.

fragments/fields/README.md

@@ -34,7 +34,7 @@ No error should be returned if a specified field has no value for it in the cata
 support the EO Extension, a successful HTTP response should be returned and the Item entities will not contain that 
 attribute. 
 
-If no `fields` are specified, the response is **must** be a valid ItemCollection. If a client excludes
+If no `fields` are specified, the response is **must** be a valid [ItemCollection](../../core/itemcollection-spec.md). If a client excludes
 attributes that are required in a STAC Item, the server may return an invalid STAC Item. For example, if `type` 
 and `geometry` are excluded, the entity will not even be a valid GeoJSON Feature, or if `bbox` is excluded then the entity 
 will not be a valid STAC Item.

fragments/itemcollection/openapi.yaml

@@ -0,0 +1,39 @@
+openapi: 3.0.3
+info:
+  title: The SpatioTemporal Asset Catalog API - Item Collection
+  version: 1.0.0-beta.1
+paths: {}
+components:
+  schemas:
+    itemCollection:
+      description: >-
+        A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity
+      type: object
+      required:
+        - stac_version
+        - features
+        - type
+      properties:
+        stac_version:
+          $ref: '../../core/commons.yaml#/components/schemas/stac_version'
+        stac_extensions:
+          $ref: '../../core/commons.yaml#/components/schemas/stac_extensions'
+        type:
+          type: string
+          enum:
+            - FeatureCollection
+        features:
+          type: array
+          items:
+            $ref: '../../core/commons.yaml#/components/schemas/item'
+        links:
+          type: array
+          description: >-
+            An array of links. Can be used for pagination, e.g. by providing a link
+            with the `next` relation type.
+          items:
+            $ref: '../../core/commons.yaml#/components/schemas/link'
+          example:
+            - rel: next
+              href: >-
+                http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk

item-search/README.md

@@ -7,7 +7,7 @@
 - **Examples**: [examples.md](examples.md)
 
 A search endpoint, linked to from the STAC landing page, provides the ability to query STAC `Items` across collections.
-It retrieves a group of Items that match the provided parameters, wrapped in an ItemCollection (which is a 
+It retrieves a group of Items that match the provided parameters, wrapped in an [ItemCollection](../core/itemcollection-spec.md) (which is a 
 valid [GeoJSON FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that contains STAC Items). Several core
 query parameters are defined by [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), with
 a few additions specified in this document.
@@ -72,7 +72,8 @@ should be returned. See [examples](examples.md) to see sample requests.
 
 ## Response
 
-The response to a request (GET or POST) to the search endpoint should always be an `ItemCollection` - a valid [GeoJSON 
+The response to a request (GET or POST) to the search endpoint should always be an 
+`[ItemCollection](../core/itemcollection-spec.md)` - a valid [GeoJSON 
 FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that consists entirely of STAC 
 [Items](../stac-spec/item-spec/item-spec.md). 
 

item-search/openapi.yaml

@@ -49,7 +49,7 @@ paths:
             application/geo+json:
               schema:
                 allOf:
-                - $ref: '../core/commons.yaml#/components/schemas/itemCollection'
+                - $ref: '../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection'
                 # extensions
                 - $ref: '../fragments/context/openapi.yaml#/components/schemas/itemCollection'
             text/html:
@@ -86,7 +86,7 @@ paths:
           content:
             application/geo+json:
               schema:
-                $ref: '../core/commons.yaml#/components/schemas/itemCollection'
+                $ref: '../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection'
             text/html:
               schema:
                 type: string

ogcapi-features/README.md

@@ -34,7 +34,7 @@ The core OGC API - Features endpoints are shown below, with details provided in
 | `/conformance`                                  | JSON             | Info about standards to which the API conforms |
 | `/collections`                                  | JSON             | Object with a list of Collections contained in the catalog and links |
 | `/collections/{collectionId}`                   | Collection       | Returns single Collection JSON |
-| `/collections/{collectionId}/items`             | ItemCollection   | GeoJSON FeatureCollection-conformant entity of Items in collection |
+| `/collections/{collectionId}/items`             | [ItemCollection](../core/itemcollection-spec.md)   | GeoJSON FeatureCollection-conformant entity of Items in collection |
 | `/collections/{collectionId}/items/{featureId}` | Item             | Returns single Item (GeoJSON Feature) |
 | `/api`                                          | OpenAPI 3.0 JSON | Returns an OpenAPI description of the service from the `service-desc` link `rel` - not required to be `/api`, but the document is required |
 

ogcapi-features/extensions/transaction/openapi.yaml

@@ -32,7 +32,7 @@ paths:
             schema:
                 oneOf:
                  - $ref: '../../../core/commons.yaml#/components/schemas/item'
-                 - $ref: '../../../core/commons.yaml#/components/schemas/itemCollection'
+                 - $ref: '../../../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection'
       responses:
         '201':
           description: Status of the create request.

overview.md

@@ -59,7 +59,7 @@ column is more of an example in most cases. OGC API makes some endpoint location
 | Endpoint                                        | Link Relationship  | Returns                                           | Description |
 | ----------------------------------------------- | ------------------ | ------------------------------------------------- | ----------- |
 | `/`                                             | root               | [Catalog](stac-spec/catalog-spec/catalog-spec.md) | Extends `/` from OAFeat to return a full STAC catalog. |
-| `/search`                                       | search             | ItemCollection | Retrieves a group of Items matching the provided search predicates, probably containing search metadata from the `search` extension |
+| `/search`                                       | search             | [ItemCollection](core/itemcollection-spec.md) | Retrieves a group of Items matching the provided search predicates, probably containing search metadata from the `search` extension |
 | **`/collections`**                                  | data               | JSON           | Object with a list of Collections contained in the catalog and links |
 | **`/conformance`**                              | conformance        | JSON | Info about standards to which the API conforms |
 | `/api`                                          | service-desc       | OpenAPI 3.0 JSON | The OpenAPI definition of the endpoints in this service            |