Skip to content

Commit 3a5f69c

Browse files
philvarnerphilvarner
committed
update linting, dep versions, add x-conformance-class and other headmatter to schema
1 parent ec9a58b commit 3a5f69c

File tree

6 files changed

+4983
-720
lines changed

6 files changed

+4983
-720
lines changed

‎.circleci/.spectral-fragments.yml‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎.circleci/.spectral.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
extends: "spectral:oas"
22
rules:
3+
openapi-tags: off
4+
info-contact: off
35
oas3-api-servers: off
46
oas3-schema: warn
57
tag-description: true
6-
oas3-parameter-description: true
8+
oas3-parameter-description: true
9+
oas3-unused-component: off
10+
operation-operationId: off

‎README.md‎

Lines changed: 34 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,13 @@
33
- [STAC API - Fields Extension Specification](#stac-api---fields-extension-specification)
44
- [Overview](#overview)
55
- [Include/Exclude Semantics](#includeexclude-semantics)
6+
- [`null` vs. empty vs. missing](#null-vs-empty-vs-missing)
67
- [Examples](#examples)
8+
- [Default fields](#default-fields)
9+
- [Explicitly get a valid STAC Item](#explicitly-get-a-valid-stac-item)
10+
- [Exclude geometry](#exclude-geometry)
11+
- [Minimal subset](#minimal-subset)
12+
- [Exclude a nested fiels](#exclude-a-nested-fiels)
713

814
## Overview
915

@@ -71,29 +77,32 @@ name, e.g., `properties.datetime` or `datetime`.
7177

7278
## Include/Exclude Semantics
7379

74-
1. If `fields` attribute is specified as an empty string (GET requests) or as an empty object or an object with both `include` and `exclude` set to either null or an
75-
empty array (for POST requests), then the recommended behavior is to include only fields
76-
`type`, `stac_version`, `id`, `geometry`, `bbox`, `links`, `assets`, and `properties.datetime`. If `properties.datetime` is null, then it is recommended to include `properties.start_datetime` and `properties.end_datetime`.
77-
These are the default fields to ensure a valid STAC Item is returned by default.
78-
Implementations may choose to include other properties, e.g., `properties.created`, but the number
79-
of default properties fields should be kept to a minimum.
80+
1. If `fields` attribute is specified as an empty string (GET requests) or as an
81+
empty object or an object with both `include` and `exclude` set to either null
82+
or an empty array (for POST requests), then the recommended behavior is to include
83+
only fields `type`, `stac_version`, `id`, `geometry`, `bbox`, `links`, `assets`,
84+
and `properties.datetime`. If `properties.datetime` is null, then it is recommended
85+
to include `properties.start_datetime` and `properties.end_datetime`.
86+
These are the default fields to ensure a valid STAC Item is returned by default.
87+
Implementations may choose to include other properties, e.g., `properties.created`,
88+
but the number of default properties fields should be kept to a minimum.
8089
2. If only `include` is specified, these fields should be the only fields included.
81-
Any additional fields provided beyond those in the `include` list should be kept
82-
to a minimum, as the caller has explicitly stated they do not need them.
90+
Any additional fields provided beyond those in the `include` list should be kept
91+
to a minimum, as the caller has explicitly stated they do not need them.
8392
3. If only `exclude` is specified, the specified fields should not be
84-
included, but every other field available for the
85-
Item should be included.
93+
included, but every other field available for the
94+
Item should be included.
8695
4. If `exclude` is specified and `include` is null or an empty
87-
array, then the `exclude` fields should be excluded from the default set.
96+
array, then the `exclude` fields should be excluded from the default set.
8897
5. For nested fields (e.g., `properties.datetime`), the most specific path
89-
should be honored first, and `include` should be preferred over `exclude`. For
90-
example:
91-
1. If a field is in `exclude`, and a nested field of that field is in
98+
should be honored first, and `include` should be preferred over `exclude`. For
99+
example:
100+
1. If a field is in `exclude`, and a nested field of that field is in
92101
`include`, the nested field should be included, but no other nested
93102
fields in the field should be included. For example, if `properties` is
94103
excluded and `properties.datetime` is included, then `datetime`
95104
should be the only nested field in `properties`.
96-
2. If a field is in `include`, and a nested field of that field is in `exclude`, the field
105+
2. If a field is in `include`, and a nested field of that field is in `exclude`, the field
97106
should be included, and the nested field should be excluded. For example,
98107
if `properties` is included and `properties.datetime` is excluded, then
99108
`datetime` should not be in `properties`, but every other nested field should be.
@@ -109,16 +118,16 @@ above](#includeexclude-semantics), but is summarized here for reference. "ALL"
109118
means that all of the Item's fields should be returned; "DEFAULT" means the
110119
default set (i.e. the required fields for a valid STAC Item) should be returned.
111120

112-
| include | exclude | returned |
113-
| -- | -- | -- |
114-
| missing, `null`, or empty | missing, `null`, or empty | DEFAULT |
115-
| ["a", "b"] | missing, `null`, or empty | ["a", "b"] |
116-
| missing | ["a", "b"] | ALL except for ["a", "b"] |
117-
| `null` or empty | ["a", "b"] | DEFAULT except for ["a", "b"] |
118-
| ["a", "b"] | ["a"] | ["a", "b"] |
119-
| ["a"] | ["a", "b"] | ["a"] |
120-
| ["a.b"] | ["a"] | `a.b` should be the only field in `a` |
121-
| ["a"] | ["a.b"] | `a` should be included, but it should not include `a.b` |
121+
| include | exclude | returned |
122+
| ------------------------- | ------------------------- | ------------------------------------------------------- |
123+
| missing, `null`, or empty | missing, `null`, or empty | DEFAULT |
124+
| ["a", "b"] | missing, `null`, or empty | ["a", "b"] |
125+
| missing | ["a", "b"] | ALL except for ["a", "b"] |
126+
| `null` or empty | ["a", "b"] | DEFAULT except for ["a", "b"] |
127+
| ["a", "b"] | ["a"] | ["a", "b"] |
128+
| ["a"] | ["a", "b"] | ["a"] |
129+
| ["a.b"] | ["a"] | `a.b` should be the only field in `a` |
130+
| ["a"] | ["a.b"] | `a` should be included, but it should not include `a.b` |
122131

123132
In this example, `include` is missing:
124133

‎openapi.yaml‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,17 @@
11
openapi: 3.0.3
22
info:
3-
title: The SpatioTemporal Asset Catalog API - Fields
4-
description: Adds parameter to control which fields are returned in the response.
3+
title: STAC API - Fields Extension
54
version: 1.0.0-rc.2
5+
description: Adds parameter to control which fields are returned in the response.
6+
contact:
7+
name: STAC Specification
8+
url: 'http://stacspec.org'
9+
license:
10+
name: Apache License 2.0
11+
url: 'http://www.apache.org/licenses/LICENSE-2.0'
12+
x-conformance-classes:
13+
- 'https://api.stacspec.org/v1.0.0-rc.2/item-search#fields'
14+
- 'https://api.stacspec.org/v1.0.0-rc.2/ogcapi-features#fields'
615
paths: {}
716
components:
817
parameters:

0 commit comments

Comments
 (0)