Skip to content

Commit 73f8152

Browse files
philvarnerphilvarner
authored
Merge pull request #247 from radiantearth/dev
Merge dev to master for 1.0.0-beta.5
2 parents 0f1ff40 + ea8d930 commit 73f8152

36 files changed

+1676
-731
lines changed

‎CHANGELOG.md

+52-2
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,63 @@ All notable changes to this project will be documented in this file.
44
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
55
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
66

7+
## [v1.0.0-beta.5 - Unreleased] - TBD
78

8-
## [v1.0.0-beta4] - 2020-10-05
9+
### Added
10+
11+
- Added `STAC API - Browseable` conformance class
12+
- Added `STAC API - Children` conformance class
13+
- Added description of how to support both search and browse in an API.
14+
- The paging mechanism via a Link with rel `next` or `prev` as defined for Item Search can also be used
15+
for the STAC API - Features endpoint `/collections/{collection_id}/items`, as described in OAFeat.
16+
- The paging mechanism via a Link with rel `next` or `prev` as defined for items can also be used
17+
for the STAC API - Features and STAC API - Collections endpoint `/collections`.
18+
19+
### Changed
20+
21+
- Limit parameter semantics now match OAFeat. Previously, the behavior was not precisely defined.
22+
- Filter Extension updates to align with changes to OAFeat CQL2 spec
23+
- Updated all "CQL" usages to "CQL2"
24+
- Most conformance class URIs are now prefixed with `http://www.opengis.net/spec/cql2/` instead
25+
of `http://www.opengis.net/spec/ogcapi-features-3/`
26+
- Conformance classes `http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/basic-cql`,
27+
`http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/cql-text`, and
28+
`http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/cql-json` have had `cql` replaced
29+
with `cql2` (in addition to the prefix change) to
30+
become `http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2`,
31+
`http://www.opengis.net/spec/cql2/1.0/conf/cql2-text`, and
32+
`http://www.opengis.net/spec/cql2/1.0/conf/cql2-json`
33+
- Significant changes to CQL2 JSON format, now using `op` and `args` structure
34+
- Spatial operator `INTERSECTS` is now `S_INTERSECTS`
35+
- Temporal operator `ANYINTERACTS` is now `T_INTERSECTS`
36+
- Updated Example 3 (now Example 5) to make it clear that property to property comparisons require the
37+
Property-Property Comparisons conformance class
38+
- The CQL2 Case-insensitive Comparison
39+
(`http://www.opengis.net/spec/cql2/1.0/conf/case-insensitive-comparison`) conformance class
40+
that adds UPPER/LOWER terms or function CASEI for case-insensitive comparison has not been added
41+
to this spec yet, since the definition in CQL2 is in flux.
42+
- `service-desc` endpoint may return any service description format, typically a
43+
machine-consumable one (previous restricted required to be OpenAPI 3.0 JSON)
44+
- `service-doc` endpoint may return any service description format, typically a
45+
human-consumable one (previous restricted required to be HTML)
46+
47+
### Deprecated
48+
49+
### Removed
50+
51+
### Fixed
52+
53+
- Collection conformance class URI should be `https://api.stacspec.org/v1.0.0-beta.XXX/collections` instead
54+
of `http://stacspec.org/spec/api/1.0.0-beta.XXX/extensions/collections`
55+
- definition of Item object was missing `properties` as an attribute
56+
- Filter Extension - examples of using intervals and timestamps in CQL2 were incorrect and have been fixed
57+
58+
## [v1.0.0-beta.4] - 2020-10-05
959

1060
### Added
1161

1262
- Support binding Sort, Fields, and Context Extensions to STAC Features items resource
13-
endpoint (`/collections/{collection_id}/items`)
63+
endpoint (`/collections/{collectionId}/items`)
1464
- In Collections, added `canonical` rel type, added `/` and `/api` to list of endpoints
1565
- In Item Search, added endpoint table
1666

‎PRINCIPLES.md

+16-6
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,22 @@ core geospatial standards.
99
The collaboration facilities of Github should be used to their full extent. All proposed improvements and
1010
changes should come in the form of pull requests, using code review functionality to discuss changes.
1111

12-
- **JSON + REST + HTTP at the core.** JSON has won over XML, and REST over SOAP. We embrace them and
12+
- **Alignment with OGC standards** - The Open Geospatial Consortium publishes a large set of geospatial standards.
13+
To the greatest extent possible, the STAC API should align with existing and in-progress OGC API standards. The
14+
STAC API has a symbiotic relationship with these standards, as it seeks both to reuse their building blocks and
15+
push them forward in a practical direction. Among the most important of these are:
16+
- [OGC API - Common](https://ogcapi.ogc.org/common/)
17+
- [OGC API - Features](https://ogcapi.ogc.org/features/), particularly [OGC API - Features - Part 1: Core](http://docs.ogc.org/is/17-069r3/17-069r3.html)
18+
- [OGC API - Records](https://ogcapi.ogc.org/records/)
19+
- [Common Query Language (CQL2)](https://docs.ogc.org/DRAFTS/21-065.html), formerly part of OGC
20+
API - Features - Part 3: Filtering and the Common Query Language (CQL)
21+
22+
- **Web API using JSON + HTTP at the core.** JSON has won over XML, and resource-centric over SOAP. We embrace them and
1323
are not considering legacy options. Forward looking protocols can be considered as extensions,
14-
but the default specifications should be in JSON, following best REST practices. HTTP caching and
24+
but the default specifications should be in JSON, following best web API practices. HTTP caching and
1525
error codes should be leveraged at the core. GeoJSON has already defined the core geospatial JSON response,
16-
so it should also be core. As STAC APIs follow a RESTful model, a core principal is the use of HTTP Request Methods ("verbs") and
17-
the `Content-Type` header to drive behavior on resources ("nouns").
26+
so it should also be core. As STAC APIs follow a resource-centric, hypermedia-driven model, a core principal
27+
is the use of HTTP Request Methods ("verbs") and the `Content-Type` header to drive behavior on resources ("nouns").
1828

1929
- **Small Reusable Pieces Loosely Coupled** - Each specification should be as focused as possible,
2030
defining one core concept and refraining from describing lots of options. Additional options can be made
@@ -36,8 +46,8 @@ for data in a different projection.
3646

3747
- **Working code required.** Proposed changes should be accompanied by working code
3848
(ideally with a link to an online service running the code). A reference implementation should be available
39-
online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations
40-
that cover the entire specification. Extensions have their own [Extention Maturity](extensions.md#extension-maturity) model.
49+
online to power the interactive documentation. Both core conformance classes and extensions follow the
50+
[Maturity Classification](README.md#maturity-classification) model.
4151

4252
- **Design for scale.** The design should work great with more data than can be imagined right now.
4353
Ideally implementations are built with large test data sets to validate that they will work.

‎README.md

+45-9
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,16 @@
66
- [STAC API](#stac-api)
77
- [About](#about)
88
- [Stability Note](#stability-note)
9+
- [Maturity Classification](#maturity-classification)
910
- [Communication](#communication)
1011
- [In this repository](#in-this-repository)
1112
- [Contributing](#contributing)
1213

1314
## About
1415

15-
The SpatioTemporal Asset Catalog (STAC) specification aims to standardize the way geospatial assets are exposed online and queried.
16+
The SpatioTemporal Asset Catalog (STAC) family of specifications aim to standardize the way geospatial asset metadata is structured and queried.
1617
A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and
17-
time. The core STAC specification lives at [gitub.com/radiantearth/stac-spec](https://github.com/radiantearth/stac-spec).
18+
time. The core STAC specifications live in the GitHub repository [radiantearth/stac-spec](https://github.com/radiantearth/stac-spec).
1819

1920
A STAC API is the dynamic version of a SpatioTemporal Asset Catalog. It returns a STAC [Catalog](stac-spec/catalog-spec/catalog-spec.md),
2021
[Collection](stac-spec/collection-spec/collection-spec.md), [Item](stac-spec/item-spec/item-spec.md),
@@ -24,21 +25,45 @@ Typically, a Feature is used when returning a single Item object, and FeatureCol
2425
JSON array of Item entities).
2526

2627
The API can be implemented in compliance with the *[OGC API - Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)* standard
27-
(we'll use OAFeat for shorthand). In this case STAC API can be thought of as a specialized Features API
28+
(OAFeat is a shorthand). In this case STAC API can be thought of as a specialized Features API
29+
2830
to search STAC catalogs, where the features returned are STAC [Item](stac-spec/item-spec/item-spec.md) objects,
2931
that have common properties, links to their assets and geometries that represent the footprints of the geospatial assets.
3032

3133
The specification for STAC API is provided as files that follow the [OpenAPI](http://openapis.org/) 3.0 specification,
32-
rendered online into HTML at <https://api.stacspec.org/v1.0.0-beta.4>, in addition to human-readable documentation.
34+
rendered online into HTML at <https://api.stacspec.org/v1.0.0-beta.5>, in addition to human-readable documentation.
3335

3436
## Stability Note
3537

3638
This specification has evolved over the past couple years, and is used in production in a variety of deployments. It is
37-
currently in a 'beta' state, with no major changes anticipated. For 1.0-beta we remain fully aligned with [OGC API -
39+
currently in a 'beta' state, with no major changes anticipated. For 1.0.0-beta.5, we remain fully aligned with [OGC API -
3840
Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) Version 1.0, and we are working to stay aligned
3941
as the additional OGC API components mature. This may result in minor changes as things evolve. The STAC API
4042
specification follows [Semantic Versioning](https://semver.org/), so once 1.0.0 is reached any breaking change
41-
will require the spec to go to 2.0.0.
43+
will require the spec to go to 2.0.0.
44+
45+
## Maturity Classification
46+
47+
Conformance classes and extensions are meant to evolve to maturity, and thus may be in different states
48+
in terms of stability and number of implementations. All extensions must include a
49+
maturity classification, so that STAC API spec users can easily get a sense of how much they can count
50+
on the extension.
51+
52+
| Maturity Classification | Min Impl # | Description | Stability |
53+
| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
54+
| Proposal | 0 | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. |
55+
| Pilot | 1 | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback |
56+
| Candidate | 3 | A number of implementers are using it and are standing behind it as a solid extension. Can generally count on an extension at this maturity level | Mostly stable, breaking changes require a new version and minor changes are unlikely. |
57+
| Stable | 6 | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. |
58+
| Deprecated | N/A | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | Will not be updated and may be removed in an upcoming major release. |
59+
60+
Maturity mostly comes through diverse implementations, so the minimum number of implementations
61+
column is the main gating function for an extension to mature. But extension authors can also
62+
choose to hold back the maturity advancement if they don't feel they are yet ready to commit to
63+
the less breaking changes of the next level.
64+
65+
A 'mature' classification level will likely be added once there are extensions that have been
66+
stable for over a year and are used in twenty or more implementations.
4267

4368
## Communication
4469

@@ -55,15 +80,26 @@ The **[Overview](overview.md)** document describes all the various parts of the
5580
The *[core](core/)* folder describes the core STAC API specification that enables browsing catalogs and
5681
retrieving the API capabilities. This includes the OpenAPI schemas for STAC Item, Catalog and Collection objects.
5782

58-
**STAC API - Item Search Specification:**
59-
The *[item-search](item-search)* folder contains the Item Search specification, which enables
60-
cross-collection search of STAC Item objects at a `search` endpoint, as well as a number of extensions.
83+
**STAC API - Collections:**
84+
The *[collections](collections)* folder describes how a STAC API Catalog can advertise the Collections it contains.
6185

6286
**STAC API - Features:**
6387
The *[ogcapi-features](ogcapi-features)* folder describes how a STAC API can fully implement [OGC API -
6488
Features](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) to expose individual `items` endpoints for search of
6589
each STAC collection. It also includes extensions that can be used to further enhance OAFeat.
6690

91+
**STAC API - Item Search Specification:**
92+
The *[item-search](item-search)* folder contains the Item Search specification, which enables
93+
cross-collection search of STAC Item objects at a `search` endpoint, as well as a number of extensions.
94+
95+
**STAC API - Children:**
96+
The *[children](children)* folder describes how a STAC API Catalog can advertise the children (child catalogs or child collections)
97+
it contains.
98+
99+
**STAC API - Browseable:**
100+
The *[browseable](browseable)* folder describes how a STAC API Catalog can advertise that all Items can be accessed
101+
by following through `child` and `item` link relations.
102+
67103
**Extensions:**
68104
The *[extensions](extensions.md) document* describes how STAC incubates new functionality, and it links to the existing
69105
extensions that can be added to enrich the functionality of a STAC API. Each has an OpenAPI yaml, but some of the yaml

‎browseable/README.md

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# STAC API - Browseable Specification
2+
3+
- [STAC API - Browseable Specification](#stac-api---browseable-specification)
4+
- [Link Relations](#link-relations)
5+
- [Endpoints](#endpoints)
6+
- [Example Landing Page for STAC API - Browseable](#example-landing-page-for-stac-api---browseable)
7+
- [Extensions](#extensions)
8+
9+
- **OpenAPI specification:** none
10+
- **Conformance URIs:**
11+
- <https://api.stacspec.org/v1.0.0-beta.5/browseable>
12+
- <https://api.stacspec.org/v1.0.0-beta.5/core>
13+
- **[Maturity Classification](../README.md#maturity-classification):** Pilot
14+
- **Dependencies**: [STAC API - Core](../core)
15+
16+
A STAC API conforming to the `STAC API - Browseable` conformance class must be structured such that all
17+
all Items in the catalog can be accessed by following `child` and `item` link relations. This is a more significant
18+
constraint than a STAC API without this conformance class or a STAC Catalog that is available over HTTP but does not
19+
implement STAC API, neither of which have any guarantee regarding the reachability of Items. This conformance
20+
class is used to signal to users that they can fully navigate to all available Items using a UI (like [STAC Browser](https://github.com/radiantearth/stac-browser),
21+
and also makes it clear to crawlers that they can reach everything by following catalog links.
22+
23+
Recommendations for structuring Catalogs hierarchically can be found in
24+
[Structuring Catalog Hierarchies](../core/README.md#structuring-catalog-hierarchies) from the `STAC API - Core` specification.
25+
26+
## Link Relations
27+
28+
This conformance class also requires implementation of the link relations in the [STAC API - Core](../core) conformance class.
29+
30+
Additionally, `child` relations must exist to child Catalogs and Collections and `item` relations to Items, such that
31+
every Item in the Catalog can be accessed by traversing these relations.
32+
33+
| **rel** | **href** | **From** | **Description** |
34+
| ------- | -------- | --------- | -------------------------------------- |
35+
| `child` | various | STAC Core | The child STAC Catalogs & Collections. |
36+
| `item` | various | STAC Core | The child STAC Items. |
37+
38+
Note that there is a different link relation `items` (plural)
39+
used by the `STAC API - Features` conformance class that links from a collection resource
40+
(at the `/collections/{collectionId}` endpoint) to the items in
41+
that collection (at the `/collections/{collectionId}/items` endpoint). Both of these endpoints are
42+
[derived from OGC API - Features](https://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_items_).
43+
44+
## Endpoints
45+
46+
This conformance class also requires for the endpoints in the [STAC API - Core](../core) conformance class to be implemented.
47+
48+
This conformance class adds no additional endpoints.
49+
50+
## Example Landing Page for STAC API - Browseable
51+
52+
This JSON is what would be expected from an API that implements `STAC API - Browseable`. Note that the
53+
`conformsTo` array contains `https://api.stacspec.org/v1.0.0-beta.5/browseable` and the `links` array
54+
contains `child` link relations. The semantics of this conformance class imply that the the catalogs
55+
linked to by these `child` link relations then have further `child` or `item` link relations that
56+
eventually reach all items in this catalog.
57+
58+
```json
59+
{
60+
"stac_version": "1.0.0",
61+
"id": "example-stac",
62+
"title": "A simple STAC API Example, implementing STAC API - Browseable",
63+
"description": "This Catalog aims to demonstrate the a simple landing page",
64+
"type": "Catalog",
65+
"conformsTo" : [
66+
"https://api.stacspec.org/v1.0.0-beta.5/core",
67+
"https://api.stacspec.org/v1.0.0-beta.5/browseable"
68+
],
69+
"links": [
70+
{
71+
"rel": "self",
72+
"type": "application/json",
73+
"href": "https://stacserver.org"
74+
},
75+
{
76+
"rel": "root",
77+
"type": "application/json",
78+
"href": "https://stacserver.org"
79+
},
80+
{
81+
"rel": "service-desc",
82+
"type": "application/vnd.oai.openapi+json;version=3.0",
83+
"href": "https://stacserver.org/api"
84+
},
85+
{
86+
"rel": "service-doc",
87+
"type": "text/html",
88+
"href": "https://stacserver.org/api.html"
89+
},
90+
{
91+
"rel": "child",
92+
"type": "application/json",
93+
"href": "https://stacserver.org/catalogs/sentinel-2",
94+
},
95+
{
96+
"rel": "child",
97+
"type": "application/json",
98+
"href": "https://stacserver.org/catalogs/landsat-8",
99+
}
100+
]
101+
}
102+
```
103+
104+
## Extensions
105+
106+
None.

‎build/index.html

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ <h2>Conformance Classes</h2>
1616
<li><a href="core/">Core</a></li>
1717
<li><a href="item-search/">Item Search</a></li>
1818
<li><a href="ogcapi-features/">STAC Features</a></li>
19-
<li><a href="collections/"></a>Collections</li>
19+
<li><a href="collections/">Collections</a></li>
2020
</ul>
2121
</body>
2222

‎build/swagger-config.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
openapi: 3.0.3
22
info:
33
title: STAC API - Complete
4-
version: 1.0.0-beta.4
4+
version: 1.0.0-beta.5
55
apis:
66
- url: 'build/core/openapi.yaml'
77
paths:

0 commit comments

Comments
 (0)