diff --git a/README.md b/README.md index cf74f90c..cb719963 100644 --- a/README.md +++ b/README.md @@ -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