From b0e019219c517f2dced705d50633fb91d1025585 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 29 Apr 2024 15:22:02 +0200 Subject: [PATCH] Define product:type and product:timeliness --- CHANGELOG.md | 2 +- README.md | 48 +++---- examples/collection.json | 40 ++---- examples/item.json | 108 ++++++++++------ json-schema/schema.json | 261 ++++++++++++++------------------------- package.json | 6 +- 6 files changed, 190 insertions(+), 275 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dd0fd2f..c36504e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,4 +16,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -[Unreleased]: +[Unreleased]: diff --git a/README.md b/README.md index bf65d0e..95834a6 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,15 @@ -# Template Extension Specification +# Product Extension Specification -- **Title:** Template -- **Identifier:** -- **Field Name Prefix:** template +- **Title:** Product +- **Identifier:** +- **Field Name Prefix:** product - **Scope:** Item, Collection - **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Proposal -- **Owner**: @your-gh-handles @person2 +- **Owner**: @m-mohr -This document explains the Template Extension to the [SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification. -This is the place to add a short introduction. +This document explains the Product Extension to the [SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification. + +This extension provides a generic framework to describe products across domains better in STAC. - Examples: - [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item @@ -26,36 +27,19 @@ The fields in the table below can be used in these parts of STAC documents: - [x] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections) - [ ] Links -| Field Name | Type | Description | -| -------------------- | ------------------------- | -------------------------------------------- | -| template:new_field | string | **REQUIRED**. Describe the required field... | -| template:xyz | [XYZ Object](#xyz-object) | Describe the field... | -| template:another_one | \[number] | Describe the field... | +| Field Name | Type | Description | +| ------------------ | ------ | ----------------- | +| product:type | string | The product type. | +| product:timeliness | string | The timeliness of the product as an [ISO 8601 Duration](https://en.wikipedia.org/wiki/ISO_8601#Durations). | ### Additional Field Information -#### template:new_field - -This is a much more detailed description of the field `template:new_field`... - -### XYZ Object - -This is the introduction for the purpose and the content of the XYZ Object... - -| Field Name | Type | Description | -| ---------- | ------ | -------------------------------------------- | -| x | number | **REQUIRED**. Describe the required field... | -| y | number | **REQUIRED**. Describe the required field... | -| z | number | **REQUIRED**. Describe the required field... | - -## Relation types +#### product:type -The following types should be used as applicable `rel` types in the -[Link Object](https://github.com/radiantearth/stac-spec/tree/master/item-spec/item-spec.md#link-object). +The product type in this extension is a free-form text that providers can freely use to descibe their product types. +Some extensions may specify more specific rules for this field. -| Type | Description | -| -------------- | ------------------------------------- | -| fancy-rel-type | This link points to a fancy resource. | +This field superceedes the `sar:product_type` field. ## Contributing diff --git a/examples/collection.json b/examples/collection.json index 2472ecc..ca76138 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -1,8 +1,7 @@ { "stac_version": "1.0.0", "stac_extensions": [ - "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json", - "https://stac-extensions.github.io/template/v1.0.0/schema.json" + "https://stac-extensions.github.io/product/v0.1.0/schema.json" ], "type": "Collection", "id": "collection", @@ -29,36 +28,15 @@ ] } }, - "template:new_field": "test", - "template:xyz": { - "x": 1, - "y": 2, - "z": 3 - }, - "template:another_one": [ - 1, - 2, - 3 - ], - "assets": { - "example": { - "href": "https://example.com/examples/file.xyz", - "template:new_field": "test" - } - }, - "item_assets": { - "data": { - "roles": [ - "data" - ], - "template:new_field": "test" - } - }, + "product:type": "GRD", + "product:timeliness": "PT3H", "summaries": { - "datetime": { - "minimum": "2015-06-23T00:00:00Z", - "maximum": "2019-07-10T13:44:56Z" - } + "product:type": [ + "GRD" + ], + "product:timeliness": [ + "PT3H" + ] }, "links": [ { diff --git a/examples/item.json b/examples/item.json index cf19370..2c615d4 100644 --- a/examples/item.json +++ b/examples/item.json @@ -1,67 +1,95 @@ { + "type": "Feature", "stac_version": "1.0.0", "stac_extensions": [ - "https://stac-extensions.github.io/template/v1.0.0/schema.json" - ], - "type": "Feature", - "id": "item", - "bbox": [ - 172.9, - 1.3, - 173, - 1.4 + "https://stac-extensions.github.io/product/v0.1.0/schema.json" ], + "id": "sentinel-1-example", + "properties": { + "datetime": "2018-11-03T23:58:55.617217Z", + "start_datetime": "2018-11-03T23:58:55.121559Z", + "end_datetime": "2018-11-03T23:59:55.112875Z", + "platform": "sentinel-1a", + "constellation": "sentinel-1", + "instruments": [ + "c-sar" + ], + "product:type": "GRD", + "product:timeliness": "PT3H" + }, "geometry": { "type": "Polygon", "coordinates": [ [ [ - 172.9, - 1.3 + -67.071648, + -64.72924 ], [ - 173, - 1.3 + -65.087479, + -56.674374 ], [ - 173, - 1.4 + -68.033211, + -51.105831 ], [ - 172.9, - 1.4 + -70.275032, + -59.805672 ], [ - 172.9, - 1.3 + -67.071648, + -64.72924 ] ] ] }, - "properties": { - "datetime": "2020-12-11T22:38:32Z", - "template:new_field": "test", - "template:xyz": { - "x": 1, - "y": 2, - "z": 3 - }, - "template:another_one": [ - 1, - 2, - 3 - ] - }, "links": [ { - "href": "https://example.com/examples/item.json", - "rel": "self" + "rel": "root", + "href": "../../catalog.json", + "type": "application/json" + }, + { + "rel": "parent", + "href": "../collection.json", + "type": "application/json" } ], "assets": { - "data": { - "href": "https://example.com/examples/file.xyz", - "template:new_field": "test" + "noises": { + "href": "https://example.com/collections/sentinel-1/items/annotation/calibration/noise-s1a-ew-grd-hh-20181103t235855-20181103t235955-024430-02ad5d-001.xml", + "type": "text/xml", + "title": "Calibration Schema" + }, + "calibrations": { + "href": "https://example.com/collections/sentinel-1/items/annotation/calibration/calibration-s1a-ew-grd-hh-20181103t235855-20181103t235955-024430-02ad5d-001.xml", + "type": "text/xml", + "title": "Noise Schema" + }, + "products": { + "href": "https://example.com/collections/sentinel-1/items/annotation/s1a-ew-grd-hh-20181103t235855-20181103t235955-024430-02ad5d-001.xml", + "type": "text/xml", + "title": "Product Schema" + }, + "measurement": { + "href": "https://example.com/collections/sentinel-1/items/measurement/s1a-ew-grd-hh-20181103t235855-20181103t235955-024430-02ad5d-001.tiff", + "type": "image/tiff", + "title": "Measurements", + "sar:polarizations": [ + "HH" + ] + }, + "thumbnail": { + "href": "https://example.com/collections/sentinel-1/items/preview/quick-look.png", + "type": "image/png", + "title": "Thumbnail" } - } -} + }, + "bbox": [ + -70.275032, + -64.72924, + -65.087479, + -51.105831 + ] +} \ No newline at end of file diff --git a/json-schema/schema.json b/json-schema/schema.json index 8eae23b..ffeacb3 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -1,209 +1,134 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://stac-extensions.github.io/template/v1.0.0/schema.json#", - "title": "Template Extension", - "description": "STAC Template Extension for STAC Items and STAC Collections.", + "$id": "https://stac-extensions.github.io/product/v0.1.0/schema.json", + "title": "Product Extension", + "description": "STAC Product Extension for STAC Items and STAC Collections.", + "type": "object", + "required": [ + "stac_extensions" + ], + "properties": { + "stac_extensions": { + "type": "array", + "contains": { + "const": "https://stac-extensions.github.io/product/v0.1.0/schema.json" + } + } + }, "oneOf": [ { "$comment": "This is the schema for STAC Items. Remove this object if this extension only applies to Collections.", - "allOf": [ - { - "$ref": "#/definitions/stac_extensions" + "type": "object", + "required": [ + "type", + "properties", + "assets" + ], + "properties": { + "type": { + "const": "Feature" }, - { + "properties": { + "$ref": "#/definitions/fields" + }, + "assets": { "type": "object", - "required": [ - "type", - "properties", - "assets" - ], - "properties": { - "type": { - "const": "Feature" - }, - "properties": { - "allOf": [ - { - "$comment": "Require fields here for Item Properties.", - "required": [ - "template:new_field" - ] - }, - { - "$ref": "#/definitions/fields" - } - ] - }, - "assets": { - "$comment": "This validates the fields in Item Assets, but does not require them.", - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/fields" - } - } + "additionalProperties": { + "$ref": "#/definitions/fields" } } - ] + } }, { "$comment": "This is the schema for STAC Collections.", "type": "object", - "allOf": [ - { - "required": [ - "type" - ], - "properties": { - "type": { - "const": "Collection" - } + "required": [ + "type" + ], + "properties": { + "type": { + "const": "Collection" + }, + "item_assets": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/fields" } }, - { - "$ref": "#/definitions/stac_extensions" - } - ], - "anyOf": [ - { - "$comment": "This is the schema for the top-level fields in a Collection. Remove this if this extension does not define top-level fields for Collections.", - "allOf": [ - { - "$comment": "Require fields here for Collections (top-level).", - "required": [ - "template:new_field" - ] - }, - { - "$ref": "#/definitions/fields" - } - ] + "assets": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/fields" + } }, - { - "$comment": "This validates the fields in Collection Assets, but does not require them.", - "required": [ - "assets" - ], + "summaries": { + "type": "object", "properties": { - "assets": { - "type": "object", - "not": { - "additionalProperties": { - "not": { - "allOf": [ - { - "$ref": "#/definitions/require_any_field" - }, - { - "$ref": "#/definitions/fields" - } - ] + "product:type": { + "oneOf": [ + { + "$ref": "#/definitions/json_schema" + }, + { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/product:type" } } - } - } - } - }, - { - "$comment": "This is the schema for the fields in Item Asset Definitions. It doesn't require any fields.", - "required": [ - "item_assets" - ], - "properties": { - "item_assets": { - "type": "object", - "not": { - "additionalProperties": { - "not": { - "allOf": [ - { - "$ref": "#/definitions/require_any_field" - }, - { - "$ref": "#/definitions/fields" - } - ] + ] + }, + "product:timeliness": { + "oneOf": [ + { + "$ref": "#/definitions/json_schema" + }, + { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/product:timeliness" } } - } + ] } } - }, + } + }, + "allOf": [ { - "$comment": "This is the schema for the fields in Summaries. By default, only checks the existence of the properties, but not the schema of the summaries.", - "required": [ - "summaries" - ], - "properties": { - "summaries": { - "$ref": "#/definitions/require_any_field" - } - } + "$ref": "#/definitions/fields" } ] } ], "definitions": { - "stac_extensions": { - "type": "object", - "required": [ - "stac_extensions" - ], - "properties": { - "stac_extensions": { - "type": "array", - "contains": { - "const": "https://stac-extensions.github.io/template/v1.0.0/schema.json" - } - } - } - }, - "require_any_field": { - "$comment": "Please list all fields here so that we can force the existence of one of them in other parts of the schemas.", - "anyOf": [ - {"required": ["template:new_field"]}, - {"required": ["template:xyz"]}, - {"required": ["template:another_one"]} - ] - }, "fields": { - "$comment": "Add your new fields here. Don't require them here, do that above in the corresponding schema.", "type": "object", "properties": { - "template:new_field": { - "type": "string" + "product:type": { + "$ref": "#/definitions/product:type" }, - "template:xyz": { - "type": "object", - "required": [ - "x", - "y", - "z" - ], - "properties": { - "x": { - "type": "number" - }, - "y": { - "type": "number" - }, - "z": { - "type": "number" - } - } - }, - "template:another_one": { - "type": "array", - "items": { - "type": "number" - } + "product:timeliness": { + "$ref": "#/definitions/product:timeliness" } }, "patternProperties": { - "^(?!template:)": { - "$comment": "Above, change `template` to the prefix of this extension" - } + "^(?!product:)": {} }, "additionalProperties": false + }, + "product:type": { + "type": "string", + "minLength": 1 + }, + "product:timeliness": { + "type": "string", + "format": "duration" + }, + "json_schema": { + "$comment": "JSON Schema", + "type": "object" } } } diff --git a/package.json b/package.json index c8eee26..bbcb33f 100644 --- a/package.json +++ b/package.json @@ -1,11 +1,11 @@ { - "name": "stac-extension-template", + "name": "stac-extension-product", "version": "1.0.0", "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/product/v0.1.0/schema.json=./json-schema/schema.json", + "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/product/v0.1.0/schema.json=./json-schema/schema.json" }, "dependencies": { "remark-cli": "^12.0.0",