Merge pull request #80 from radiantearth/beta.1-refinement

Beta.1 refinement

.github/pull_request_template.md

@@ -11,4 +11,3 @@
 - [ ] This PR is made against the dev branch (all proposed changes except releases should be against dev, not master).
 - [ ] This PR has **no** breaking changes.
 - [ ] I have added my changes to the [CHANGELOG](https://github.com/radiantearth/stac-api-spec/blob/dev/CHANGELOG.md) **or** a CHANGELOG entry is not required.
-- [ ] OpenAPI files only: I have run `npm run generate-all` to update the [generated OpenAPI files](https://github.com/radiantearth/stac-api-spec/blob/dev/README.md#openapi-definitions).

CHANGELOG.md

@@ -8,8 +8,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - The landing page returns the conformance classes in a property `conformsTo`, which mirrors `GET /conformances` from OGC APIs.
+- Conformance classes for all the major functionality and extensions, to be referenced in a new `conformsTo` JSON object in the landing page.
+- Fragments: reusable OpenAPI documents for sort, filter, fields and context, along with explanation of how they work.
+- ItemCollection moved from [STAC Core](https://github.com/radiantearth/stac-spec/blob/v0.9.0/item-spec/itemcollection-spec.md) to this repo.
 
 ### Changed
+- Major re-organization of the content and directory structure to make better conformance classes.
+  - STAC API Core is the landing page (a STAC catalog and conformance information).
+  - Item Search is the `search` cross-collection item search resource.
+  - STAC API - Features is the OGC API - Features standards to be used in a STAC API.
+  - Extensions are specified in the relevant functionality directory, though they can share openapi yaml's in the 'fragments' directory.
 - Updated to STAC specification version 1.0.0-beta.2
 - Named explicit supported STAC core versions to be from 0.9.0 up to (and not including) 2.0.0
 - Context Extension OpenAPI spec was updated to remove the no longer used `next` attribute

CONTRIBUTING.md

@@ -22,57 +22,61 @@ where a new change in one part of the spec might not yet be fully updated everyw
 a release. Once all the major issues are resolved the core team makes sure everything is consistent across the spec and
 examples.
 
-Any changes to the spec must be made as pull requests to the `dev` branch. Anyone is welcome and encouraged to bring ideas
-and improvements, to the issue tracker or (ideally) as pull requests. To merge a new pull request the work must be reviewed
-by at least two members of the STAC spec core team (who have write access to the main repository). It also must pass the
-Continuous Integration testing.
+### Submitting Pull Requests
 
-### Working with the OpenAPI files
+Any proposed changes to the specification should be done as pull requests. Please make these
+requests against the [`dev`](https://github.com/radiantearth/stac-api-spec/tree/dev) branch (this will
+require you to switch from the default of 'master', which we keep so it displays first). 
 
-The definitive specification for STAC API is provided as an [OpenAPI](http://openapis.org/) 3.0 specification that is
-contained within several YAML files in the various directories.
+Creating a Pull Request will show our PR template, which includes checkbox reminders for a number
+of things.
 
-TODO: Update with the latest folders / structure, and update the below instructions if they change
+- Adding an entry the [CHANGELOG](CHANGELOG.md). If the change is more editorial and minor then this 
+is not required, but any change to the actual specification should definitely have one.
+- Base the PR against dev, as mentioned above - even if the branch was made off of dev this reminds
+you to change the base in GitHub's PR creation page.
+- Highlight if the PR makes breaking changes to the specification (in beta there can still be
+select breaking changes, but after 1.0 this will change)
 
-```bash
-npm install
-npm run generate-all
-```
+All pull requests should submit clean markdown, which is checked by the continuous integration
+system. Please use `npm run check-markdown` locally, as described in the [next section](#using-check-markdown-locally), 
+to ensure that the checks on the pull request succeed. If it does not then you can look at the
+mistakes online, which are the same as running `check-markdown` locally would surface.
 
-You can also dynamically serve a human-readable version of your edited files at `http://127.0.0.1:8080` using the following commands:
-- Only the core STAC API:
-  ```bash
-  npm install
-  npm run serve
-  ```
-- The STAC API including all extensions:
-  ```bash
-  npm install
-  npm run serve-ext
-  ```
-
-Create your own OpenAPI document by combining the STAC definition with the extensions you want by creating a `myapi.merge.yaml` file.
-This file should contain a line indicating the files that need to be merged:
-
-```yaml
-!!files_merge_append ["STAC.yaml", "extensions/query/query.fragment.yaml"]
-```
+All pull requests that modify or create JSON examples should use [JSON 
+formatter](https://jsonformatter.org/) to keep files consistent across the repo. 
 
-Then, run the [yaml-files](https://www.npmjs.com/package/yaml-files) command line tool:
+All pull requests additionally require a review of two STAC core team members. Releases are cut
+from dev to master (and require 3 approvals).
 
-```bash
-npm -g install
-yaml-files myapi.merge.yaml myapi.yaml
-```
+### Using check-markdown locally
+
+The same check-markdown program that runs as a check on PR's is part of the repo and can be run locally. 
+To install you'll need npm, which is a standard part of any [node.js installation](https://nodejs.org/en/download/). 
+Alternatively, you can also use [yarn](https://yarnpkg.com/) instead of npm. In this case replace all occurrences of 
+`npm` with `yarn` below.
 
-The commands above require root/administrator level access to install the npm packages globally.
-If you do not have the required permissions or do not want to install the packages globally for any other reason check the
-npm documentation for your platform for instructions to install and run local packages. Unix bash users for instance may use:
+First you'll need to install everything with npm once. Just navigate to the root of the stac-spec repo and on 
+your command line run:
 
 ```bash
 npm install
-$(npm bin)/yaml-files myapi.merge.yaml myapi.yaml
 ```
+Then to do the check on your markdown you run:
+
+```bash
+npm run check-markdown
+```
+
+This will spit out the same text that you see online, and you can then go and fix your markdown.
+
+### Working with the OpenAPI files
+
+The definitive specification for STAC API is provided as an [OpenAPI](http://openapis.org/) 3.0 specification that is
+contained within several YAML files in the various directories. These live in the same place as the markdown defining
+various parts of the specification. Currently we expect developers to be up to speed with
+OpenAPI and using their own tools to modify things. In the future we will provide tools to make it easier to work with.
+We do publish full OpenAPI files online, at TODO: Matt to add final location.
 
 ## Release Process
 

README.md

@@ -10,7 +10,7 @@ time. The core STAC specification lives at [gitub.com/radiantearth/stac-spec](ht
 
 A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md), 
 [Collection](stac-spec/collection-spec/collection-spec.md), [Item](stac-spec/item-spec/item-spec.md), 
-or ItemCollection, depending on the endpoint.
+or a STAC API [ItemCollection](core/itemcollection.md), depending on the endpoint.
 Catalogs and Collections are JSON, while Items and ItemCollections are GeoJSON-compliant entities with foreign members.  
 Typically, a Feature is used when returning a single Item, and FeatureCollection when multiple Items (rather than a JSON array of Item entities).
 
@@ -25,10 +25,8 @@ The specification for STAC API is provided as an [OpenAPI](http://openapis.org/)
 
 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.
+Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) Version 1.0, and we are working to stay aligned
+as the additional OGC API components mature. This may result in minor changes as things evolve.
 
 ## Communication
 
@@ -42,19 +40,29 @@ the specification takes place in the [issue tracker](https://github.com/radiante
 The **[Overview](overview.md)** document describes all the various parts of the STAC API and how they fit together.
 
 **STAC API - Core Specification:**
-The main description of the core STAC API specification is in the *[core](core/)* folder and
-allows browsing catalogs and retrieving the API capabilities.
-An implementation will most always add extensions for broader functionality than just browsing catalogs.
+The *[core](core/)* folder describes the core STAC API specification that enables browsing catalogs and 
+retrieving the API capabilities. This includes the OpenAPI schemas for STAC items, catalogs and collections.
+
+**STAC API - Item Search Specification:**
+The *[item-search](item-search)* folder contains the Item Search specification, which enables 
+cross-collection search of STAC Items at a `search` endpoint, as well as a number of extensions. 
+
+**STAC API - Features:**
+The *[ogcapi-features](ogcapi-features)* folder describes how a STAC API can fully implement [OGC API - 
+Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) to expose individual `items` endpoints for search of
+each STAC collection. It also includes extensions that can be used to further enhance OAFeat.
 
 **Extensions:**
-The [extensions/](extensions.md) document links to additional capabilities that can be added to enrich the functionality of STAC API - Core.
-OpenAPI YAML documents are provided for each extension with additional documentation and examples provided in a README.
+The *[extensions](extensions.md) document* describes how STAC incubates new functionality, and it links to the existing
+
+extensions that can be added to enrich the functionality of a STAC API. Each has an OpenAPI yaml, but some of the yaml
+documents live as fragments in the [fragments/](fragments/) folder.
 
 **Fragments:**
-The [fragments/](fragments/) folder contains re-usable building blocks to be used in STAC API - Core and STAC API extensions.
-This includes the OpenAPI schemas for items, catalogs and collections, but also common schemas and parameters for behavior like 
-sorting and querying. Most all of them are compatible with OGC API - Features, and the plan is to fully align the relevant 
-functionality and have it be useful for all OAFeat implementations.
+The *[fragments/](fragments/)* folder contains re-usable building blocks to be used in a STAC API, including common OpenAPI 
+schemas and parameters for behavior like sorting and filtering. Most all of them are compatible with 
+OGC API - Features, and the plan is to fully align the relevant functionality and have it be useful for all OAFeat implementations.
+OpenAPI YAML documents are provided for each extension with additional documentation and examples provided in a README.
 
 **STAC Specification:** This repository includes a '[sub-module](https://git-scm.com/book/en/v2/Git-Tools-Submodules)', which
 is a copy of the [STAC specification](stac-spec/) tagged at the latest stable version.

core/README.md

@@ -3,6 +3,8 @@
 - **Conformance URI:** <http://stacspec.org/spec/api/1.0.0-beta.1/core>
 - **Extension [Maturity Classification](../extensions.md#extension-maturity):** Pilot
 - **Dependencies**: None
+- **OpenAPI Specifications**: [openapi.yaml](openapi.yaml) describes the core endpoints, and [commons.yaml](commons.yaml) is the OpenAPI 
+    version of the core [STAC spec](../stac-spec) JSON Schemas.
 
 The core of a STAC API is its landing page, which is the starting point to discover STAC data and what the API supports.