feat: change include/exclude recommendations

Author: gadomski

README.md

@@ -71,44 +71,55 @@ 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, 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., `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": {
   }
 }
 ```
 
-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 +128,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 +157,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 +184,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": {