From 9221ed544289e11039db1048246d65906727a2d9 Mon Sep 17 00:00:00 2001 From: Panagiotis Vretanos Date: Wed, 14 Sep 2022 11:57:50 -0400 Subject: [PATCH 1/5] Changes to move 'created' and 'update' fields related to the resource from the record properties to links actually pointing to the representations of the resource. --- core/examples/json/record.json | 14 ++++++++------ core/openapi/ogcapi-records-1.yaml | 22 ++++++++++++---------- core/openapi/schemas/common/link.yaml | 10 ++++++++++ core/openapi/schemas/recordGeoJSON.yaml | 14 ++------------ core/standard/clause_7_record.adoc | 12 +++++++----- 5 files changed, 39 insertions(+), 33 deletions(-) diff --git a/core/examples/json/record.json b/core/examples/json/record.json index a7407a0f..fe455376 100644 --- a/core/examples/json/record.json +++ b/core/examples/json/record.json @@ -32,8 +32,8 @@ ] }, "properties": { - "recordCreated": "2021-02-08", - "recordUpdated": "2021-02-08", + "created": "2021-02-08", + "updated": "2021-02-08", "type": "dataset", "title": "Total Ozone - daily observations", "description": "A measurement of the total amount of atmospheric ozone in a given column from the surface to the edge of the atmosphere. Ground based instruments such as spectrophotometers and ozonemeters are used to measure results daily", @@ -53,8 +53,6 @@ "value": "urn:x-wmo:md:int.wmo.wis::https://geo.woudc.org/def/data/ozone/total-column-ozone/totalozone" } ], - "created": "2015-01-23", - "updated": "2015-01-23", "publisher": "https://woudc.org", "themes": [ { @@ -163,7 +161,9 @@ "rel": "enclosure", "type": "text/html", "title": "Web Accessible Folder (WAF)", - "href": "https://woudc.org/archive/Archive-NewFormat/TotalOzone_1.0_1" + "href": "https://woudc.org/archive/Archive-NewFormat/TotalOzone_1.0_1", + "created": "2015-01-23", + "updated": "2015-01-23" }, { "rel": "search", @@ -175,7 +175,9 @@ "rel": "enclosure", "type": "application/zip", "title": "Static dataset archive file", - "href": "https://woudc.org/archive/Summaries/dataset-snapshots/totalozone.zip" + "href": "https://woudc.org/archive/Summaries/dataset-snapshots/totalozone.zip", + "created": "2015-01-23", + "updated": "2015-01-23" }, { "rel": "service", diff --git a/core/openapi/ogcapi-records-1.yaml b/core/openapi/ogcapi-records-1.yaml index 77fb221e..77993fbd 100644 --- a/core/openapi/ogcapi-records-1.yaml +++ b/core/openapi/ogcapi-records-1.yaml @@ -422,11 +422,11 @@ components: - type - title properties: - recordCreated: + created: type: string description: Date of creation of this record. format: date-time - recordUpdated: + updated: type: string description: The most recent date on which the record was changed. format: date-time @@ -474,14 +474,6 @@ components: description: The value of the identifier. required: - value - created: - type: string - description: Date of creation of the resource. - format: date-time - updated: - type: string - description: Most recent date on which the resource was changed. - format: date-time publisher: type: string description: |- @@ -621,6 +613,16 @@ components: type: string length: type: integer + templated: + type: boolean + variables: + type: object + created: + type: string + format: date-time + updated: + type: string + format: date-time multilinestringGeoJSON: type: object required: diff --git a/core/openapi/schemas/common/link.yaml b/core/openapi/schemas/common/link.yaml index 25d93630..8d624559 100644 --- a/core/openapi/schemas/common/link.yaml +++ b/core/openapi/schemas/common/link.yaml @@ -24,3 +24,13 @@ properties: In combination with a templated href, the variables section should provide enough information to bind to the target resource (e.g. a WMS). type: object + created: + type: string + description: + Date of creation of the resource pointed to by the link. + format: date-time + updated: + type: string + description: + Most recent date on which the resource pointed to by the link was changed. + format: date-time diff --git a/core/openapi/schemas/recordGeoJSON.yaml b/core/openapi/schemas/recordGeoJSON.yaml index c807d17b..0c6245d6 100644 --- a/core/openapi/schemas/recordGeoJSON.yaml +++ b/core/openapi/schemas/recordGeoJSON.yaml @@ -43,12 +43,12 @@ properties: - type - title properties: - recordCreated: + created: type: string description: Date of creation of this record. format: date-time - recordUpdated: + updated: type: string description: The most recent date on which the record was changed. @@ -103,16 +103,6 @@ properties: description: The value of the identifier. required: - value - created: - type: string - description: - Date of creation of the resource. - format: date-time - updated: - type: string - description: - Most recent date on which the resource was changed. - format: date-time themes: type: array description: diff --git a/core/standard/clause_7_record.adoc b/core/standard/clause_7_record.adoc index 84a01d5d..9722bc00 100644 --- a/core/standard/clause_7_record.adoc +++ b/core/standard/clause_7_record.adoc @@ -37,8 +37,8 @@ Other encoding are allow but are not described in this document. |=== |Queryables |Requirement |Description |GeoJSON key |recordId |**required** |A unique record identifier assigned by the server. |id -|recordCreated |optional |The date this record was created in the server. |properties.recordCreated -|recordUpdated |optional |The most recent date on which the record was changed. |properties.recordUpdated +|created |optional |The date this record was created in the server. |properties.created +|updated |optional |The most recent date on which the record was changed. |properties.updated |=== [#core-queryables-resource-table,reftext='{table-caption} {counter:table-num}'] @@ -55,8 +55,6 @@ Other encoding are allow but are not described in this document. |keywords |optional |A list of free-form keywords or tags associated with the resource. |properties.keyword |language |optional |The natural language used for textual values (i.e. titles, descriptions, etc) of a resource. |properties.language |externalIds |optional |One or more identifiers for the resource assigned by an external entity. |properties.externalIds -|created |optional |The date the resource was created. |properties.created -|updated |optional |The more recent date on which the resource was changed. |properties.updated |themes |optional |A knowledge organization system used to classify the resource. |properties.themes |formats |optional |A list of available distributions for the resource. |properties.formats |providers |optional |A list of providers qualified by their role in association to the record. |properties.providers @@ -165,7 +163,7 @@ Templated links may also be used to bind to resources that may require additiona This specification extends the https://github.com/opengeospatial/ogcapi-common/blob/master/core/openapi/schemas/link.json[schema for a link] to include substitution variables who values are filled in at runtime prior to resolving the link. -The https://github.com/opengeospatial/ogcapi-common/blob/master/core/openapi/schemas/link.json[link schema] is extended with the addition of two properties names `templated` and `variables`. The `templated` property is a boolean that is used to indicate the the URL of the link (i.e. `href`) is a template and contains substitution variables. The `variables` property uses https://json-schema.org/draft/2020-12/json-schema-validation.html[JSON-Schema fragments] to define the characteristics of each substitution variable referenced in the templated link URL. +The https://github.com/opengeospatial/ogcapi-common/blob/master/core/openapi/schemas/link.json[link schema] is extended with the addition of two properties named `templated` and `variables`. The `templated` property is a boolean that is used to indicate the the URL of the link (i.e. `href`) is a template and contains substitution variables. The `variables` property uses https://json-schema.org/draft/2020-12/json-schema-validation.html[JSON-Schema fragments] to define the characteristics of each substitution variable referenced in the templated link URL. include::requirements/record-core/REQ_templated-link.adoc[] @@ -176,6 +174,10 @@ include::requirements/record-core/REQ_templated-link.adoc[] include::../examples/json/templated-link.json[] ---- +==== Resource timestamps + +A <> contains information for accessing the resource described by the record which is encoded in the links section. Since a resource may have multiple representations there may be multiple links pointing to each represention of a resource. Furthermore, representations of a resource may be created and updated at different times. In order to capture this life cycle information of resource representations, the https://github.com/opengeospatial/ogcapi-common/blob/master/core/openapi/schemas/link.json[link schema] is extended with the addition of two properties named `created` and `updated`. The values of these properties are used to indicate the creation and last updated dates of the resource representation pointed to by the link. + [[sc_language_negotiation]] ==== Language negotiation From f1ff779a0331809538f28abefb08693f5e7358e4 Mon Sep 17 00:00:00 2001 From: Panagiotis Vretanos Date: Wed, 14 Sep 2022 12:47:20 -0400 Subject: [PATCH 2/5] Update dates used in example to be datetimes (rather than just plain dates). --- .../dataset_example/nz-buildings-record.json | 16 +++++++++------- core/examples/json/queryables.json | 4 ++-- core/examples/json/record.json | 12 ++++++------ 3 files changed, 17 insertions(+), 15 deletions(-) diff --git a/core/examples/json/crawlable_catalogue/dataset_example/nz-buildings-record.json b/core/examples/json/crawlable_catalogue/dataset_example/nz-buildings-record.json index ba1d9120..fdad1e79 100644 --- a/core/examples/json/crawlable_catalogue/dataset_example/nz-buildings-record.json +++ b/core/examples/json/crawlable_catalogue/dataset_example/nz-buildings-record.json @@ -32,8 +32,8 @@ }, "properties": { - "recordCreated": "2021-08-17", - "recordUpdated": "2021-08-17", + "created": "2021-08-17", + "updated": "2021-08-17", "type": "dataset", "title": "New Zealand Building Outlines", "description": "This dataset provides current outlines of buildings within mainland New Zealand captured from the latest aerial imagery. A building outline is a 2D representation of the roof outline of a building which has been classified from LINZ aerial imagery using a combination of automated and manual processes to extract and refine a building roof outline. Building outlines observed in aerial imagery larger than or equal to 10 square meters are captured in this dataset, and may include structures such as garages and large sheds. **Data vintage** This dataset shows the most recent set of building outlines extracted from the LINZ aerial imagery available on the LINZ Data Service. Current coverage includes nearly all regions of New Zealand, except parts of rural Auckland, remote parts of Bay of Plenty, Tasman and the Southern Alps, as well as Fiordland, Stewart Island and the Chatham Islands. This dataset will be updated and expanded as new aerial imagery becomes available. Since aerial imagery is flown only every few years in each region of the country, building outlines only reflect those buildings observed at the date of this aerial imagery capture, and may not reflect buildings constructed after this time period. Please refer to the [NZ Building Outlines Data Dictionary](https://nz-buildings.readthedocs.io/en/latest/introduction.html) for detailed metadata and information about this dataset.", @@ -42,8 +42,6 @@ "New Zealand" ], "language": "en-NZ", - "created": "2013-01-21", - "updated": "2020-04-23", "publisher": { "organizationName": "LINZ - Land Information New Zealand", @@ -80,14 +78,18 @@ "href": "buildings-collection.json", "rel": "alternate", "type": "application/json", - "title": "OGC Collection JSON of this data" + "title": "OGC Collection JSON of this data", + "created": "2013-01-21T00:00:00Z", + "updated": "2020-04-23T00:00:00Z" }, { "href": "https://storage.googleapis.com/open-geodata/linz-examples/nz-building-outlines.gpkg", "rel": "enclosure", "type": "application/geopackage+sqlite3", "length": 1449656320, - "title": "Data as a Geopackage" + "title": "Data as a Geopackage", + "created": "2013-01-21T00:00:00Z", + "updated": "2020-04-23T00:00:00Z" }, { "href": "./nz-building-outlines.xml", @@ -96,4 +98,4 @@ "title": "ISO 19115/19139 Metadata" } ] -} \ No newline at end of file +} diff --git a/core/examples/json/queryables.json b/core/examples/json/queryables.json index ab8e809b..05cf85fb 100644 --- a/core/examples/json/queryables.json +++ b/core/examples/json/queryables.json @@ -61,11 +61,11 @@ "type": "datetime" }, { - "queryable": "recordcreated", + "queryable": "created", "type": "datetime" }, { - "queryable": "recordmodified", + "queryable": "updated", "type": "datetime" } ] diff --git a/core/examples/json/record.json b/core/examples/json/record.json index fe455376..139f57bb 100644 --- a/core/examples/json/record.json +++ b/core/examples/json/record.json @@ -32,8 +32,8 @@ ] }, "properties": { - "created": "2021-02-08", - "updated": "2021-02-08", + "created": "2021-02-08T00:00:00Z", + "updated": "2021-02-08T00:00:00Z", "type": "dataset", "title": "Total Ozone - daily observations", "description": "A measurement of the total amount of atmospheric ozone in a given column from the surface to the edge of the atmosphere. Ground based instruments such as spectrophotometers and ozonemeters are used to measure results daily", @@ -162,8 +162,8 @@ "type": "text/html", "title": "Web Accessible Folder (WAF)", "href": "https://woudc.org/archive/Archive-NewFormat/TotalOzone_1.0_1", - "created": "2015-01-23", - "updated": "2015-01-23" + "created": "2015-01-23T00:00:00Z", + "updated": "2015-01-23T00:00:00Z" }, { "rel": "search", @@ -176,8 +176,8 @@ "type": "application/zip", "title": "Static dataset archive file", "href": "https://woudc.org/archive/Summaries/dataset-snapshots/totalozone.zip", - "created": "2015-01-23", - "updated": "2015-01-23" + "created": "2015-01-23T00:00:00Z", + "updated": "2015-01-23T00:00:00Z" }, { "rel": "service", From d70f36fe8b508426fc5742c2e11fca0b1581ee22 Mon Sep 17 00:00:00 2001 From: Panagiotis Vretanos Date: Wed, 14 Sep 2022 13:01:01 -0400 Subject: [PATCH 3/5] More changes to propagate changes to align closer to STAC. --- README.md | 8 +++----- core/openapi/schemas/catalogue.yaml | 14 ++----------- .../OpenSearch/clause_15_opensearch.adoc | 6 ++---- .../collections/openapi/ogcapi-records-1.yaml | 20 +++++++++---------- .../schemas/extendedCollectionInfo.yaml | 14 ++----------- 5 files changed, 19 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index a267de8f..4f28f536 100644 --- a/README.md +++ b/README.md @@ -23,17 +23,14 @@ The record building block defines the core schema of a catalogue record. It inc |Queryables |Requirement |Description |-----------|------------|----------------------------------- |recordId |**M** |A unique record identifier assigned by the server. -|recordCreated |O |The date this record was created in the server. -|recordUpdated |O |The most recent date on which the record was changed. -|links |O |A list of links for accessing the resource (e.g. download link, access link, etc.) in one of the supported distribution formats and/or links to other resources associated with this resource. Also, a list of links for navigating the API (e.g. prev, next, alternate, etc.). +|created |O |The date this record was created in the server. +|updated |O |The most recent date on which the record was changed. |type |**M** |The nature or genre of the resource. |title |**M** |A human-readable name given to the resource. |description |O |A free-text description of the resource. |keywords |O |A list of free-form keywords or tag associated with the resource. |language |O |This refers to the natural language used for textual values (i.e. titles, descriptions, etc) of a resource. |externalId |O |An identifier for the resource assigned by an external entity. -|created |O |The date the resource was created. -|updated |O |The more recent date on which the resource was changed. |publisher |O |The entity making the resource available. |themes |O |A knowledge organization system used to classify the resource. |formats |O |A list of available distributions for the resource. @@ -41,6 +38,7 @@ The record building block defines the core schema of a catalogue record. It inc |license |O |A legal document under which the resource is made available. |rights |O |A statement that concerns all rights not addressed by the license such as a copyright statement. |extent |O |The spatio-temporal coverage and resolution of the resource. +|links |O |A list of links including links for accessing the resource (e.g. download link, access link, etc.) in one of the supported distribution formats, links to other resources associated with this resource and links for navigating the API (e.g. prev, next, alternate, etc.). See [link schema.](https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/schemas/common/link.yaml). It is anticipated that the schema of a record will be extended to describe specific resource types (e.g. data sets, earth observation products, services, machine models, etc.) and also extended by information communities wishing to enrich the information content of the record to suit their needs. The specification does not mandate a specific encoding for a record but conformance classes are defined for encoding records as GeoJSON feature and HTML. diff --git a/core/openapi/schemas/catalogue.yaml b/core/openapi/schemas/catalogue.yaml index 00ccb8da..d6d48ff4 100644 --- a/core/openapi/schemas/catalogue.yaml +++ b/core/openapi/schemas/catalogue.yaml @@ -6,12 +6,12 @@ allOf: - itemType - type properties: - recordCreated: + created: type: string description: Date of creation of this catalogue. format: date-time - recordUpdated: + updated: type: string description: The most recent date on which this catalogue was changed. @@ -30,16 +30,6 @@ allOf: descriptions, etc.) of the catalogue. ISO 639-1/639-2 codes should be used. default: en - created: - type: string - description: - Date of creation of this catalogue. - format: date-time - updated: - type: string - description: - Most recent date on which the catalogue was changed. - format: date-time themes: type: array description: diff --git a/extensions/OpenSearch/clause_15_opensearch.adoc b/extensions/OpenSearch/clause_15_opensearch.adoc index e0d82ff9..cdffe910 100644 --- a/extensions/OpenSearch/clause_15_opensearch.adoc +++ b/extensions/OpenSearch/clause_15_opensearch.adoc @@ -211,8 +211,8 @@ The following table maps the <> t |=== |Core query response property |ATOM entry element |`recordId` |`atom:entry/atom:id` -|`recordCreated` |`dct:issued` -|`recordUpdated` |`dct:modified` +|`created` |`atom:entry/atom:published` +|`updated` |`atom:entry/atom:modified` |`links` |`atom:link` |`type` |`dc:type` |`title` |`atom:entry/atom:title` @@ -220,8 +220,6 @@ The following table maps the <> t |`keywords` |`atom:entry/atom:category` |`language` |`dct:language` |`externalId` |n/a` -|`created` |`atom:entry/atom:published` -|`updated` |`atom:entry/atom:modified` |`publisher` |`atom:entry/atom:creator` |`themes` |`atom:entry/atom:category` |`formats` |`atom/entry/atom:link[@rel="enclosure"]/@type` diff --git a/extensions/collections/openapi/ogcapi-records-1.yaml b/extensions/collections/openapi/ogcapi-records-1.yaml index dc507d71..35dca9f2 100644 --- a/extensions/collections/openapi/ogcapi-records-1.yaml +++ b/extensions/collections/openapi/ogcapi-records-1.yaml @@ -420,11 +420,11 @@ components: - type - title properties: - recordCreated: + created: type: string description: Date of creation of this record. format: date-time - recordUpdated: + updated: type: string description: The most recent date on which the record was changed. format: date-time @@ -460,14 +460,6 @@ components: the catalogue) entity. items: type: string - created: - type: string - description: Date of creation of the resource. - format: date-time - updated: - type: string - description: Most recent date on which the resource was changed. - format: date-time publisher: type: string description: |- @@ -607,6 +599,14 @@ components: type: string length: type: integer + created: + type: string + description: Date of creation of the resource. + format: date-time + updated: + type: string + description: Most recent date on which the resource was changed. + format: date-time multilinestringGeoJSON: type: object required: diff --git a/extensions/collections/openapi/schemas/extendedCollectionInfo.yaml b/extensions/collections/openapi/schemas/extendedCollectionInfo.yaml index 84187df3..07ce5967 100644 --- a/extensions/collections/openapi/schemas/extendedCollectionInfo.yaml +++ b/extensions/collections/openapi/schemas/extendedCollectionInfo.yaml @@ -5,12 +5,12 @@ allOf: - title - itemType properties: - recordCreated: + created: type: string description: |- Date of creation of this record. format: date-time - recordUpdated: + updated: type: string description: |- The most recent date on which the record was changed. @@ -41,16 +41,6 @@ allOf: catalogue) entity. items: type: string - created: - type: string - description: |- - Date of creation of the resource. - format: date-time - updated: - type: string - description: |- - Most recent date on which the resource was changed. - format: date-time publisher: $ref: responsibleParty.yaml description: |- From 3801c5cc82f87d51376df5afa83b5a37e19b23ee Mon Sep 17 00:00:00 2001 From: Panagiotis Vretanos Date: Wed, 14 Sep 2022 13:03:08 -0400 Subject: [PATCH 4/5] Oops ... missed one example. --- .../dataset_example/nz-buildings-record.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/core/examples/json/crawlable_catalogue/dataset_example/nz-buildings-record.json b/core/examples/json/crawlable_catalogue/dataset_example/nz-buildings-record.json index fdad1e79..e6765bb3 100644 --- a/core/examples/json/crawlable_catalogue/dataset_example/nz-buildings-record.json +++ b/core/examples/json/crawlable_catalogue/dataset_example/nz-buildings-record.json @@ -32,8 +32,8 @@ }, "properties": { - "created": "2021-08-17", - "updated": "2021-08-17", + "created": "2021-08-17T00:00:00Z", + "updated": "2021-08-17T00:00:00Z", "type": "dataset", "title": "New Zealand Building Outlines", "description": "This dataset provides current outlines of buildings within mainland New Zealand captured from the latest aerial imagery. A building outline is a 2D representation of the roof outline of a building which has been classified from LINZ aerial imagery using a combination of automated and manual processes to extract and refine a building roof outline. Building outlines observed in aerial imagery larger than or equal to 10 square meters are captured in this dataset, and may include structures such as garages and large sheds. **Data vintage** This dataset shows the most recent set of building outlines extracted from the LINZ aerial imagery available on the LINZ Data Service. Current coverage includes nearly all regions of New Zealand, except parts of rural Auckland, remote parts of Bay of Plenty, Tasman and the Southern Alps, as well as Fiordland, Stewart Island and the Chatham Islands. This dataset will be updated and expanded as new aerial imagery becomes available. Since aerial imagery is flown only every few years in each region of the country, building outlines only reflect those buildings observed at the date of this aerial imagery capture, and may not reflect buildings constructed after this time period. Please refer to the [NZ Building Outlines Data Dictionary](https://nz-buildings.readthedocs.io/en/latest/introduction.html) for detailed metadata and information about this dataset.", From 27de72bb66d44903caf1e51b3cdb74d98e5b8910 Mon Sep 17 00:00:00 2001 From: Panagiotis Vretanos Date: Sun, 27 Nov 2022 21:04:29 -0500 Subject: [PATCH 5/5] Patch typo. --- core/standard/clause_7_record.adoc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/core/standard/clause_7_record.adoc b/core/standard/clause_7_record.adoc index 9722bc00..030f1fb1 100644 --- a/core/standard/clause_7_record.adoc +++ b/core/standard/clause_7_record.adoc @@ -46,11 +46,10 @@ Other encoding are allow but are not described in this document. [cols="20,5,55,20",options="header"] |=== |Queryables |Requirement |Description |GeoJSON key -|geometry |**required** |A geometry associated with the resource that is used for discovery. Can be null if there is no associated geometry |geometry -|time |**required** |The temporal extent of the resource. Can be null. |time +|geometry |**required** |A geometry associated with the resource that is used for discovery. Can be null if there is no associated geometry. |geometry +|time |**required** |The temporal extent of the resource. Can be null is there is not associated temporal extent. |time |type |**required** |The nature or genre of the resource. |properties.type |title |**required** |A human-readable name given to the resource. |properties.title - |description |optional |A free-text description of the resource. |properties.description |keywords |optional |A list of free-form keywords or tags associated with the resource. |properties.keyword |language |optional |The natural language used for textual values (i.e. titles, descriptions, etc) of a resource. |properties.language