fix: comments from PR review

Author: gadomski

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