From a829170faf27f073f751090433138c1059567e6d Mon Sep 17 00:00:00 2001 From: Jon Duckworth Date: Mon, 17 May 2021 14:31:33 -0400 Subject: [PATCH] Separate recommendations and cautions for usage --- fragments/usage/usage-fragment.md | 45 ++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/fragments/usage/usage-fragment.md b/fragments/usage/usage-fragment.md index 45d1e61..2390971 100644 --- a/fragments/usage/usage-fragment.md +++ b/fragments/usage/usage-fragment.md @@ -1,8 +1,10 @@ # Usage Recommendations Specification The Usage Recommendations section defines conditions under which the model publishers believe the -model will perform as expected. It is important to note that these are *recommendations* and that -they **in no way provide any guarantee of model performance under the given conditions**. +model will perform as expected. It also provides a mechanism for publishers to explicitly call out +conditions under which they believe the model is likely to not performa as expected. It is important +to note that these are *recommendations* and that they **in no way provide any guarantee of model +performance under the given conditions**. If no Usage Recommendation section is provided, then users should assume that the model will only perform as expected under conditions that match those described in the [Model Training] section. @@ -10,18 +12,36 @@ This also applies to any fields that are not present in the Usage Recommendation instance, if no `temporal` field is provided, users should assume the model will only perform as expected for data in the time range given in the [Model Training] section. -## Usage Recommendation Fields -| Field Name | Type | Description | -|------------------|--------------------------|-------------------------------------------------------------------------| -| spatial | [Spatial Extent Object] | The spatial extents within which the model should perform as expected. | -| temporal | [Temporal Extent Object] | The temporal extents within which the model should perform as expected. | -| description | string | A human-readable description of conditions under which the model should perform as expected. | +## Usage Recommendations Fields + +The `recommendations` and `cautions` fields in this section are arrays of objects that describe +conditions under which the model either should perform as expected or should *not* behave as +expected, respectively. + +If the Usage Recommendations section is present, then at least one of these fields is required and +must be a non-empty array. + +| Field Name | Type | Description | +| ----------------- | --------------------- | ---------------------------------------------------------------------------------------------- | +| `recommendations` | \[[Usage Conditions]] | An array of objects describing conditions under which the model *should* perform as expected. | +| `cautions` | \[[Usage Conditions]] | An array of objects describing conditions under which the model *may not* perform as expected. | + +## Usage Conditions + +This object is used to described conditions under which model usage is either recommended (if found +in the `recommendations` list) or discouraged (if found in the `cautions` list). + +| Field Name | Type | Description | +| ----------- | ------------------------ | ------------------------------------------------------------------------------------------ | +| spatial | [Spatial Extent Object] | The spatial extents to which the recommendation or caution applies. | +| temporal | [Temporal Extent Object] | The temporal extents to which the recommendation or caution applies. | +| description | string | A human-readable description of conditions to which the recommendation or caution applies. | ### Spatial Extent Object -| Element | Type | Description | -| ------- | ------------ | -------------------------------------------------------------------- | +| Element | Type | Description | +| ------- | ------------ | -------------------------------------------------------------------------------------------- | | bbox | \[\[number]] | **REQUIRED.** Potential *spatial extents* within which the model should perform as expected. | The `bbox` element is an *array* whose elements are themselves arrays. Each inner array is a bounding @@ -36,8 +56,8 @@ spatial extent, when in fact there may be only specific areas in which this is t ### Temporal Extent Object -| Element | Type | Description | -| -------- | ------------------ | --------------------------------------------------------------------- | +| Element | Type | Description | +| -------- | ------------------ | --------------------------------------------------------------------------------------------- | | interval | \[\[string\|null]] | **REQUIRED.** Potential *temporal extents* within which the model should perform as expected. | The `interval` element is an *array* whose elements are themselves arrays. Each inner array is an @@ -55,5 +75,6 @@ when in fact there may be only specific ranges in which this is true. [Model Training]: ../training [Spatial Extent Object]: #spatial-extent-object [Temporal Extent Object]: #temporal-extent-object +[Usage Conditions]: #usage-conditions [STAC Spatial Extent Object]: https://github.com/radiantearth/stac-spec/blob/v1.0.0-rc.4/collection-spec/collection-spec.md#spatial-extent-object [STAC Temporal Extent Object]: https://github.com/radiantearth/stac-spec/blob/v1.0.0-rc.4/collection-spec/collection-spec.md#temporal-extent-object