Add definitions for core STAC fields (#2)

* Define core STAC Item fields

* Define STAC common metadata as referring to training data

* Add recommendations for related STAC extensions

* Use inline links

* Clarify null datetime

* Use STAC fields to refer to recommended usage instead of training

* Add guidance for open intervals using end_datetime

* Fix markdown formatting

* Fix template references

* Remove Timestamp & Versioning Indicators Extension recommendations

CHANGELOG.md

@@ -16,4 +16,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-[Unreleased]: <https://github.com/stac-extensions/template/compare/v1.0.0...HEAD>
+[Unreleased]: <https://github.com/stac-extensions/ml-model/compare/v1.0.0...HEAD>

README.md

@@ -75,13 +75,39 @@ following values, but other values are allowed.
 
 Describes the type of predictions made by the model. It is STRONGLY RECOMMENDED that you use one of the 
 following values, but other values are allowed. Note that not all Prediction Type values are valid
-for a given [Learning Approach].
+for a given [Learning Approach](#ml-modellearning_approach).
 
 - `"object-detection"`
 - `"classification"`
 - `"segmentation"`
 - `"regression"`
 
+## Interpretation of STAC Fields
+
+The semantics of ML model metadata can sometimes differ significantly from the use-cases for which STAC was originally intended (Earth observation
+data). We feel that the benefits of structuring this metadata as a STAC Extensions outweigh the possible downsides, but it does require us to be
+specific about how certain STAC fields should be interpreted. The following definitions clarify the meaning of core fields from the STAC spec; for
+any fields not specifically defined here, please refer to the core STAC spec.
+
+### Spatiotemporal Fields
+
+| Field Name     | Type                      | Description                                                                                  |
+|----------------|---------------------------|----------------------------------------------------------------------------------------------|
+| geometry       | [GeoJSON Geometry Object](https://tools.ietf.org/html/rfc7946#section-3.1) | The geographic area over which the model may be used. Note that this may be the same as the area over which the model was trained, but could also represent additional areas where model performance has been tested or where the model publisher believes it will perform well based on similarities to the training environment.     |
+| start_datetime | string                    | The first or start date and time for images that should be used to generate inferences using the model. |
+| end_datetime   | string                    | The last or end date and time for images that should be used to generate inferences using the model. To represent an open interval (e.g. imagery from 2021-01-01T00:00:00Z or later), use the maximum value (`"9999-12-31T23:59:59Z"`) for `end_datetime`. |
+| datetime       | string                    | *This should always be `null`, since a date range (using `start_datetime` and `end_datetime`) will almost always be more appropriate.* |
+
+All other fields defined in the [STAC Common Metadata](https://github.com/radiantearth/stac-spec/blob/master/item-spec/common-metadata.md)
+documentation should be interpreted as referring to imagery that may be used for running the model to generate inferences.
+
+## Usage with Other STAC Extensions
+
+It is RECOMMENDED that following STAC Extensions be used in conjunction with the ML Model STAC Extension to fully describe geospatial ML models:
+
+- [Scientific Citation Extension](https://github.com/stac-extensions/scientific): This extension should be used to describe how the model should
+  cited in publications, as well as to reference any existing publications associated with the model.
+
 ## Relation types
 
 The following types should be used as applicable `rel` types in the
@@ -121,5 +147,3 @@ If the tests reveal formatting problems with the examples, you can fix them with
 ```bash
 npm run format-examples
 ```
-
-[Learning Approach]: <#ml-modellearning_approach>

examples/collection.json

@@ -30,8 +30,7 @@
   },
   "assets": {
     "example": {
-      "href": "https://example.com/examples/file.xyz",
-      "template:new_field": "test"
+      "href": "https://example.com/examples/file.xyz"
     }
   },
   "summaries": {

json-schema/schema.json

@@ -140,7 +140,7 @@
         "stac_extensions": {
           "type": "array",
           "contains": {
-            "const": "https://stac-extensions.github.io/template/v1.0.0/schema.json"
+            "const": "https://stac-extensions.github.io/ml-model/v1.0.0/schema.json"
           }
         }
       }

package.json

@@ -4,8 +4,8 @@
   "scripts": {
     "test": "npm run check-markdown && npm run check-examples",
     "check-markdown": "remark . -f -r .github/remark.yaml",
-    "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/template/v1.0.0/schema.json=./json-schema/schema.json",
-    "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/template/v1.0.0/schema.json=./json-schema/schema.json"
+    "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/ml-model/v1.0.0/schema.json=./json-schema/schema.json",
+    "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/ml-model/v1.0.0/schema.json=./json-schema/schema.json"
   },
   "dependencies": {
     "remark-cli": "^8.0.0",