Add text around when to include an extension in stac_extensions #1123
Conversation
lossyrob
force-pushed
the
clarification/rde/collection-extension
branch
from
2fa6167 to
59a8cf4
Compare
There was a problem hiding this comment.
Added a little bit of reorg and intro text to help explain to people how to 'use' an extension. Moved the 'general conventions' down to the 'new extensions' section, as it seemed to mostly be for those who are making extensions, and less relevant as the first thing to see.
|
@cholmes changes LGTM |
extensions/README.md
Outdated
| @@ -56,7 +56,7 @@ with the template. | |||
|
|
|||
| The logic for when an object should list an extension ID in its `stac_extension` array is as follows: | |||
|
|
|||
| - If the object directly implements the extension, the `stac_extensions` of that object should contain the extension ID. | |||
| - If the object directly implements the extension (by including at least one of the fields of the extension, plus any additional specified requirements), the `stac_extensions` of that object should contain the extension ID. | |||
There was a problem hiding this comment.
As there may be some extensions that don't add fields, maybe say something like:
by including at least one of the fields of the extension (if there are any) or implementing proposed behaviors, plus any additional specified requirements.
Please improve my wording, it seems like a very "German" way of writing it...
There was a problem hiding this comment.
Will there be extensions that don't add fields? What would they do?
If there are ones that don't add fields then I think I might just say '(by including the fields specified by the extension)'
There was a problem hiding this comment.
e.g. define asset roles or rel types. Or behavior such as the commons extension or the external item properties.
| - If a Collection [summary](../collection-spec/collection-spec.md#summaries) contains Item fields that implement an extension, then | ||
| the `stac_extensions` array of that Collection should list the extension ID. For example, if a Collection `summaries` field | ||
| contains a summary of `eo:bands`, then that Collection should have the EO extension JSON Schema URL in the `stac_extensions` array. | ||
| - If an object implements an extension that results in fields from a separate extension to be referenced, then the latter extension |
There was a problem hiding this comment.
Maybe add that this is usually the case, but extensions may specify otherwise (i.e. they say explicitly that stac_extensions should not be populated?)
There was a problem hiding this comment.
Since we don't yet have a case of this I think we should just leave as is. If an extension comes that has a good reason to do it in another way we can tweak this.
extensions/README.md
Outdated
| @@ -79,6 +104,20 @@ with existing extensions as well as possible and may even re-use fields and thei | |||
| into a new extension that combines commonly used fields across multiple extensions. | |||
| Best practices for extension proposals are still emerging in this section. | |||
|
|
|||
| ### General Conventions | |||
|
|
|||
| Creating a new extension involves defining a set of logically grouped fields, and specifying what the allowed values | |||
There was a problem hiding this comment.
Not all extensions may define fields, some may just define behavior (e.g. formerly the Commons extension) or define e.g. just rel types or asset roles.
| the Item Asset objects contained in the Item, but may also be used in an individual Item Asset to describe only the bands available in that asset. | ||
| 3. Additional attributes relating to a [Catalog](../catalog-spec/catalog-spec.md) or | ||
| [Collection](../collection-spec/collection-spec.md) should be added to the root of the object. | ||
|
|
There was a problem hiding this comment.
Maybe as 4. point, extensions may also extend other extensions, e.g. to add new fields to eo:bands/raster:bands or so?
Related Issue(s): #1120
Proposed Changes:
Adds clarification on when an extension ID (the JSON Schema URL) should be included in
stac_extensionsPR Checklist:
or a CHANGELOG entry is not required.
This PR affects the STAC API spec,and I have opened issue/PR #XXX to track the change.