Conformance

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+ - Clearer language on compliance requirements
 
 ### Changed
 - Context Extension OpenAPI spec was updated to remove the no longer used `next` attribute

README.md

@@ -20,15 +20,14 @@ compatible and usable with any OGC API - Features clients. The STAC API can be t
 to search STAC Catalogs, where the features returned are STAC [Items](https://github.com/radiantearth/stac-spec/item-spec/item-spec.md), 
 that have common properties, links to their assets and geometries that represent the footprints of the geospatial assets.
 
-## WARNING
-
-This specification is approaching maturity, but will likely have some minor changes as we approach the 1.0-beta release and 
-fully align with [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html). This repo was also recently 
-split off from the main [stac-spec repository](https://github.com/radiantearth/stac-spec). Not all links and references have 
-been updated yet so should be considered a work in progress. To implement against a stable STAC API we recommend using 
-[STAC API Version 0.9.0](https://github.com/radiantearth/stac-spec/tree/v0.9.0/api-spec). This master branch will be 
-considered to be under active development until we release version 1.0-beta, at which time it will be stable, and a `dev` 
-branch will be created for active development.
+## Stability Note
+
+This specification has evolved over the past couple years, and is used in production in a variety of deployments. It is 
+currently in a 'beta' state, with no major changes anticipated. For 1.0-beta we remain fully aligned with  [OGC API - 
+Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) Version 1.0. We have further aligned STAC extensions
+with OGC API - Features extensions, particularly [CQL](https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/cql/)
+and [Transactions](https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/transactions). These are not
+yet entirely stable, so if they change then STAC will update to remain in line.
 
 ## Communication
 

api-spec.md

@@ -1,17 +1,27 @@
 # STAC API Specification
 
-The STAC API is intended to be a superset of the *OGC API - Features - Part 1: Core* (OAFeat) standard. STAC API 
-currently is based on [OAFeat version 1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), previously known as 
-OGC Web Feature Service (WFS). Future STAC API releases will align with 
-[upcoming versions](https://github.com/opengeospatial/ogcapi-features).
+## About
+
+The STAC API defines a RESTful JSON-based server to query [SpatioTemporal Asset Catalogs](https://github.com/radiantearth/stac-spec/) 
+(STAC). While the core STAC specification provides a structure and language to describe assets, users usually want to access
+a subset of the entire catalog, such as for a certain date range, in a particular area of interest, or matching properties
+they care about. STAC API specifies those query parameters, and compliant servers return collections of STAC Items that
+match the user's preferences.
+
+## STAC API and OGC API - Features
+
+The vast majority of what STAC API does is specified in the *[OGC API - Features](https://ogcapi.ogc.org/features/)*
+standard ('OAFeat' for our shorthand). STAC API is fully compliant with [OAFeat - Part 1: Core, version 
+1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), and will be aligned with their additional extensions
+when they are finalized. Future STAC API releases will align with [upcoming versions](https://github.com/opengeospatial/ogcapi-features).
+STAC API adds certain requirements and extensions on top of the OAFeat core, to meet its community's use cases, detailed below.
 
 The OGC API - Features is a standard API that represents collections of geospatial data. It defines the RESTful interface 
 to query geospatial data, with GeoJSON as a main return type. With OAFeat you can return any `Feature`, which is a geometry 
 plus any number of properties. The core [STAC Item spec](https://github.com/radiantearth/stac-spec/item-spec/README.md) 
 enhances the core `Feature` with additional requirements and options to enable cataloging of spatiotemporal 'assets' like 
 satellite imagery. This STAC `Item` always links to an asset, and these assets always have a capture time, so it requires 
-fields for `datetime` and `assets`. The STAC API extends the OAFeat core with some key functionality to enable search of 
-geospatial assets, detailed below.
+fields for `datetime` and `assets`. 
 
 OAFeat also defines the concept of a Collection, which contains Features. In OAFeat Collections are the sets of data that can 
 be queried ([7.11](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collections_)), and each describes basic 
@@ -21,15 +31,19 @@ information, along with other STAC specific fields to provide additional metadat
 thus are compliant with both OAFeat Collections and STAC Collections and are returned from the `/collections/{collection_id}` 
 endpoint.
 
-In OAFeat Features are the individual records within a Collection and are provided in GeoJSON format. 
-[STAC Items](https://github.com/radiantearth/stac-spec/item-spec/README.md) are analogous to OAFeat Features, 
-are in GeoJSON, and are returned from the `/collections/{collection_id}/items/{item_id}` endpoint.
+In OAFeat Features are the individual records within a Collection and are usually provided in GeoJSON format. 
+[STAC Items](https://github.com/radiantearth/stac-spec/item-spec/README.md) are compliant with the OAFeat Features [GeoJSON
+requirements class](http://docs.ogc.org/is/17-069r3/17-069r3.html#_requirements_class_geojson),  and are returned from the 
+`/collections/{collection_id}/items/{item_id}` endpoint. The return of other encodings 
+([html](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_html), [gml](http://docs.ogc.org/is/17-069r3/17-069r3.html#rc_gmlsf0))
+is outside the scope of STAC API, as the [STAC Item](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md) is
+specified in GeoJSON.
 
 A typical OAFeat will have multiple collections, and each will just offer simple search for its particular collection at 
 `GET /collections/{collectionId}/items`.
 The main STAC endpoint specified beyond what OAFeat offers is `/search`, which offers cross-collection search. A primary
 use case of STAC is to search diverse imagery collections (like Landsat, Sentinel, MODIS) by location and cloud cover for any
-relevant image. So the ability to do searches across Collections is required, and is not yet specified by OAFeat. Due to the 
+relevant image. So the ability to do searches across Collections is very important, and is not yet specified by OAFeat. Due to the 
 limited parameter support in OGC API - Features, it is recommended to use the STAC API endpoint 
 `POST /search` for advanced queries, as it supports richer options.
 The filtering is made to be compatible between STAC API and OGC API - Features whenever feasible, and the two specs seek 
@@ -40,6 +54,23 @@ Implementations may **optionally** provide support for the full superset of STAC
 where the collection ID in the path is equivalent to providing that single value in the `collections` query parameter in 
 STAC API.
 
+### STAC API Compliance
+
+To be a compliant STAC API an implementation must either:
+
+1) Fully implement [OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) core, and have one or more
+[Feature Collections](http://docs.ogc.org/is/17-069r3/17-069r3.html#_collections_) implement STAC 
+[Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md), with its returned 
+[Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_) as valid STAC 
+[Items](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md).
+2) Implement the [STAC API Endpoints](#stac-api-endpoints), with `/` returning valid STAC 
+[Catalogs](https://github.com/radiantearth/stac-spec/blob/master/catalog-spec/catalog-spec.md) and `/search` returning valid
+[Items](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md).
+
+The recommendation is to implement both, with `/search` providing cross-collection search and then having each 
+`/collections/{collectionId}` describe a homogeneous set of STAC Items, but only one of the two is required to be a
+valid STAC API implementation.
+
 ## HTTP Request Methods and Content Types
 
 The OAFeat and STAC APIs follow a RESTful model. A core principal of this is the use of HTTP Request Methods ("verbs") and