Minor clean-up and more intro

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## \[Unreleased\]
 
 ### Added
+- More intro text
 
 ### Changed
 - Updated to STAC specification version 1.0.0-beta.2

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 
+matching item. 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 
@@ -195,7 +209,7 @@ with a single value array in JSON if the same functionality is desired. For filt
 query parameters should use comma-separated string values (with no outer brackets \[ or \]) and JSON entity 
 attributes should use JSON Arrays. 
 
-### Examples
+### Query Examples
 
 ```http
 GET /search?collections=landsat8,sentinel&bbox=-10.415,36.066,3.779,44.213&limit=200&datetime=2017-05-05T00:00:00Z
@@ -210,6 +224,8 @@ GET /search?collections=landsat8,sentinel&bbox=-10.415,36.066,3.779,44.213&limit
 }
 ```
 
+### Query Parameter Table
+
 | Parameter    | Type             | APIs         | Description |
 | -----------  | ---------------- | ------------ | ----------- |
 | collectionId | string           | OAFeat       | **Path-only** Single Collection ID to include in the search for items. Only Items in one of the provided Collection will be searched |