v1.1.0 (implements #6, #7, #8)

m-mohr · m-mohr · commit f6b9b91e5049 · 2022-08-17T14:51:10.000+02:00
diff --git a/.github/remark.yaml b/.github/remark.yaml
@@ -21,7 +21,6 @@ plugins:
     - 'fenced'
 # Headings
   - remark-lint-heading-increment
-  - remark-lint-no-duplicate-headings
   - remark-lint-no-multiple-toplevel-headings
   - remark-lint-no-heading-punctuation
   - - remark-lint-maximum-heading-length
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -3,12 +3,11 @@ on: [push, pull_request]
 jobs:
   deploy:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [14.x]
     steps:
-      - uses: actions/setup-node@v1
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 'lts/*'
       - uses: actions/checkout@v2
       - run: |
           npm install
-          npm test
+          npm test
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,14 +12,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Allow usage in Catalogs.
 - Explicitly support usage in assets.
+- New relation type `version-history`
 
 ### Changed
 
 - The `version` field is not required any longer.
 
-## [v1.0.0]
+### Fixed
 
-- First release
+- Clarify usage of the relation types and how often they can be used per document.
+
+## [v1.0.0] - 2021-03-08
+
+- Initial independent release, see [previous history](https://github.com/radiantearth/stac-spec/commits/v1.0.0-rc.1/extensions/version)
 
 [Unreleased]: <https://github.com/stac-extensions/version/compare/v1.1.0...HEAD>
 [v1.1.0]: <https://github.com/stac-extensions/version/compare/v1.0.0...v1.1.0>
diff --git a/README.md b/README.md
@@ -6,7 +6,9 @@
 - **Scope:** Item, Collection
 - **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Proposal
 - **Owner**: @m-mohr
-- **History**: [Prior to March 2, 2021](https://github.com/radiantearth/stac-spec/commits/v1.0.0-rc.1/extensions/version)
+
+This document explains the Versioning Indicators Extension to the
+[SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification.
 
 This extension allows to version STAC Collections and STAC Items. Therefore, it also allows to deprecate legacy versions.
 Only fields and possible link relation types are defined in this extension,
@@ -33,6 +35,11 @@ The fields in the table below can be used in these parts of STAC documents:
 | version    | string  | Version of the context this fields is used in (e.g. Asset or Collection). |
 | deprecated | boolean | Specifies that the context this field is used in (e.g. Asset or Collection) is deprecated with the potential to be removed. Defaults to `false`. It should be transitioned out of usage as soon as possible and users should refrain from using it in new projects. A link with relation type `latest-version` SHOULD be added to the links and MUST refer to the resource that can be used instead. |
 
+These fields have different meaning depending on where they are used. When used as an Item properties or top-level Collection field, they refer to
+the version or deprecation of all data referenced in the Item or Collection, which may include the metadata itself.
+When used in an Asset Object, they refer to the version or deprecation
+of the particular data asset linked to in the Asset Object.
+
 ## Relation types
 
 The following types should be used as applicable `rel` types for the
@@ -42,6 +49,38 @@ These are all following [RFC 5829](https://tools.ietf.org/html/rfc5829).
 
 | Type                | Description |
 | ------------------- | ----------- |
-| latest-version      | This link points to a resource containing the latest (e.g., current) version. |
-| predecessor-version | This link points to a resource containing the predecessor version in the version history. |
-| successor-version   | This link points to a resource containing the successor version in the version history. |
+| latest-version      | This link points to a STAC resource containing the latest (e.g., current) version. A maximum of one link can use this relation type per STAC resource. |
+| predecessor-version | One or multiple links can point to STAC resources that are predecessor versions in the version history. |
+| successor-version   | One or multiple links can point to STAC resources that are successor versions in the version history. |
+| version-history     | This link points to a version history or changelog. This can be for example a Markdown file with the corresponding media type or a STAC Catalog or Collection. |
+
+## Contributing
+
+All contributions are subject to the
+[STAC Specification Code of Conduct](https://github.com/radiantearth/stac-spec/blob/master/CODE_OF_CONDUCT.md).
+For contributions, please follow the
+[STAC specification contributing guide](https://github.com/radiantearth/stac-spec/blob/master/CONTRIBUTING.md) Instructions
+for running tests are copied here for convenience.
+
+### Running tests
+
+The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. 
+To run tests locally, you'll need `npm`, which is a standard part of any [node.js installation](https://nodejs.org/en/download/).
+
+First you'll need to install everything with npm once. Just navigate to the root of this repository and on 
+your command line run:
+```bash
+npm install
+```
+
+Then to check markdown formatting and test the examples against the JSON schema, you can run:
+```bash
+npm test
+```
+
+This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.
+
+If the tests reveal formatting problems with the examples, you can fix them with:
+```bash
+npm run format-examples
+```
diff --git a/json-schema/schema.json b/json-schema/schema.json
@@ -7,6 +7,9 @@
     {
       "$comment": "This is the schema for STAC Items.",
       "allOf": [
+        {
+          "$ref": "#/definitions/stac_extensions"
+        },
         {
           "type": "object",
           "required": [
@@ -28,43 +31,55 @@
               }
             }
           }
-        },
-        {
-          "$ref": "#/definitions/stac_extensions"
         }
       ]
     },
     {
       "$comment": "This is the schema for STAC Collections.",
+      "type": "object",
       "allOf": [
         {
-          "type": "object",
           "required": [
             "type"
           ],
           "properties": {
             "type": {
               "const": "Collection"
-            },
+            }
+          }
+        },
+        {
+          "$ref": "#/definitions/stac_extensions"
+        },
+        {
+          "$comment": "This is the schema for the top-level fields in a Collection.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/fields"
+            }
+          ]
+        },
+        {
+          "$comment": "This validates the fields in Collection Assets.",
+          "properties": {
             "assets": {
               "type": "object",
               "additionalProperties": {
                 "$ref": "#/definitions/fields"
               }
-            },
+            }
+          }
+        },
+        {
+          "$comment": "This is the schema for the fields in Item Asset Definitions.",
+          "properties": {
             "item_assets": {
               "type": "object",
               "additionalProperties": {
                 "$ref": "#/definitions/fields"
               }
             }
           }
-        },
-        {
-          "$ref": "#/definitions/stac_extensions"
-        },
-        {
-          "$ref": "#/definitions/fields"
         }
       ]
     },

Original file line number	Diff line number	Diff line change
`@@ -7,6 +7,9 @@`
`7`	`7`	`{`
`8`	`8`	`"$comment": "This is the schema for STAC Items.",`
`9`	`9`	`"allOf": [`
	`10`	`+ {`
	`11`	`+ "$ref": "#/definitions/stac_extensions"`
	`12`	`+ },`
`10`	`13`	`{`
`11`	`14`	`"type": "object",`
`12`	`15`	`"required": [`
`@@ -28,43 +31,55 @@`
`28`	`31`	`}`
`29`	`32`	`}`
`30`	`33`	`}`
`31`		`- },`
`32`		`- {`
`33`		`- "$ref": "#/definitions/stac_extensions"`
`34`	`34`	`}`
`35`	`35`	`]`
`36`	`36`	`},`
`37`	`37`	`{`
`38`	`38`	`"$comment": "This is the schema for STAC Collections.",`
	`39`	`+ "type": "object",`
`39`	`40`	`"allOf": [`
`40`	`41`	`{`
`41`		`- "type": "object",`
`42`	`42`	`"required": [`
`43`	`43`	`"type"`
`44`	`44`	`],`
`45`	`45`	`"properties": {`
`46`	`46`	`"type": {`
`47`	`47`	`"const": "Collection"`
`48`		`- },`
	`48`	`+ }`
	`49`	`+ }`
	`50`	`+ },`
	`51`	`+ {`
	`52`	`+ "$ref": "#/definitions/stac_extensions"`
	`53`	`+ },`
	`54`	`+ {`
	`55`	`+ "$comment": "This is the schema for the top-level fields in a Collection.",`
	`56`	`+ "allOf": [`
	`57`	`+ {`
	`58`	`+ "$ref": "#/definitions/fields"`
	`59`	`+ }`
	`60`	`+ ]`
	`61`	`+ },`
	`62`	`+ {`
	`63`	`+ "$comment": "This validates the fields in Collection Assets.",`
	`64`	`+ "properties": {`
`49`	`65`	`"assets": {`
`50`	`66`	`"type": "object",`
`51`	`67`	`"additionalProperties": {`
`52`	`68`	`"$ref": "#/definitions/fields"`
`53`	`69`	`}`
`54`		`- },`
	`70`	`+ }`
	`71`	`+ }`
	`72`	`+ },`
	`73`	`+ {`
	`74`	`+ "$comment": "This is the schema for the fields in Item Asset Definitions.",`
	`75`	`+ "properties": {`
`55`	`76`	`"item_assets": {`
`56`	`77`	`"type": "object",`
`57`	`78`	`"additionalProperties": {`
`58`	`79`	`"$ref": "#/definitions/fields"`
`59`	`80`	`}`
`60`	`81`	`}`
`61`	`82`	`}`
`62`		`- },`
`63`		`- {`
`64`		`- "$ref": "#/definitions/stac_extensions"`
`65`		`- },`
`66`		`- {`
`67`		`- "$ref": "#/definitions/fields"`
`68`	`83`	`}`
`69`	`84`	`]`
`70`	`85`	`},`