fix: address review comments

Author: gadomski

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Include/exclude recommendations ([#5](https://github.com/stac-api-extensions/fields/pull/5))
+- Include/exclude semantics are more precisely defined ([#5](https://github.com/stac-api-extensions/fields/pull/5))
 
 ## [v1.0.0-rc.2] - TBD
 

README.md

@@ -71,18 +71,17 @@ name, e.g., `properties.datetime` or `datetime`.
 
 ## Include/Exclude Semantics
 
-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 only fields
-`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`.
+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
+empty array (for POST requests), then the recommended behavior is to include only fields
+`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`.
 These are the default fields to ensure a valid STAC Item is returned by default.
 Implementations may choose to include other properties, e.g., `properties.created`, but the number
 of default properties fields should be kept to a minimum.
 2. If only `include` is specified, these fields should be the only fields included.
 Any additional fields provided beyond those in the `include` list should be kept
 to a minimum, as the caller has explicitly stated they do not need them.
-3. If only `exclude` is specified, the specified fields fields should not be
-included in the response Item entity, but every other field available for the
+3. If only `exclude` is specified, the specified fields should not be
+included, but every other field available for the
 Item should be included.
 4. If `exclude` is specified and `include` is null or an empty
 array, then the `exclude` fields should be excluded from the default set.
@@ -97,7 +96,7 @@ example:
     2. If a field is in `include`, and a nested field of that field is in `exclude`, the field
     should be included, and the nested field should be excluded.  For example,
     if `properties` is included and `properties.datetime` is excluded, then
-    `datetime` should not be in `properties`.
+    `datetime` should not be in `properties`, but every other nested field should be.
 6. If the same field is present in both `include` and `exclude`, it should be included.
 
 ### `null` vs. empty vs. missing
@@ -182,6 +181,8 @@ missing. For example, this is a case of `include` being empty (NOT missing):
 
 ## Examples
 
+### Default fields
+
 Return the default fields. This should return valid STAC Item entities.
 
 Query Parameters
@@ -199,6 +200,8 @@ JSON
 }
 ```
 
+### Explicitly get a valid STAC Item
+
 This has a similar effect as an empty object for `fields`, but it is up to the discretion of the implementation.
 
 Query Parameters
@@ -226,6 +229,8 @@ JSON
 }
 ```
 
+### Exclude geometry
+
 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
@@ -246,6 +251,8 @@ JSON
 }
 ```
 
+### Minimal subset
+
 Return the `id`, `type`, `geometry`, and the Properties field `eo:cloud_cover`.
 This is not guaranteed not return a valid STAC Item, since not all required Item
 fields are included, but an implementor may choose to return a valid STAC
@@ -272,6 +279,8 @@ JSON
 }
 ```
 
+### Exclude a nested fiels
+
 To include `id` and all the properties fields, except for the `foo` field.
 
 Query Parameters