diff --git a/README.md b/README.md index 1cbc11c6..c4c67d36 100644 --- a/README.md +++ b/README.md @@ -71,29 +71,39 @@ 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": { @@ -101,14 +111,16 @@ JSON } ``` -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": { @@ -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": { @@ -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": { @@ -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": {