Skip to content

Commit

Permalink
feat: change include/exclude recommendations
Browse files Browse the repository at this point in the history
  • Loading branch information
gadomski committed Feb 17, 2023
1 parent 99e3612 commit dd82a3f
Showing 1 changed file with 45 additions and 27 deletions.
72 changes: 45 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,44 +71,56 @@ name, e.g., `properties.datetime` or `datetime`.

## Include/Exclude Semantics

1. If `fields` attribute is specified with an empty object, or with both `include` and `exclude` set to null or an
empty array, the recommended behavior is as if `include` was set to
`["id", "type", "geometry", "bbox", "links", "assets", "properties.datetime"]`. This default is so that the entity
returned is a valid STAC Item. Implementations may choose to add other properties, e.g., `created`, but the number
1. If `fields` attribute is specified as an empty object (for POST requests), an empty string (for GET requests),
or with both `include` and `exclude` set to null or an
empty array, then the recommended behavior is to `include` the following keys:
`["id", "type", "geometry", "bbox", "links", "assets", "properties.datetime", "stac_version"]`.
This default is so that the entity returned is a valid STAC Item.
Implementations may choose to add other properties, e.g., `properties.created`, but the number
of default properties attributes should be kept to a minimum.
2. If only `include` is specified, these attributes are added to the default set of attributes (set union operation).
3. If only `exclude` is specified, these attributes are subtracted from the union of the default set of attributes and
the `include` attributes (set difference operation). This will result in an entity that is not a valid Item if any
of the excluded attributes are in the default set of attributes.
4. If both `include` and `exclude` attributes are specified, semantics are that a field must be included and **not**
excluded. E.g., if `properties` is included and `properties.datetime` is excluded, then `datetime` must not appear
in the attributes of `properties`.
2. If only `include` is specified, these attributes should be the only attributes included.
3. If only `exclude` is specified, these attributes are subtracted from the full item.
This may result in an entity that is not a valid STAC Item.
4. If `exclude` is specified and `include` is null or an empty
array, then the `exclude` attributes are subtracted from the default set.
This may result in an entity that is not a valid STAC Item.
5. If a key is in `exclude`, and a sub-key is in `include`, the sub-key should be included, but no other fields
in the key should be included. E.g., if `properties` is excluded and `properties.datetime` is included, then `datetime`
should be the only attribute in `properties`.
6. If a key is in `include`, and a sub-key is in `exclude`, the key should be included, and the sub-key should be excluded.
E.g., if `properties` is included and `properties.datetime` is excluded, then `datetime`
should not be in `properties`.
7. If the same attribute is present in both `include` and `exclude`, it should be included.

## Examples

Return baseline fields. This **must** return valid STAC Item entities.
Return the default fields. This should return valid STAC Item entities.

Query Parameters
```http

```text
?fields=
```

JSON

```json
{
"fields": {
}
}
```

This has a similar effect as an empty object for `fields`, but it is up to the discretion of the implementation
This has a similar effect as an empty object for `fields`, but it is up to the discretion of the implementation.

Query Parameters
```http
?fields=id,type,geometry,bbox,properties,links,assets

```text
?fields=id,type,geometry,bbox,properties.datetime,links,assets,stac_version
```

JSON

```json
{
"fields": {
Expand All @@ -117,22 +129,25 @@ JSON
"type",
"geometry",
"bbox",
"properties",
"properties.datetime",
"links",
"assets"
"assets",
"stac_version",
]
}
}
```

Exclude `geometry` from the baseline fields. This **must** return an entity that is not a valid GeoJSON Feature or a valid STAC Item.
Exclude `geometry` from the full item. This **must** return an entity that is not a valid GeoJSON Feature or a valid STAC Item.

Query Parameters
```http

```text
?fields=-geometry
```

JSON

```json
{
"fields": {
Expand All @@ -143,17 +158,17 @@ JSON
}
```

To return the `id`, `type`, `geometry`, and the Properties attribute `eo:cloud_cover`.
This **must** return a valid STAC Item, as the includes are added to the default includes.
Explicitly specifying `id`, `type`, and `geometry` has not effect as these are default fields,
but `properties.eo:cloud_cover` is not a default field and thereby should be in the response.
Return the `id`, `type`, `geometry`, and the Properties attribute `eo:cloud_cover`.
This might not return a valid STAC Item, since not all required Item attributes are included.

Query Parameters
```http

```text
?fields=id,type,geometry,properties.eo:cloud_cover
```

JSON

```json
{
"fields": {
Expand All @@ -170,16 +185,19 @@ JSON
To include `id` and all the properties fields, except for the `foo` field.

Query Parameters
```http

```text
?fields=id,properties,-properties.foo
```

also valid:
```http

```text
?fields=+id,+properties,-properties.foo
```

JSON

```json
{
"fields": {
Expand Down

0 comments on commit dd82a3f

Please sign in to comment.