diff --git a/README.md b/README.md index cf74f90c..63eccbd9 100644 --- a/README.md +++ b/README.md @@ -25,42 +25,42 @@ geometries, and even smaller Item objects can add up when large numbers of them fields in an Item are used, so this specification provides a mechanism for clients to request that servers to explicitly include or exclude certain fields. -This behavior may be bound to either or both of +This behavior may be bound to either or both of [STAC API - Item Search](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.2/item-search) (`/search` endpoint) or [STAC API - Features](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.2/ogcapi-features) -(`/collections/{collectionId}/items` endpoint) by advertising the relevant conformance class. +(`/collections/{collectionId}/items` endpoint) by advertising the relevant conformance class. -When used in a POST request with `Content-Type: application/json`, this adds an attribute `fields` with -an object value to the core JSON search request body. The `fields` object contains two attributes with string array +When used in a POST request with `Content-Type: application/json`, this adds an attribute `fields` with +an object value to the core JSON search request body. The `fields` object contains two attributes with string array values, `include` and `exclude`. -When used with GET, the semantics are the same, except the syntax is a single parameter `fields` with -a comma-separated list of attribute names, where `exclude` values are those prefixed by a `-` and `include` values are +When used with GET, the semantics are the same, except the syntax is a single parameter `fields` with +a comma-separated list of attribute names, where `exclude` values are those prefixed by a `-` and `include` values are those with no prefix, e.g., `-geometry`, or `id,-geometry,properties`. -It is recommended that implementations provide exactly the `include` and `exclude` sets specified by the request, -but this is not required. These values are only hints to the server as to the desires of the client, and not a -contract about what the response will be. Implementations are still considered compliant if fields not specified as part of `include` -are in the response or ones specified as part of `exclude` are. For example, implementations may choose to always -include simple string fields like `id` and `type` regardless of the `exclude` specification. However, it is recommended -that implementations honor excludes for attributes with more complex and arbitrarily large values -(e.g., `geometry`, `assets`). For example, some Item objects may have a geometry with a simple 5 point polygon, but these +It is recommended that implementations provide exactly the `include` and `exclude` sets specified by the request, +but this is not required. These values are only hints to the server as to the desires of the client, and not a +contract about what the response will be. Implementations are still considered compliant if fields not specified as part of `include` +are in the response or ones specified as part of `exclude` are. For example, implementations may choose to always +include simple string fields like `id` and `type` regardless of the `exclude` specification. However, it is recommended +that implementations honor excludes for attributes with more complex and arbitrarily large values +(e.g., `geometry`, `assets`). For example, some Item objects may have a geometry with a simple 5 point polygon, but these polygons can be very large when reprojected to EPSG:4326, as in the case of a highly-decimated sinusoidal polygons. Implementations are also not required to implement semantics for nested values whereby one can include an object, but exclude attributes of that object, e.g., include `properties` but exclude `properties.datetime`. -No error must be returned if a specified field has no value for it in the catalog. For example, if the attribute +No error must be returned if a specified field has no value for it in the catalog. For example, if the attribute "properties.eo:cloud_cover" is specified but there is no cloud cover value for an Item, a successful HTTP response -must be returned and the Item entities will not contain that -attribute. +must be returned and the Item entities will not contain that +attribute. If no `fields` are specified, the response is **must** be a valid [ItemCollection](https://github.com/radiantearth/stac-spec/tree/v1.0.0-rc.2/itemcollection/README.md). If a client excludes -attributes that are required in a STAC Item, the server may return an invalid STAC Item. For example, if `type` -and `geometry` are excluded, the entity will not even be a valid GeoJSON Feature, or if `bbox` is excluded then the entity +attributes that are required in a STAC Item, the server may return an invalid STAC Item. For example, if `type` +and `geometry` are excluded, the entity will not even be a valid GeoJSON Feature, or if `bbox` is excluded then the entity will not be a valid STAC Item. -Implementations may return attributes not specified, e.g., id, but must avoid anything other than a minimal entity +Implementations may return attributes not specified, e.g., id, but must avoid anything other than a minimal entity representation. This specification does not yet require the implementation of an "-ables" endpoint (like CQL2 does for queryables) @@ -79,18 +79,26 @@ This default is so that the entity returned is a valid STAC Item. Implementations may choose to include 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 should be the only attributes included. -3. If only `exclude` is specified, these attributes should be subtracted from the full item. -This may result in an entity that is not a valid STAC Item. +If additional fields are provided beyond those in the `include` list, the number and size of +these attributes should be kept to a minimum. +3. If only `exclude` is specified, these attributes fields should not be +included in the response Item object, but every other fields available for the +Item should be included. 4. If `exclude` is specified and `include` is null or an empty array, then the `exclude` attributes should be excluded 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. For example, 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. -For example, 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. +5. For nested attributes (e.g. `properites.datetime`), the most specific path +should be honored first, and `include` should be preferred over `exclude`. For +example: + 1. If a field is in `exclude`, and a nested attribute of that field is in + `include`, the nested attribute should be included, but no other nested + attributes in the field should be included. For example, if `properties` is + excluded and `properties.datetime` is included, then `datetime` + should be the only nested attribute in `properties`. + 2. If a field is in `include`, and a nested attribute is in `exclude`, the field + should be included, and the nested attribute should be excluded. For example, + if `properties` is included and `properties.datetime` is excluded, then + `datetime` should not be in `properties`. +6. If the same field is present in both `include` and `exclude`, it should be included. ## Examples @@ -138,7 +146,7 @@ JSON } ``` -Exclude `geometry` from the full item. This **must** return an entity that is not a valid GeoJSON Feature or a valid STAC Item. +Exclude `geometry` from the full item. This will return an entity that is not a valid GeoJSON Feature or a valid STAC Item. Query Parameters @@ -159,7 +167,9 @@ JSON ``` 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. +This is not guaranteed not return a valid STAC Item, since not all required Item +attributes are included, but an implementor may choose to return a valid STAC +item anyways. Query Parameters