From 8bf5c2a686ff5b27a2fc5cef4153b85ceec16e96 Mon Sep 17 00:00:00 2001 From: Panagiotis Vretanos Date: Tue, 26 Sep 2023 18:29:52 -0400 Subject: [PATCH] Changes to close issues #304, #302, #300, #280, #276, #168. --- core/openapi/schemas/catalog.yaml | 95 ++ core/openapi/schemas/catalogue.yaml | 72 -- core/openapi/schemas/recordGeoJSON.yaml | 75 +- core/standard/20-004.adoc | 26 +- core/standard/annex_common.adoc | 2 +- core/standard/annex_summary.adoc | 25 +- core/standard/clause_0_front_material.adoc | 25 +- .../clause_10_crawlable_catalogue.adoc | 79 -- ..._security.adoc => clause_10_security.adoc} | 0 .../clause_11_searchable_catalogue.adoc | 34 - .../clause_12_local_resources_catalogue.adoc | 314 ----- core/standard/clause_13_sorting.adoc | 82 -- core/standard/clause_14_record-filter.adoc | 213 ---- core/standard/clause_15_autodiscovery.adoc | 16 - core/standard/clause_16_encodings.adoc | 53 - core/standard/clause_1_scope.adoc | 4 +- core/standard/clause_2_conformance.adoc | 126 +- .../clause_4_terms_and_definitions.adoc | 13 +- core/standard/clause_6_overview.adoc | 51 +- core/standard/clause_7_building_blocks.adoc | 1046 +++++++++++++++++ core/standard/clause_7_record.adoc | 257 ---- core/standard/clause_8_collection.adoc | 79 -- core/standard/clause_8_deployments.adoc | 375 ++++++ core/standard/clause_9_api.adoc | 172 --- ...a_types.adoc => clause_9_media_types.adoc} | 18 +- .../PER_autodiscovery_links.adoc | 2 +- .../PER_additional-collection-properties.adoc | 8 + .../PER_common-mark.adoc | 4 +- .../REC_collection-links.adoc | 8 + .../REC_record-file-location.adoc | 7 + .../REC_record-file-name.adoc | 4 +- .../PER_additions-collections-properties.adoc | 9 - .../REC_collections-links.adoc | 8 - .../REC_record-file-location.adoc | 7 - .../recommendations/json/PER_time.adoc | 7 + .../PER_additional-properties.adoc | 4 +- .../PER_common-mark.adoc | 4 +- .../REC_additional-query-parameters.adoc | 2 +- ...urces-catalogue_additional-properties.adoc | 0 .../local-resources-catalog/REC_param-q.adoc | 10 + .../REC_param-type.adoc | 4 +- .../REC_property-extent.adoc | 4 +- .../REC_property-links.adoc | 4 +- .../REC_json-encoding.adoc | 4 +- .../REC_text-encoding.adoc | 4 +- .../REC_param-q.adoc | 11 - ...es.adoc => PER_additional-properties.adoc} | 0 .../REC_additional-query-parameters.adoc | 30 + .../REC_param-q.adoc | 10 + .../REC_query-param-type-definition.adoc | 6 + ... => PER_additional-properties-record.adoc} | 4 +- .../record-core/REC_record-lang.adoc | 6 +- .../record-core/REC_resource-langs.adoc | 2 +- .../record-core/REQ_links.adoc | 7 + .../record-filter/REC_json-encoding.adoc | 4 +- .../record-filter/REC_text-encoding.adoc | 4 +- .../records-api/PER_conformance-classes.adoc | 2 +- .../REC_additional-query-parameters.adoc | 29 - .../recommendations/records-api/REC_html.adoc | 2 +- .../recommendations/records-api/REC_json.adoc | 4 +- .../records-api/REC_param-q.adoc | 10 - .../REC_query-param-type-definition.adoc | 6 - .../PER_additional-properties.adoc | 2 +- .../PER_additional-requirements.adoc | 2 +- .../REQ_additional-queryables.adoc | 8 + .../REQ_additional-queryables.adoc | 8 - .../autodiscovery/REQ_autodiscovery_link.adoc | 8 +- .../OLD}/REQ_collections.adoc | 4 +- .../crawlable-catalog/REQ_catalog-links.adoc | 13 + .../REQ_catalog-location.adoc | 7 + .../crawlable-catalog/REQ_catalog.adoc | 7 + .../REQ_collection-links.adoc | 12 + .../REQ_collection-location.adoc | 7 + .../crawlable-catalog/REQ_collection.adoc | 7 + .../crawlable-catalog/REQ_itemType.adoc | 11 + .../REQ_record-file-location.adoc | 7 + .../REQ_record-links.adoc | 6 +- .../REQ_record.adoc | 4 +- .../REQ_collection-links.adoc | 13 - .../REQ_collection-location.adoc | 7 - .../crawlable-catalogue/REQ_collection.adoc | 7 - .../REQ_collections-links.adoc | 11 - .../REQ_record-file-location.adoc | 7 - .../requirements/geojson/REQ_conformance.adoc | 7 - .../{geojson => json}/REQ_api-common.adoc | 4 +- .../json/REQ_collection-content.adoc | 7 + .../json/REQ_collection-response.adoc | 8 + .../requirements/json/REQ_conformance.adoc | 7 + .../REQ_record-content.adoc} | 4 +- .../REQ_record-response.adoc} | 4 +- .../OLD}/REQ_param-bbox-def.adoc | 4 +- .../OLD}/REQ_param-bbox-response.adoc | 4 +- .../OLD}/REQ_param-datetime-def.adoc | 4 +- .../OLD}/REQ_param-datetime-response.adoc | 4 +- .../OLD}/REQ_param-limit-def.adoc | 4 +- .../OLD}/REQ_param-limit-response.adoc | 4 +- .../OLD}/REQ_param-q-def.adoc | 4 +- .../OLD}/REQ_param-q-response.adoc | 4 +- .../OLD}/REQ_param-type-def.adoc | 4 +- .../OLD}/REQ_param-type-response.adoc | 4 +- .../REQ_property-created.adoc | 4 +- .../REQ_property-description.adoc | 8 + .../REQ_property-keywords.adoc | 4 +- .../REQ_property-title.adoc | 7 + .../REQ_property-type.adoc | 4 +- .../REQ_property-updated.adoc | 4 +- .../REQ_query-parameters.adoc | 7 + .../REQ_response.adoc | 6 +- .../REQ_filter-crs-param.adoc | 6 +- .../REQ_filter-lang-param.adoc | 7 + .../REQ_filter-param.adoc | 7 + .../REQ_filter-response.adoc | 10 + .../REQ_queryables-link.adoc | 4 +- .../REQ_param-sortby-def.adoc | 4 +- .../REQ_param-sortby-response.adoc | 4 +- .../REQ_property-description.adoc | 8 - .../REQ_property-title.adoc | 7 - .../REQ_filter-lang-param.adoc | 7 - .../REQ_filter-param.adoc | 7 - .../REQ_filter-response.adoc | 10 - .../record-collection/REQ_links.adoc | 4 +- ...les.adoc => REQ_mandatory-properties.adoc} | 4 +- .../REQ_query-param-bbox.adoc | 7 + .../REQ_query-param-datetime.adoc | 7 + ...REQ_query-param-externalid-definition.adoc | 19 + .../REQ_query-param-externalid-response.adoc | 4 +- .../REQ_query-param-ids-definition.adoc | 23 + .../REQ_query-param-ids-response.adoc | 7 + .../REQ_query-param-limit.adoc | 7 + .../REQ_query-param-q-definition.adoc | 6 +- .../REQ_query-param-q-response.adoc | 4 +- .../REQ_query-param-type-definition.adoc | 6 +- .../REQ_query-param-type-response.adoc | 4 +- .../REQ_mandatory-properties-record.adoc | 7 + .../REQ_mandatory-queryables-record.adoc | 7 - .../record-core/REQ_record-license.adoc | 2 +- .../record-core/REQ_record-links.adoc | 2 +- .../records-api/REQ_conformance-classes.adoc | 7 +- ...REQ_query-param-externalid-definition.adoc | 19 - .../REQ_record-collection-response.adoc | 6 +- .../REQ_record-collections-response.adoc | 4 +- ...requirements_class_crawlable-catalog.adoc} | 6 +- .../requirements_class_geojson.adoc | 13 - .../requirements/requirements_class_json.adoc | 13 + ...rements_class_local-resources-catalog.adoc | 9 + ...ass_local-resources-catalog_filtering.adoc | 9 + ...class_local-resources-catalog_sorting.adoc | 9 + ...ments_class_local-resources-catalogue.adoc | 9 - ...local-resources-catalogue_cql2-filter.adoc | 9 - ...ass_local-resources-catalogue_sorting.adoc | 7 - .../requirements_class_record-collection.adoc | 2 +- ...ts_class_record-core-query-parameters.adoc | 8 + .../requirements_class_record-core.adoc | 2 +- .../requirements_class_record-filter.adoc | 4 +- .../requirements_class_records-api.adoc | 4 +- ...equirements_class_searchable-catalog.adoc} | 9 +- ...ts_class_searchable-catalog_filtering.adoc | 9 + ...nts_class_searchable-catalog_sorting.adoc} | 6 +- ...lass_searchable-catalogue_cql2-filter.adoc | 9 - .../REQ_core.adoc | 11 +- .../REQ_mandatory-properties.adoc | 7 + .../REQ_crs.adoc | 4 +- .../REQ_filtering.adoc | 7 + .../REQ_mandatory-queryables.adoc | 6 + .../REQ_sorting.adoc | 7 + .../REQ_mandatory-properties.adoc | 7 - .../REQ_filtering.adoc | 7 - .../REQ_mandatory-queryables.adoc | 6 - .../REQ_sorting.adoc | 7 - .../REQ_defaultSortOrder-definition.adoc | 2 +- .../sorting/REQ_sortby-definition.adoc | 2 +- 171 files changed, 2263 insertions(+), 1960 deletions(-) create mode 100644 core/openapi/schemas/catalog.yaml delete mode 100644 core/openapi/schemas/catalogue.yaml delete mode 100644 core/standard/clause_10_crawlable_catalogue.adoc rename core/standard/{clause_18_security.adoc => clause_10_security.adoc} (100%) delete mode 100644 core/standard/clause_11_searchable_catalogue.adoc delete mode 100644 core/standard/clause_12_local_resources_catalogue.adoc delete mode 100644 core/standard/clause_13_sorting.adoc delete mode 100644 core/standard/clause_14_record-filter.adoc delete mode 100644 core/standard/clause_15_autodiscovery.adoc delete mode 100644 core/standard/clause_16_encodings.adoc create mode 100644 core/standard/clause_7_building_blocks.adoc delete mode 100644 core/standard/clause_7_record.adoc delete mode 100644 core/standard/clause_8_collection.adoc create mode 100644 core/standard/clause_8_deployments.adoc delete mode 100644 core/standard/clause_9_api.adoc rename core/standard/{clause_17_media_types.adoc => clause_9_media_types.adoc} (84%) create mode 100644 core/standard/recommendations/crawlable-catalog/PER_additional-collection-properties.adoc rename core/standard/recommendations/{crawlable-catalogue => crawlable-catalog}/PER_common-mark.adoc (61%) create mode 100644 core/standard/recommendations/crawlable-catalog/REC_collection-links.adoc create mode 100644 core/standard/recommendations/crawlable-catalog/REC_record-file-location.adoc rename core/standard/recommendations/{crawlable-catalogue => crawlable-catalog}/REC_record-file-name.adoc (51%) delete mode 100644 core/standard/recommendations/crawlable-catalogue/PER_additions-collections-properties.adoc delete mode 100644 core/standard/recommendations/crawlable-catalogue/REC_collections-links.adoc delete mode 100644 core/standard/recommendations/crawlable-catalogue/REC_record-file-location.adoc create mode 100644 core/standard/recommendations/json/PER_time.adoc rename core/standard/recommendations/{local-resources-catalogue => local-resources-catalog}/PER_additional-properties.adoc (89%) rename core/standard/recommendations/{local-resources-catalogue => local-resources-catalog}/PER_common-mark.adoc (65%) rename core/standard/recommendations/{local-resources-catalogue => local-resources-catalog}/REC_additional-query-parameters.adoc (94%) rename core/standard/recommendations/{local-resources-catalogue => local-resources-catalog}/REC_local-resources-catalogue_additional-properties.adoc (100%) create mode 100644 core/standard/recommendations/local-resources-catalog/REC_param-q.adoc rename core/standard/recommendations/{local-resources-catalogue => local-resources-catalog}/REC_param-type.adoc (76%) rename core/standard/recommendations/{local-resources-catalogue => local-resources-catalog}/REC_property-extent.adoc (71%) rename core/standard/recommendations/{local-resources-catalogue => local-resources-catalog}/REC_property-links.adoc (79%) rename core/standard/recommendations/{local-resources-catalogue_cql2-filter => local-resources-catalog_filtering}/REC_json-encoding.adoc (75%) rename core/standard/recommendations/{local-resources-catalogue_cql2-filter => local-resources-catalog_filtering}/REC_text-encoding.adoc (75%) delete mode 100644 core/standard/recommendations/local-resources-catalogue/REC_param-q.adoc rename core/standard/recommendations/record-collection/{PER_additional-queryables.adoc => PER_additional-properties.adoc} (100%) create mode 100644 core/standard/recommendations/record-core-query-parameters/REC_additional-query-parameters.adoc create mode 100644 core/standard/recommendations/record-core-query-parameters/REC_param-q.adoc create mode 100644 core/standard/recommendations/record-core-query-parameters/REC_query-param-type-definition.adoc rename core/standard/recommendations/record-core/{PER_additional-queryables-record.adoc => PER_additional-properties-record.adoc} (60%) create mode 100644 core/standard/recommendations/record-core/REQ_links.adoc delete mode 100644 core/standard/recommendations/records-api/REC_additional-query-parameters.adoc delete mode 100644 core/standard/recommendations/records-api/REC_param-q.adoc delete mode 100644 core/standard/recommendations/records-api/REC_query-param-type-definition.adoc rename core/standard/recommendations/{searchable-catalogue => searchable-catalog}/PER_additional-properties.adoc (61%) rename core/standard/recommendations/{searchable-catalogue => searchable-catalog}/PER_additional-requirements.adoc (86%) create mode 100644 core/standard/recommendations/searchable-catalog_filtering/REQ_additional-queryables.adoc delete mode 100644 core/standard/recommendations/searchable-catalogue_cql2-filter/REQ_additional-queryables.adoc rename core/standard/requirements/{crawlable-catalogue => crawlable-catalog/OLD}/REQ_collections.adoc (56%) create mode 100644 core/standard/requirements/crawlable-catalog/REQ_catalog-links.adoc create mode 100644 core/standard/requirements/crawlable-catalog/REQ_catalog-location.adoc create mode 100644 core/standard/requirements/crawlable-catalog/REQ_catalog.adoc create mode 100644 core/standard/requirements/crawlable-catalog/REQ_collection-links.adoc create mode 100644 core/standard/requirements/crawlable-catalog/REQ_collection-location.adoc create mode 100644 core/standard/requirements/crawlable-catalog/REQ_collection.adoc create mode 100644 core/standard/requirements/crawlable-catalog/REQ_itemType.adoc create mode 100644 core/standard/requirements/crawlable-catalog/REQ_record-file-location.adoc rename core/standard/requirements/{crawlable-catalogue => crawlable-catalog}/REQ_record-links.adoc (69%) rename core/standard/requirements/{crawlable-catalogue => crawlable-catalog}/REQ_record.adoc (54%) delete mode 100644 core/standard/requirements/crawlable-catalogue/REQ_collection-links.adoc delete mode 100644 core/standard/requirements/crawlable-catalogue/REQ_collection-location.adoc delete mode 100644 core/standard/requirements/crawlable-catalogue/REQ_collection.adoc delete mode 100644 core/standard/requirements/crawlable-catalogue/REQ_collections-links.adoc delete mode 100644 core/standard/requirements/crawlable-catalogue/REQ_record-file-location.adoc delete mode 100644 core/standard/requirements/geojson/REQ_conformance.adoc rename core/standard/requirements/{geojson => json}/REQ_api-common.adoc (74%) create mode 100644 core/standard/requirements/json/REQ_collection-content.adoc create mode 100644 core/standard/requirements/json/REQ_collection-response.adoc create mode 100644 core/standard/requirements/json/REQ_conformance.adoc rename core/standard/requirements/{geojson/REQ_content.adoc => json/REQ_record-content.adoc} (88%) rename core/standard/requirements/{geojson/REQ_response.adoc => json/REQ_record-response.adoc} (88%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog/OLD}/REQ_param-bbox-def.adoc (76%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog/OLD}/REQ_param-bbox-response.adoc (81%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog/OLD}/REQ_param-datetime-def.adoc (76%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog/OLD}/REQ_param-datetime-response.adoc (90%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog/OLD}/REQ_param-limit-def.adoc (76%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog/OLD}/REQ_param-limit-response.adoc (83%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog/OLD}/REQ_param-q-def.adoc (83%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog/OLD}/REQ_param-q-response.adoc (60%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog/OLD}/REQ_param-type-def.adoc (75%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog/OLD}/REQ_param-type-response.adoc (65%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog}/REQ_property-created.adoc (76%) create mode 100644 core/standard/requirements/local-resources-catalog/REQ_property-description.adoc rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog}/REQ_property-keywords.adoc (68%) create mode 100644 core/standard/requirements/local-resources-catalog/REQ_property-title.adoc rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog}/REQ_property-type.adoc (78%) rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog}/REQ_property-updated.adoc (77%) create mode 100644 core/standard/requirements/local-resources-catalog/REQ_query-parameters.adoc rename core/standard/requirements/{local-resources-catalogue => local-resources-catalog}/REQ_response.adoc (52%) rename core/standard/requirements/{local-resources-catalogue_cql2-filter => local-resources-catalog_filtering}/REQ_filter-crs-param.adoc (50%) create mode 100644 core/standard/requirements/local-resources-catalog_filtering/REQ_filter-lang-param.adoc create mode 100644 core/standard/requirements/local-resources-catalog_filtering/REQ_filter-param.adoc create mode 100644 core/standard/requirements/local-resources-catalog_filtering/REQ_filter-response.adoc rename core/standard/requirements/{local-resources-catalogue_cql2-filter => local-resources-catalog_filtering}/REQ_queryables-link.adoc (71%) rename core/standard/requirements/{local-resources-catalogue_sorting => local-resources-catalog_sorting}/REQ_param-sortby-def.adoc (67%) rename core/standard/requirements/{local-resources-catalogue_sorting => local-resources-catalog_sorting}/REQ_param-sortby-response.adoc (69%) delete mode 100644 core/standard/requirements/local-resources-catalogue/REQ_property-description.adoc delete mode 100644 core/standard/requirements/local-resources-catalogue/REQ_property-title.adoc delete mode 100644 core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-lang-param.adoc delete mode 100644 core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-param.adoc delete mode 100644 core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-response.adoc rename core/standard/requirements/record-collection/{REQ_mandatory-queryables.adoc => REQ_mandatory-properties.adoc} (70%) create mode 100644 core/standard/requirements/record-core-query-parameters/REQ_query-param-bbox.adoc create mode 100644 core/standard/requirements/record-core-query-parameters/REQ_query-param-datetime.adoc create mode 100644 core/standard/requirements/record-core-query-parameters/REQ_query-param-externalid-definition.adoc rename core/standard/requirements/{records-api => record-core-query-parameters}/REQ_query-param-externalid-response.adoc (62%) create mode 100644 core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-definition.adoc create mode 100644 core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-response.adoc create mode 100644 core/standard/requirements/record-core-query-parameters/REQ_query-param-limit.adoc rename core/standard/requirements/{records-api => record-core-query-parameters}/REQ_query-param-q-definition.adoc (72%) rename core/standard/requirements/{records-api => record-core-query-parameters}/REQ_query-param-q-response.adoc (56%) rename core/standard/requirements/{records-api => record-core-query-parameters}/REQ_query-param-type-definition.adoc (55%) rename core/standard/requirements/{records-api => record-core-query-parameters}/REQ_query-param-type-response.adoc (61%) create mode 100644 core/standard/requirements/record-core/REQ_mandatory-properties-record.adoc delete mode 100644 core/standard/requirements/record-core/REQ_mandatory-queryables-record.adoc delete mode 100644 core/standard/requirements/records-api/REQ_query-param-externalid-definition.adoc rename core/standard/requirements/{requirements_class_crawlable-catalogue.adoc => requirements_class_crawlable-catalog.adoc} (71%) delete mode 100644 core/standard/requirements/requirements_class_geojson.adoc create mode 100644 core/standard/requirements/requirements_class_json.adoc create mode 100644 core/standard/requirements/requirements_class_local-resources-catalog.adoc create mode 100644 core/standard/requirements/requirements_class_local-resources-catalog_filtering.adoc create mode 100644 core/standard/requirements/requirements_class_local-resources-catalog_sorting.adoc delete mode 100644 core/standard/requirements/requirements_class_local-resources-catalogue.adoc delete mode 100644 core/standard/requirements/requirements_class_local-resources-catalogue_cql2-filter.adoc delete mode 100644 core/standard/requirements/requirements_class_local-resources-catalogue_sorting.adoc create mode 100644 core/standard/requirements/requirements_class_record-core-query-parameters.adoc rename core/standard/requirements/{requirements_class_searchable-catalogue.adoc => requirements_class_searchable-catalog.adoc} (61%) create mode 100644 core/standard/requirements/requirements_class_searchable-catalog_filtering.adoc rename core/standard/requirements/{requirements_class_searchable-catalogue_sorting.adoc => requirements_class_searchable-catalog_sorting.adoc} (60%) delete mode 100644 core/standard/requirements/requirements_class_searchable-catalogue_cql2-filter.adoc rename core/standard/requirements/{searchable-catalogue => searchable-catalog}/REQ_core.adoc (63%) create mode 100644 core/standard/requirements/searchable-catalog/REQ_mandatory-properties.adoc rename core/standard/requirements/{searchable-catalogue_crs => searchable-catalog_crs}/REQ_crs.adoc (76%) create mode 100644 core/standard/requirements/searchable-catalog_filtering/REQ_filtering.adoc create mode 100644 core/standard/requirements/searchable-catalog_filtering/REQ_mandatory-queryables.adoc create mode 100644 core/standard/requirements/searchable-catalog_sorting/REQ_sorting.adoc delete mode 100644 core/standard/requirements/searchable-catalogue/REQ_mandatory-properties.adoc delete mode 100644 core/standard/requirements/searchable-catalogue_cql2-filter/REQ_filtering.adoc delete mode 100644 core/standard/requirements/searchable-catalogue_cql2-filter/REQ_mandatory-queryables.adoc delete mode 100644 core/standard/requirements/searchable-catalogue_sorting/REQ_sorting.adoc diff --git a/core/openapi/schemas/catalog.yaml b/core/openapi/schemas/catalog.yaml new file mode 100644 index 00000000..95027cbc --- /dev/null +++ b/core/openapi/schemas/catalog.yaml @@ -0,0 +1,95 @@ +--- +allOf: + $ref: "http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/\ + schemas/collection.yaml" + type: object + required: + - title + - type + - itemType + properties: + type: + type: string + enum: + - catalog + itemType: + description: + The itemType type can be a string with the value of + "record" to indicate that this object is a catalog + (i.e. a collection of records). + If the itemType is an array, this indicates that + this object is a general collection that can point + to other catalogs, records and/or other related + resources. + oneOf: + - type: string + enum: + - record + - type: array + items: + type: string + enum: + - record + - catalog + - collection + - other + conformsTo: + description: + If all records (`itemType=record`) of the catalog + conform to same set of extensions/conformance classes + then this member may be used to advertise this fact + rather than copying this information into each record. + $ref: common/confClasses.yaml#/properties/conformsTo + created: + type: string + description: + Date of creation of this catalog. + format: date-time + updated: + type: string + description: + The most recent date on which this catalog was + changed. + format: date-time + keywords: + type: array + description: + The topic or topics of the catalog. Typically + represented using free-form keywords, tags, key + phrases, or classification codes. + items: + type: string + language: + description: + The language used for textual values for this + catalog object. + $ref: language.yaml + languages: + type: array + description: + This list of other languages in which this + catalog object can be retrieved. + items: + $ref: language.yaml + themes: + type: array + description: + A knowledge organization system used to classify + the resource. + minItems: 1 + items: + $ref: theme.yaml + contacts: + type: array + description: + A list of contacts qualified by their role(s). + items: + $ref: contact.yaml + license: + $ref: license.yaml + rights: + type: string + description: + A statement that concerns all rights not addresses + by the license such as a copyright statement. + additionalProperties: true diff --git a/core/openapi/schemas/catalogue.yaml b/core/openapi/schemas/catalogue.yaml deleted file mode 100644 index 23ddb8ea..00000000 --- a/core/openapi/schemas/catalogue.yaml +++ /dev/null @@ -1,72 +0,0 @@ ---- -allOf: - $ref: "http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/\ - schemas/collection.yaml" - type: object - required: - - title - - itemType - - type - properties: - itemType: - enum: - - record - conformsTo: - description: - If all records of the catalogue conform to same set of - extensions/conformance classes then this member can be - used to advertise that fact rather than copying this - information into each record. - $ref: common/confClasses.yaml#/properties/conformsTo - created: - type: string - description: - Date of creation of this catalogue. - format: date-time - updated: - type: string - description: - The most recent date on which this catalogue was changed. - format: date-time - keywords: - type: array - description: - The topic or topics of the catalogue. Typically represented using - free-form keywords, tags, key phrases, or classification codes. - items: - type: string - language: - description: - The language used for textual values for this catalogue object. - $ref: language.yaml - languages: - type: array - description: - This list of other languages in which this catalogue object can - be retrieved. - items: - $ref: language.yaml - themes: - type: array - description: - A knowledge organization system used to classify the resource. - minItems: 1 - items: - $ref: theme.yaml - contacts: - type: array - description: - A list of contacts qualified by their role(s). - items: - $ref: contact.yaml - license: - type: string - description: - A legal document under which the catalogue is made available. - format: uri - rights: - type: string - description: - A statement that concerns all rights not addresses by the license - such as a copyright statement. - additionalProperties: true diff --git a/core/openapi/schemas/recordGeoJSON.yaml b/core/openapi/schemas/recordGeoJSON.yaml index 1b538eda..6ad91fc0 100644 --- a/core/openapi/schemas/recordGeoJSON.yaml +++ b/core/openapi/schemas/recordGeoJSON.yaml @@ -40,15 +40,17 @@ properties: updated: type: string description: - The most recent date on which the record was changed. + The most recent date on which the record was + changed. format: date-time type: type: string description: - The nature or genre of the resource. The value should be a code, - convenient for filtering records. Where available, a link to - the canonical URI of the record type resource will be added to - the 'links' property. + The nature or genre of the resource. The value + should be a code, convenient for filtering + records. Where available, a link to the + canonical URI of the record type resource will + be added to the 'links' property. maxLength: 64 title: type: string @@ -61,65 +63,75 @@ properties: keywords: type: array description: - The topic or topics of the resource. Typically represented using - free-form keywords, tags, key phrases, or classification codes. + The topic or topics of the resource. Typically + represented using free-form keywords, tags, + key phrases, or classification codes. items: type: string language: description: - The language used for textual values in this record representation. + The language used for textual values in this + record representation. $ref: language.yaml languages: type: array description: - This list of languages in which this record is available. + This list of languages in which this record + is available. items: $ref: language.yaml resourceLanguages: type: array description: - The list of languages in which the resource described by this - record is available. + The list of languages in which the resource + described by this record is available. items: $ref: language.yaml externalIds: type: array description: - An identifier for the resource assigned by an external (to the - catalogue) entity. + An identifier for the resource assigned by + an external (to the catalogue) entity. items: type: object properties: scheme: type: string description: - A reference to an authority or identifier for a knowledge - organization system from which the external identifier was - obtained. It is recommended that the identifier be a + A reference to an authority or + identifier for a knowledge + organization system from which + the external identifier was + obtained. It is recommended + that the identifier be a resolvable URI. value: type: string - description: The value of the identifier. + description: + The value of the identifier. required: - value themes: type: array description: - A knowledge organization system used to classify the resource. + A knowledge organization system used + to classify the resource. minItems: 1 items: $ref: theme.yaml formats: type: array description: - A list of available distributions of the resource. + A list of available distributions of + the resource. items: type: string contacts: type: array description: - A list of contacts qualified by their role(s) in association to the - record or the resource described by the record. + A list of contacts qualified by their + role(s) in association to the record + or the resource described by the record. items: $ref: contact.yaml license: @@ -127,18 +139,21 @@ properties: rights: type: string description: - A statement that concerns all rights not addressed by the license - such as a copyright statement. + A statement that concerns all rights + not addressed by the license such as + a copyright statement. links: type: array description: - A list of links for accessing the resource (e.g. download link, - access link) 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, etc.). Since the specification requires that at least - the self link be present then the min items for this list should - be one. + A list of links for accessing the resource + (e.g. download link, access link) 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, etc.). Since the + specification requires that at least the self + link be present then the min items for this + list should be one. items: minItems: 1 $ref: common/link.yaml diff --git a/core/standard/20-004.adoc b/core/standard/20-004.adoc index 4f058f5e..9f769792 100644 --- a/core/standard/20-004.adoc +++ b/core/standard/20-004.adoc @@ -83,6 +83,8 @@ toc::[] include::clause_0_front_material.adoc[] +include::clause_10_security.adoc[] + include::clause_1_scope.adoc[] include::clause_2_conformance.adoc[] @@ -95,29 +97,11 @@ include::clause_5_conventions.adoc[] include::clause_6_overview.adoc[] -include::clause_7_record.adoc[] - -include::clause_8_collection.adoc[] - -include::clause_9_api.adoc[] - -include::clause_10_crawlable_catalogue.adoc[] - -include::clause_11_searchable_catalogue.adoc[] - -include::clause_12_local_resources_catalogue.adoc[] - -include::clause_13_sorting.adoc[] - -include::clause_14_record-filter.adoc[] - -include::clause_15_autodiscovery.adoc[] - -include::clause_16_encodings.adoc[] +include::clause_7_building_blocks.adoc[] -include::clause_17_media_types.adoc[] +include::clause_8_deployments.adoc[] -include::clause_18_security.adoc[] +include::clause_9_media_types.adoc[] include::annex_ats.adoc[] diff --git a/core/standard/annex_common.adoc b/core/standard/annex_common.adoc index 02a30a29..bc164a7f 100644 --- a/core/standard/annex_common.adoc +++ b/core/standard/annex_common.adoc @@ -183,7 +183,7 @@ A successful response to the < In a typical API deployment, the <> will list collections of all offered resource types. The collections where the value of the `itemType` property (JSONPath: `$.collections[*].itemType`) -is `record` are collections of records (i.e. catalogues). +is `record` are collections of records (i.e. catalogs). [#collections-schema,reftext='Collections Response Schema'] .Collections Response Schema diff --git a/core/standard/annex_summary.adoc b/core/standard/annex_summary.adoc index 4193ccde..916f8683 100644 --- a/core/standard/annex_summary.adoc +++ b/core/standard/annex_summary.adoc @@ -5,35 +5,34 @@ === Overview -This annex presents implementation summaries for the crawlable catalogue, -searchable catalogue and local resources catalogue deployment patterns. +This annex presents implementation summaries for the crawlable catalog, +searchable catalog and local resources catalog deployment patterns. This information is meant to be a short guide for developers. -=== Crawlable catalogue +=== Crawlable catalog -In order to implement a catalogue where records are stored as individual files in one or more web-accessible locations and can be crawled by simply following hypermedia controls: +In order to implement a catalog where records are stored as individual files in one or more web-accessible locations and can be crawled by simply following hypermedia controls: -* for each discoverable resource create a file that contains a summary description of the resource using the record schema defined in <> and <> +* for each discoverable resource create a file that contains a summary description of the resource using the record schema defined in <> and <> * extend the record schema to enrich its content as necessary * to make the resource discoverable, place each record file in a web-accessible location, preferably co-located (e.g. in the same directory or object store location) with the resource that the record is describing * optionally create a file containing a description of a <> of related records * also place the collection file in a web-accessible location -=== Searchable catalogue +=== Searchable catalog -In order to implement a catalogue where records are stored in some backend database and are accessed through an access/search API: +In order to implement a catalog where records are stored in some backend database and are accessed through an access/search API: * implement the http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Features - Core: Part 1] specification, * implement the parameters defined in <>, -* implement the record schema defined in <> and <>. +* implement the record schema defined in <> and <>. * extend the record schema to enrich its content as necessary -=== Local resources catalogue +=== Local resources catalog -In order to implement a local resource catalogue at an OGC API resources endpoint such as `/collections` for example: +In order to implement a local resource catalog at an OGC API resources endpoint such as `/collections` for example: * implement the endpoint as per the relevant OGC API specification, -* enhance the information content of the resource using the mandatory and optional parameters defined in <>, +* enhance the information content of the resource using the mandatory and optional parameters defined in <>, * implement the query parameters defined in <>, -* optionally implement <>, <>. - +* optionally implement <>, <>. diff --git a/core/standard/clause_0_front_material.adoc b/core/standard/clause_0_front_material.adoc index 471ccf05..9a4e0d68 100644 --- a/core/standard/clause_0_front_material.adoc +++ b/core/standard/clause_0_front_material.adoc @@ -6,22 +6,23 @@ This document defines the OGC API for Records. A Record makes a resource discoverable by providing summary information (metadata) about the resource. In this context, resources are things that would be useful to a user or developer, such as features, coverages, tiles / maps, styles, assets, machine models, services, processes, widgets, etc. -OGC API - Records provides a way to browse or search a curated collection of records known as a catalogue. This specification envisions deploying a catalogue as: +OGC API - Records provides a way to browse or search a curated collection of records known as a catalog. This specification envisions deploying a catalog as: * a collection of static files, * a collection of records accessed via an API. -A catalogue can be deployed as a static collection of records stored in web-accessible files and typically co-located with the resources each record is describing. Such a deployment is amenable to browsing using a web browser or being crawled by a search engine crawler. +A catalog can be deployed as a static collection of records stored in web-accessible files and typically co-located with the resources each record is describing. Such a deployment is amenable to browsing using a web browser or being crawled by a search engine crawler. -A catalogue can also be deployed as an API with well known endpoints for retrieving information about the catalogue, retrieving records from the catalogue and searching the catalogue for sub-sets of records that satisfy user-defined search criteria. +A catalog can also be deployed as an API with well known endpoints for retrieving information about the catalog, retrieving records from the catalog and searching the catalog for sub-sets of records that satisfy user-defined search criteria. -To enable this kind of flexible deployment of a collection of records, this specification defined the following set of building blocks: +To enable this kind of flexible deployment of a collection of records, this specification defines the following set of building blocks: -* the record, -* the collection (of records), -* and the search API. +* a record, +* a collection (of records), +* a set of common query parameters +* and a search API. -A record is the atomic unit of information in a catalogue, It contains descriptive information (metadata) about a resource such as: +A record is the atomic unit of information in a catalog, It contains descriptive information (metadata) about a resource such as: * a title, * a human readable description of the resource, @@ -33,7 +34,7 @@ A record is the atomic unit of information in a catalogue, It contains descripti This information is generic and can be used to describe a wide variety of resources. This specification expects and encourages implementations to enrich the information content of a record to suit specific use cases or requirements. -A collection of records is itself described by a record that provides descriptive information about the catalogue. The collection also provides access to the records of the collection either by explicitly linking to each record that is an item of the collection or by providing a search endpoint that allows the collection of records to be searched. +A collection of records is itself described by a record that provides descriptive information about the catalog. The collection also provides access to the records of the collection either by explicitly linking to each record that is an item of the collection or by providing a search endpoint that allows the collection of records to be searched. The search API allows collections of records to be searched using logically connected spatial, temporal and scalar predicates. This standard uses the https://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] specification as the core of the Records search API. Additional parts from the https://ogcapi.ogc.org/features/[OGC API - Features] suite of standards can also be implemented to enhance the capabilities of the search API. The following table lists the endpoints of the core OGC API - Records API that allow a collection of records to be searched: @@ -50,14 +51,14 @@ The search API allows collections of records to be searched using logically conn |Record |`/collections/{collectionId}/items/{recordId}` |GET |<> |=== -A special use case of the catalogue deployed as an API is the _local resources catalogue_. A local resources catalogue is a catalogue deployed to make local resources offered by a provider searchable using the catalogue information model and API. An example of a local resources catalogue is the `/collections` endpoint of http://docs.opengeospatial.org/DRAFTS/20-024.html[OGC API - Common - Part 2: Geospatial data] or http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core]. Adding catalogue capabilities to this endpoint allows a client to search for collections that satisfy a specified filter expression. Any API endpoint whose function is to provide a list of resources, such as the `/collections` endpoint, can be extended to be a local resources catalogue. +A special use case of the catalog deployed as an API is the _local resources catalog_. A local resources catalog is a catalog deployed to make local resources offered by a provider searchable using the catalog information model and API. An example of a local resources catalog is the `/collections` endpoint of http://docs.opengeospatial.org/DRAFTS/20-024.html[OGC API - Common - Part 2: Geospatial data] or http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core]. Adding catalog capabilities to this endpoint allows a client to search for collections that satisfy a specified filter expression. Any API endpoint whose function is to provide a list of resources, such as the `/collections` endpoint, can be extended to be a local resources catalog. [[keywords]] [big]*ii. Keywords* -The following are keywords to be used by search engines and document catalogues. +The following are keywords to be used by search engines and document catalogs. -ogcdoc, OGC document, OGC API, catalogue, record, records, resource, metadata, discovery, CSW, API, GeoJSON, HTML, schema.org, JSON-LD +ogcdoc, OGC document, OGC API, catalog, record, records, resource, metadata, discovery, CSW, API, GeoJSON, HTML, schema.org, JSON-LD [[preface]] [big]*iii. Preface* diff --git a/core/standard/clause_10_crawlable_catalogue.adoc b/core/standard/clause_10_crawlable_catalogue.adoc deleted file mode 100644 index e5344be8..00000000 --- a/core/standard/clause_10_crawlable_catalogue.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[[clause-crawlable-catalogue]] -== Requirements Class "Crawlable Catalogue" - -[[crawlable-catalogue-overview]] -=== Overview - -include::requirements/requirements_class_crawlable-catalogue.adoc[] - -The `Crawlable Catalogue` Requirements Class defines the requirements for a catalogue composed of static, web-accessible files. - -The goal of a crawlable catalogue is to expose metadata about resources online with as low an entry barrier as possible, thus making those resource more easily discoverable. - -A crawlable catalogue is a deployment pattern that uses the <> and <> building blocks defined in this standard. It is simply a set of files deployed on the web that encode, usually in HTML or JSON, the <> and <> defined in this standard. The files contain embedded links to enable navigation from one to another. Any HTTP server or cloud storage service, for example, could be used to expose the files of a crawlable catalogue. - -A crawlable catalogue is not searchable and does not respond to query requests. As the name implies, it can only be crawled (or harvested) by following the embedded links; typically by search engines and other active catalogues or browsed using a web browser. However, due to its simplicity, a crawlable catalogue is easy to deploy and maintain, and is very reliable. - -NOTE: It should be pointed out that a <> can also behave as a crawlable catalogue as long as the requirements in this clause are satisfied by the <> implementation. - -[[crawlable-catalogue-record]] -=== Making a resource discoverable - -include::requirements/crawlable-catalogue/REQ_record.adoc[] - -Attention is drawn to requirement <> that allows the information content of the record to be enriched as required to describe the resource being made discoverable. - -include::requirements/crawlable-catalogue/REQ_record-links.adoc[] - -include::requirements/crawlable-catalogue/REQ_record-file-location.adoc[] - -include::recommendations/crawlable-catalogue/REC_record-file-name.adoc[] - -include::recommendations/crawlable-catalogue/REC_record-file-location.adoc[] - -For example, the record file could be placed in the same web-accessible directory or object store as the resource(s) that the record describes. - -[[crawlable-catalogue]] -=== Grouping a collection of records into a catalogue - -include::requirements/crawlable-catalogue/REQ_collection.adoc[] - -include::requirements/crawlable-catalogue/REQ_collection-location.adoc[] - -include::requirements/crawlable-catalogue/REQ_collection-links.adoc[] - -=== Collections of catalogue resources - -In order to provide flexibility with regard to how crawlable catalogues can be organized (e.g. a hierarchy) a _collections object_ is defined that may be used as a common entry point for crawling to multiple, related, sub-collections, catalogues, records and other resources. - -<> defines the set of properties for a collections object. - -[#collections-properties-table,reftext='{table-caption} {counter:table-num}'] -.Table of properties for a collections object -[cols="30,5,65",options="header"] -|=== -|Queryables |Requirement |Description -|_**id**_ |**required** |A unique identifier for this collections object. -|_**title**_ |**required** |A human-readable name given to this collections object. -|_**description**_ |optional |A free-text description of this collections object. -|_**links**_ |**required** |A list of links related to this collection. -|_**extent**_ |optional |The spatio-temporal coverage of this collections object. -|_**crs**_ |optional |A list of coordinate reference systems used for spatial-temporal values. -|type |**required** |The nature or genre of this resource. Fixed to "Collection". -|keywords |optional |A list of free-form keywords or tags associated with this collections object. -|language |optional |The natural language used for textual values (i.e. titles, descriptions, etc) of this collections object. -|created |optional |The date this collections object was created. -|updated |optional |The more recent date on which this collections object was changed. -|contacts |optional |A list of contacts qualified by their role(s). -|themes |optional |A knowledge organization system used to classify this collections object. -|license |optional |The legal provisions under which this collections object is made available. -|rights |optional |A statement that concerns all rights not addressed by the license such as a copyright statement. -|=== - -include::requirements/crawlable-catalogue/REQ_collections.adoc[] - -include::recommendations/crawlable-catalogue/PER_additions-collections-properties.adoc[] - -include::requirements/crawlable-catalogue/REQ_collections-links.adoc[] - -include::recommendations/crawlable-catalogue/REC_collections-links.adoc[] diff --git a/core/standard/clause_18_security.adoc b/core/standard/clause_10_security.adoc similarity index 100% rename from core/standard/clause_18_security.adoc rename to core/standard/clause_10_security.adoc diff --git a/core/standard/clause_11_searchable_catalogue.adoc b/core/standard/clause_11_searchable_catalogue.adoc deleted file mode 100644 index 7c84a82b..00000000 --- a/core/standard/clause_11_searchable_catalogue.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[[clause-searchable-catalogue]] -== Requirements Class "Searchable Catalogue" - -include::requirements/requirements_class_searchable-catalogue.adoc[] - -The `Searchable Catalogue` Requirements Class defines the requirements for a catalogue that is searchable through an API. A searchable catalogue is an implementation of <> that uses a defined information model. In the case of OGC API - Records, that information model is the <>. - -=== Core - -include::requirements/searchable-catalogue/REQ_core.adoc[] - -include::recommendations/searchable-catalogue/PER_additional-requirements.adoc[] - -include::requirements/searchable-catalogue/REQ_mandatory-properties.adoc[] - -include::recommendations/searchable-catalogue/PER_additional-properties.adoc[] - -[[clause-searchable-catalogue_sorting]] -=== Sorting - -include::requirements/searchable-catalogue_sorting/REQ_sorting.adoc[] - -[[clause-searchable-catalogue_cql2-filter]] -=== Filtering - -include::requirements/searchable-catalogue_cql2-filter/REQ_filtering.adoc[] - -include::requirements/searchable-catalogue_cql2-filter/REQ_mandatory-queryables.adoc[] - -include::recommendations/searchable-catalogue_cql2-filter/REQ_additional-queryables.adoc[] - -=== Coordinate reference systems - -include::requirements/searchable-catalogue_crs/REQ_crs.adoc[] diff --git a/core/standard/clause_12_local_resources_catalogue.adoc b/core/standard/clause_12_local_resources_catalogue.adoc deleted file mode 100644 index 098e671b..00000000 --- a/core/standard/clause_12_local_resources_catalogue.adoc +++ /dev/null @@ -1,314 +0,0 @@ -[[clause-local-resources-catalogue]] -== Requirements Class "Local Resources Catalogue" - -[[local-resources-catalogue-overview]] -=== Overview - -include::requirements/requirements_class_local-resources-catalogue.adoc[] - -This conformance class specifies requirements for a _local resources catalogue_. - -The OGC API defines a number of resource endpoints that provide lists of -sub-resources. These endpoints are referred to as _local resources catalogues_ in this standard because they provide metadata about resources offered locally by an OGC API deployment. - -NOTE: The term _local resources endpoint_ is used to reference to the resource path of the _local resources catalogue_. The term _local resources object_ is used to refer to an instance of the object or resource that can be retrieved from the _local resources endpoint_. - -The `/collections` endpoint is an example of a _local resources endpoint_. This endpoint provides a list of objects describing the collections of items offered by an OGC API deployment. Each offered collection (path `/collections/{collectionId}`) is described by a _local resources object_ containing a small number of properties. A common set of properties is defined in https://docs.ogc.org/DRAFTS/20-024.html[OGC API - Common - Part 2: Geospatial Data] and can be extended by resource-specific specifications (e.g. http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Feature - Part 1: Core]). In this respect, the `/collections` endpoint is a catalogue of records (i.e. `/collections/{collectionId}` objects) describing the collections of items offered by the OGC API deployment. - -Other _local resources catalogues_ available in the OGC API resource tree include the `/processes` endpoint which provides a list of offered processes and the `/collections/{collectionId}/scenes` endpoint which provides a list of source images of a coverage. - -In order to enable catalogue-like searching at these local resources endpoints, this conformance class defines requirements and recommendations that: - -1. enhance the information content of each local resources object (e.g. the `/collection/{collectionId}` object) with additional members from the list of <> defined for a catalogue <>, - -2. define or extend the set of query parameters available at the local resources endpoint (e.g. `/collections`) to enhance it searchability. - -This conformance class does not define the specific endpoints in the OGC API resource tree that should be enabled with catalogue-like query capabilities. It only defines how those endpoints should be enhanced should the requirement for catalogue-line searching be identified by the responsible OGC standard. - -=== Resource Description - -==== Overview - -The clause defines requirements and recommendations for the information content of a local resources object that can be retrieved from local resources endpoint. - -As an example of a local resources endpoint, consider the `/collections` endpoint. The object that can be retrieved from this endpoint is defined in https://docs.ogc.org/DRAFTS/20-024.html[OGC API - Common] and http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collections_[OGC API - Features]. The following table cross-walks the information content of the collection object with the <> defined for the <> building block: - -[[record-collection-crosswalk]] -[reftext='{table-caption} {counter:table-num}'] -.Crosswalk of core queryables with collection information object properties -[cols="25,25,25,25",options="header"] -|=== -|Collection property |Requirement |Core Queryable |Requirement -|id |M |id |M -|title |O |title |M -|description |O |description |M -|itemType |O |-- |-- -|extent |O |extent |O -|links |M |links |O -|crs |O |-- |-- -|=== - -It is evident that there is significant overlap of the properties of each resource. This standard defines the following requirements and recommendations with regard to information content of a local resources object such as the collection object that is retrievable from the `/collections` endpoint. - -==== Property `title` - -include::requirements/local-resources-catalogue/REQ_property-title.adoc[] - -==== Property `description` - -include::requirements/local-resources-catalogue/REQ_property-description.adoc[] - -include::recommendations/local-resources-catalogue/PER_common-mark.adoc[] - -==== Property `extent` - -include::recommendations/local-resources-catalogue/REC_property-extent.adoc[] - -==== Property `links` - -include::recommendations/local-resources-catalogue/REC_property-links.adoc[] - -==== Property `type` - -include::requirements/local-resources-catalogue/REQ_property-type.adoc[] - -==== Property `created` - -include::requirements/local-resources-catalogue/REQ_property-created.adoc[] - -==== Property `updated` - -include::requirements/local-resources-catalogue/REQ_property-updated.adoc[] - -NOTE: Adding, modifying, or deleting items from a collection are all examples of changes that may occur that would require an update of the collection object that can be retrieved from the `/collections` endpoint. - -==== Property `keywords` - -include::requirements/local-resources-catalogue/REQ_property-keywords.adoc[] - -==== Additional properties - -include::recommendations/local-resources-catalogue/PER_additional-properties.adoc[] - -==== Example - -The following JSON Schema fragment illustrates how the feature collections object (path: `/collection/{collectionId}`) can be extended to include properties required and recommended by this conformance class: - -[source,yaml] ----- - allOf: - - $ref: "http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml" - - type: object - required: - - type - - created - - updated - - keywords - properties: - type: - description: - The nature or genre of the items of the collections (e.g. feature, - coverage) - type: string - created: - description: - The date this collection was created in the server. - type: string - format: date-time - updated: - description: - The most recent date on which the collection was updated. - type: string - format: date-time - keywords: - description: - A list of free-form keywords or tag associated with the collection - type: array - items: - type: string - language: - description: - The natural language used for textual values (i.e. titles, - descriptions, etc) of items in the collection. - type: string - themes: - type: array - description: - A knowledge organization system used to classify the resource. - minItems: 1 - items: - type: object - properties: - concepts: - type: array - description: - One or more entity/concept identifers from this knowledge - system. it is recommended that a resolvable URI be used - for each entity/concept identifier. - minItems: 1 - items: - type: object - properties: - id: - type: string - description: - An identifier for the concept. - title: - type: string - description: - A human readable title for the concept. - description: - type: string - description: - A human readable description for the concept. - url: - type: string - format: uri - description: - A URI providing further description of the concept. - required: - - id - scheme: - type: string - description: - An identifier for the knowledge organization system used - to classify the resource. It is recommended that the - identifier be a resolvable URI. - required: - - concepts - - scheme - contacts: - description: - The entity to contact about the collection. - type: array - items: - $ref: contact.yaml - license: - description: - The legal provisions under which the collection is made available. - type: string - rights: - description: - A statement that concerns all rights not addressed by the license - such as a copyright statement. - type: string ----- - -T.D.B. Should add an instance example of a collection object. - -=== Query parameters - -==== Overview - -To enable search capabilities at local resource endpoints, this conformance class defines a set of requirements and recommendations around query parameters that can be implemented at the endpoint. - -[[local-resources-catalogue-bbox-param]] -==== Parameter bbox - -include::requirements/local-resources-catalogue/REQ_param-bbox-def.adoc[] - -include::requirements/local-resources-catalogue/REQ_param-bbox-response.adoc[] - -[[local-resources-catalogue-datetime-param]] -==== Parameter datetime - -include::requirements/local-resources-catalogue/REQ_param-datetime-def.adoc[] - -include::requirements/local-resources-catalogue/REQ_param-datetime-response.adoc[] - -[[local-resources-catalogue-limit-param]] -==== Parameter limit - -include::requirements/local-resources-catalogue/REQ_param-limit-def.adoc[] - -include::requirements/local-resources-catalogue/REQ_param-limit-response.adoc[] - -See all the discussion about the `limit` parameter in the http://docs.ogc.org/is/17-069r3/17-069r3.html#_response_6[Feature response] clause of the http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] standard. - -[[local-resources-catalogue-q-param]] -==== Parameter q - -include::requirements/local-resources-catalogue/REQ_param-q-def.adoc[] - -include::recommendations/local-resources-catalogue/REC_param-q.adoc[] - -include::requirements/local-resources-catalogue/REQ_param-q-response.adoc[] - -[[local-resources-catalogue-type-param]] -==== Parameter type - -include::requirements/local-resources-catalogue/REQ_param-type-def.adoc[] - -include::recommendations/local-resources-catalogue/REC_param-type.adoc[] - -include::requirements/local-resources-catalogue/REQ_param-type-response.adoc[] - -[[local-resources-catalogue-additional-params]] -==== Additional query parameters - -include::recommendations/local-resources-catalogue/REC_additional-query-parameters.adoc[] - -==== Response - -include::requirements/local-resources-catalogue/REQ_response.adoc[] - -[[clause-local-resources-catalogue_sorting]] -=== Requirements Class "Local Resources Catalogue, Sorting" - -include::requirements/requirements_class_local-resources-catalogue_sorting.adoc[] - -This conformance class specifies requirements and recommendations for supporting sorting of responses at _local resource catalogue_ endpoints. - -==== Operation - -include::requirements/local-resources-catalogue_sorting/REQ_param-sortby-def.adoc[] - -==== Response - -include::requirements/local-resources-catalogue_sorting/REQ_param-sortby-response.adoc[] - -See also: <>, <>. - -==== Examples - -Example 1: List all the collections that lie within a specific bounding box and contain the keyword `weather`. - ----- - Client Server - | | - | GET /collections?bbox=41.875315,-96.767601,56.732861,-73.476| - | 586&q=weather HTTP/1.1 | - | Accept: application/json | - |-------------------------------------------------------------->| - | | - | HTTP/1.1 200 OK | - | Content-Type: application/json | - | | - | T.B.D. Need example output here... | - |<--------------------------------------------------------------| ----- - -[[clause-local-resources-catalogue_cql2-filter]] -=== Requirements Class "Local Resources Catalogue - CQL2 Filter" - -include::requirements/requirements_class_local-resources-catalogue_cql2-filter.adoc[] - -This conformance class specifies requirements and recommendations for supporting advanced filtering using CQL2 at _local resource catalogue_ endpoints. - -==== Operation - -include::requirements/local-resources-catalogue_cql2-filter/REQ_filter-param.adoc[] - -include::requirements/local-resources-catalogue_cql2-filter/REQ_filter-lang-param.adoc[] - -include::recommendations/local-resources-catalogue_cql2-filter/REC_text-encoding.adoc[] - -include::recommendations/local-resources-catalogue_cql2-filter/REC_json-encoding.adoc[] - -include::requirements/local-resources-catalogue_cql2-filter/REQ_filter-crs-param.adoc[] - -include::requirements/local-resources-catalogue_cql2-filter/REQ_queryables-link.adoc[] - -==== Response - -include::requirements/local-resources-catalogue_cql2-filter/REQ_filter-response.adoc[] diff --git a/core/standard/clause_13_sorting.adoc b/core/standard/clause_13_sorting.adoc deleted file mode 100644 index 8ded9c35..00000000 --- a/core/standard/clause_13_sorting.adoc +++ /dev/null @@ -1,82 +0,0 @@ -[[clause-sorting]] -== Requirements Class "Sorting" - -[[sorting-overview]] -=== Overview - -include::requirements/requirements_class_sorting.adoc[] - -The `Sorting` Requirements Class defines the requirements for specifying how records in a response should be ordered for presentation. - -[[sorting-parameter-sortby]] -=== Parameter sortby - -include::requirements/sorting/REQ_sortby-definition.adoc[] - -NOTE: The core definition of the `sortby` parameter only defines a single directive that controls the sort order of the corresponding property. It is anticipated extensions would add additional search facets such as directives for: -handling missing values; specifying a high value indicating that the corresponding property be sorted as if it were the highest possible value; specifying a low value indicating that the corresponding property be sorted as if it were the lowest possible value; allowing records to be omitted from the result set based on their sort order; specify a fixed value and a fixed value that sorts the corresponding property as if it were the specified fixed value. - -include::requirements/sorting/REQ_sortby-response.adoc[] - -include::requirements/sorting/REQ_get-sortables-op.adoc[] - -include::requirements/sorting/REQ_get-sortables-success.adoc[] - -The response is returned as a JSON Schema document that describes a single JSON object where each property is a sortable. Note that the sortables schema does not specify a schema of any object that can be retrieved from the API. JSON Schema is used for the sortables to have a consistent approach for describing schema information and JSON Schema is/will be used in other parts of OGC API - Features to describe schemas for GeoJSON feature content including in OpenAPI documents. - -NOTE: The OGC Features API Standards Working Group has a schema harmonization task that could lead to a future OGC API standard that will deprecate the approach for the sortables resource specified in this document. - -To support clients, providing additional detail about the meaning of the sortables is recommended: - -include::recommendations/sorting/REC_sortables-schema.adoc[] - -In an OpenAPI 3.0 document, the Sortables resource has the following schema: - -[[schema_sortables]] -.link:http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/responses/Sortables.yaml[Schema for the list of sortable properties (Sortables.yaml)] -[source,YAML] ----- -include::../openapi/responses/Sortables.yaml[] ----- - -=== Declaring default sort order - -This specification does not mandate a specific default sort order for records -fetched from a searchable catalogue. However, servers can declare a default -sort order. - -include::requirements/sorting/REQ_defaultSortOrder-definition.adoc[] - -=== Examples - -[#defaultSortOrder-example,reftext=`Default Sort Order Example`] -.Default Sort Order Example -[source,json] ----- -include::../examples/json/defaultSortOrder.json[] ----- - -This examples indicates that by default, response records are sorted by the `updated` sortable and the `area` sortable with the most recent record with the largest area being presented first. - -[#sortables-example,reftext=`Sortables Example`] -.Sortables Example -[source,json] ----- -include::../examples/json/sortables.json[] ----- - -[#sortby-example,reftext=`SortBy Example`] -.sortby Example of descending sort by updated date and ascending sort of record identifier. -[source] ----- -.../collections/mycat/items?...&sortby=-updated,id&... ----- - -[#sortby-extent-example,reftext=`SortBy Extent Example`] -.sortby Example of an ascending sort by extent (i.e. smaller area first) -[source] ----- -.../collections/mycat/items?...&sortby=%2Bextent&... ----- - - diff --git a/core/standard/clause_14_record-filter.adoc b/core/standard/clause_14_record-filter.adoc deleted file mode 100644 index a80aea87..00000000 --- a/core/standard/clause_14_record-filter.adoc +++ /dev/null @@ -1,213 +0,0 @@ -[[clause-cql-filter]] -== Requirements Class "Filtering using the Common Query Language (CQL)" - -[[record-filter-overview]] -=== Overview - -include::requirements/requirements_class_record-filter.adoc[] - -This clause defines the binding to the filter parameters defined in the https://docs.ogc.org/DRAFTS/19-079.html#_requirements_class_filter[OGC API - Features - Part 3: Filtering and the Common Query Language (CQL), Requirements Class "Filter"] clause. - -=== Records - -==== Operation - -As specified in the <> clause, records are accessed using the HTTP GET method via the `/collections/{collectionId}/items` path. The following additional requirements bind the parameters https://docs.ogc.org/DRAFTS/19-079.html#filter-param[filter], https://docs.ogc.org/DRAFTS/19-079.html#filter-lang-param[filter-lang] and https://docs.ogc.org/DRAFTS/19-079.html#filter-filter-crs[filter-crs] to the GET operation on this path. - -include::requirements/record-filter/REQ_filter-param.adoc[] - -include::requirements/record-filter/REQ_filter-lang-param.adoc[] - -include::recommendations/record-filter/REC_text-encoding.adoc[] - -include::recommendations/record-filter/REC_json-encoding.adoc[] - -include::requirements/record-filter/REQ_filter-crs-param.adoc[] - -==== Response - -include::requirements/record-filter/REQ_response.adoc[] - -=== Filtering on links - -==== Overview - -Links can be added to a catalogue record in various ways. This clause -describes the various linking patterns and describes how to use CQL to -filter based on links. - -==== Linking in records - -Links can be added to the following sections in a catalogue record: - -. the <> section. -. the <> section. - -The schema for links added to the <> section is based on https://tools.ietf.org/html/rfc8288[RFC 8288] and is described in https://docs.ogc.org/DRAFTS/19-072.html#link-relation-conventions[OGC API - Common - Part 1: Core] and http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml[OGC API - Features - Part 1: Core]. - -Links added directly to the <> section of a catalogue record can be -added using the following patterns: - -. The link relation is the key for an array of links with a schema similar to that used in the <> section but omitting the `rel` key. -. The link relation is the key for an array of `href` values. -. The link relation is the key for an an `href` value. - -The following examples illustrate each of these linking patterns: - -[#linking-pattern-1,reftext=`Adding links to the **links** section.`] -.Adding links to the **links** section ----- -{ - . - . - ., - "properties": { - . - . - ., - "links": - [ - . - . - ., - { - "rel" : "alternate", - "title" : "This records as XML.", - "href" : "https://example.org/collections/mycat/items/rec01.xml" - }, - { - "rel": "next", - "title": "The next record in this result set.", - "href" : "https://example.org/collections/mycat/items/rec02" - }, - . - . - . - ], - . - . - . - } -} ----- - -[#linking-pattern-2,reftext=`Adding links to the **properties** section.`] -.Adding links to the **properties** section ----- -{ - . - . - ., - "properties": { - . - . - ., - - "related": [ - { - "title" : "A related record", - "href" : "https://example.org/related-record-path/rec15" - } - ], - "license": { - "title" : "CC BY 2.0", - "href" : "https://creativecommons.org/licenses/by/2.0/" - }, - . - . - . - } -} ----- - -[#linking-pattern-3,reftext=`Adding links to the **properties** section.`] -.Adding links to the **properties** section ----- -{ - . - . - ., - "properties": { - . - . - ., - - "related": ["https://example.org/related-record-path/rec15"], - "license": "https://creativecommons.org/licenses/by/2.0/", - . - . - . - } -} ----- - -==== Examples - -===== CQL filters on links - -The following example illustrates how to filter links that may appear in a catalogue record. - -[#filter-pattern-1,reftext=`Filtering links in the **links** section.`] -.Filtering links in the **links** section ----- -links[rel='license'].title LIKE 'CC%' ----- - -[#filter-pattern-2,reftext=`Filtering links in the **properties** section.`] -.Filtering links in the **properties** section ----- -properties.related[*].href LIKE '%/rec15' AND properties.license.title LIKE 'CC%' ----- - -[#filter-pattern-3,reftext=`Filtering links in the **properties** section.`] -.Filtering links in the **properties** section ----- -properties.related LIKE '%/rec15' AND properties.license LIKE 'https://creativecommons.org/licenses/%' ----- - -===== Filtering by keyword from a controlled vocabulary - -The following example illustrates how to use https://docs.ogc.org/DRAFTS/19-079r1.html[OGC API - Feature - Part 3: Filtering] and https://docs.ogc.org/DRAFTS/21-065.html[CQL2] to query by keywords from a specific controlled vocabulary. - -The use of keywords from a controlled voacbulary is encoded in a record using the <> member. Consider a record that have the following `themes` member: - ----- - "themes": [ - { - "concepts": [ - "dobson", - "brewer", - "vassey", - "pion", - "microtops", - "spectral", - "hoelper", - "saoz", - "filter" - ], - "scheme": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode" - }, - { - "concepts": [ - "atmosphericComposition", - "pollution", - "observationPlatform", - "rocketSounding" - ], - "scheme": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode" - } - ], ----- - -Using https://docs.ogc.org/DRAFTS/19-079r1.html[OGC API - Feature - Part 3: Filtering], a server would need to expose two https://docs.ogc.org/DRAFTS/19-079r1.html#queryables[queryables], `scheme` and `concept` for the purpose of filtering using keywords from a specific controlled vocabulary. Using these queryables, the following filter could be expressed: - ----- -https://www.someserver.com/collections/myCatalogue/items?filter-lang=cql2-text&filter=scheme%3D%27https%3A%2F%2Fgeo.woudc.org%2Fcodelists.xml%23WOUDC_InstrumentCode%27%20and%20concept%3D%27spectral%27%2C%0Ahoelper%27 ----- - -An alternative approach that does rely on using https://docs.ogc.org/DRAFTS/19-079r1.html[OGC API - Feature - Part 3: Filtering] and https://docs.ogc.org/DRAFTS/21-065.html[CQL2] would rely on the server defining a set of https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameters_for_filtering_on_feature_properties[query parameters] in the server's https://docs.ogc.org/is/17-069r4/17-069r4.html#_api_definition[API description document], again named `scheme` and `concept`, that would allow the following filter to be expressed: - ----- -https://www.someserver.com/collections/myCatalogue/items?scheme=https%3A%2F%2Fgeo.woudc.org%2Fcodelists.xml%23WOUDC_InstrumentCode&concept=spectral,hoelper ----- - diff --git a/core/standard/clause_15_autodiscovery.adoc b/core/standard/clause_15_autodiscovery.adoc deleted file mode 100644 index 07e42244..00000000 --- a/core/standard/clause_15_autodiscovery.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[[clause-autodiscovery]] -== Requirements Class "Autodiscovery" - -=== Overview - -include::requirements/requirements_class_autodiscovery.adoc[] - -The purpose of autodiscovery is, knowing the URI of a web page, to find the location of that page's associated catalogue. - -=== Autodiscovery links - -include::requirements/autodiscovery/REQ_autodiscovery_link.adoc[] - -For example, a client could retrieve the landing page of an OGC API deployment, find the location of the site's catalogue by locating the `rel=http://www.opengis.net/def/rel/ogc/1.0/catalogue` link and then use that catalogue to search for resources offered by the site. - -include::recommendations/autodiscovery/PER_autodiscovery_links.adoc[] diff --git a/core/standard/clause_16_encodings.adoc b/core/standard/clause_16_encodings.adoc deleted file mode 100644 index 2deb0e86..00000000 --- a/core/standard/clause_16_encodings.adoc +++ /dev/null @@ -1,53 +0,0 @@ -[[clause-encodings]] -== Encodings - -[[requirements-class-geojson-clause]] -=== Requirements Class GeoJSON - -include::requirements/requirements_class_geojson.adoc[] - -GeoJSON is a commonly used format that is simple to understand and well supported by tools and software libraries. Since most Web developers are comfortable with using a JSON-based format supporting GeoJSON is recommended, if record data can be represented in GeoJSON for the intended use. - -The following requirements apply to an OGC API - Records implementation when the following conditions apply: - -. The API advertises conformance to the JSON Conformance Class -. The client negotiates to a record response encoded as GeoJSON. - -include::requirements/geojson/REQ_response.adoc[] - -include::requirements/geojson/REQ_content.adoc[] - -[[schema_geojson_record]] -.link:http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas/recordGeoJSON.yaml[Schema for a catalogue record in JSON(recordGeoJSON.yaml)] -[source,YAML] ----- -include::../openapi/schemas/recordGeoJSON.yaml[] ----- - -[[requirements-class-html-clause]] -=== Requirements Class HTML - -include::requirements/requirements_class_html.adoc[] - -The following requirements apply to an OGC API - Records implementation when the following conditions apply: - -. The API advertises conformance to the HTML Conformance Class -. The client negotiates an HTML format - -Catalogue information that is only accessible in formats primarily intended to -be read by machines, such as JSON or XML, have two issues: - -* The data is not discoverable using the most common mechanism for discovering information, that is the search engines of the Web; - -* The data can not be viewed directly in a browser - additional tools are required to view the data. - -Therefore, sharing data on the Web should include publication in HTML. To be consistent with the Web, it should be done in a way that enables users and search engines to access all data. - -This is discussed in detail in link:https://www.w3.org/TR/sdw-bp/#indexable-by-search-engines[Best Practice 2: Make your spatial data indexable by search engines] <>. This standard therefore <>. - -include::requirements/html/REQ_definition.adoc[] - -include::requirements/html/REQ_content.adoc[] - -include::recommendations/html/REC_schema-org.adoc[] - diff --git a/core/standard/clause_1_scope.adoc b/core/standard/clause_1_scope.adoc index 7d754988..438632ee 100644 --- a/core/standard/clause_1_scope.adoc +++ b/core/standard/clause_1_scope.adoc @@ -1,7 +1,7 @@ == Scope -This document specifies a collection of building blocks that can be assembled in various ways to deploy a collection of related descriptive information (metadata) about resources called a catalogue. The atomic unit of information in a catalogue is the record. +This document specifies a collection of building blocks that can be assembled in various ways to deploy a collection of related descriptive information (metadata) about resources called a catalog. The atomic unit of information in a catalog is the record. This document specifies the information content of a record. A record contains summary descriptive information (metadata) about a resource that a provider wishes to make discoverable. A record represents resource characteristics that can be presented for evaluation and further processing by both humans and software. Examples of resources include: a data collection, a service, a process, a style, a code list, an Earth observation asset, a machine learning model, a code list and so on. -Records are organized into collections. This specification describes how collections of records can be crawled or searched. Crawling a collection of records involves following embedded links from one record in a catalogue to the next. Searching a collection of records involves specifying query predicates that define a subset of records. +Records are organized into collections. This specification describes how collections of records can be crawled or searched. Crawling a collection of records involves following embedded links from one record in a catalog to the next. Searching a collection of records involves specifying query predicates that define a subset of records. diff --git a/core/standard/clause_2_conformance.adoc b/core/standard/clause_2_conformance.adoc index 192cdab0..90cd0e66 100644 --- a/core/standard/clause_2_conformance.adoc +++ b/core/standard/clause_2_conformance.adoc @@ -7,24 +7,33 @@ Conformance with this standard shall be checked using the tests specified in Ann The standardization target of the conformance classes: -* <> -* <> -* <> -* <> +* <> +* <> -is "Web APIs". +is "Document model". The standardization target of the conformance classes: -* <> -* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> -is "Document model". +is "Web APIs". The standardization target of the conformance classes: -* <> -* <> +* <> +* <> is "Document encoding". @@ -39,71 +48,75 @@ The Conformance Classes implemented by an API are advertised through the <> * <> +* <> * <> * <> -* <> -* <> -* <> +* <> +* <> +* <> * <> -The <> conformance class defines the requirements for the core schema of a catalogue record which is a set of properties (<>) that can be used to make any resource discoverable via a catalogue. This core set of properties can be extended as required by specific communities of interest and/or use cases. +The <> conformance class defines the requirements for the core schema of a catalog record which is a set of properties (<>) that can be used to make any resource discoverable via a catalog. This core set of properties can be extended as required by specific communities of interest and/or use cases. The <> conformance class defines requirements for the metadata used to describe a collection of related records. +The <> conformance class defines a minimum set of query parameters that all queryable catalogs should provide. + The <> conformance class defines the requirements for an API for searching collections of records based on logically connected predicates that can include spatial and/or temporal predicates. The Records API is based on http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Feature - Part 1: Core] with <> specific to OGC API - Records. The <> conformance class defines the requirements to support sorting of records in a query response. -The <> conformance class defines the requirements to support record filtering using https://docs.ogc.org/DRAFTS/19-079r1.html[CQL2]. +The <> conformance class defines the requirements to support record filtering using https://docs.ogc.org/DRAFTS/19-079r1.html[CQL2]. -The <> conformance class defines the requirements for a GeoJSON (see RFC 7946) representation of a standard catalogue record. +The <> conformance class defines the requirements for a JSON representation of a catalog object and a GeoJSON (see RFC 7946) representation of a standard catalog record. -The <> conformance class defines the requirements for an HTML representation of a standard catalogue record. +The <> conformance class defines the requirements for an HTML representation of a standard catalog record. -The <> conformance class defines requirements that allow catalogues associated with a web page or web site to be discovered. +The <> conformance class defines requirements that allow catalogs associated with a web page or web site to be discovered. -[[catalogue-requirements-classes]] -=== Catalogue deployments +[[catalog-requirements-classes]] +=== Catalog deployments -Using the above mentioned building blocks, this standard identifies the following catalogue requirements classes: +Using the above mentioned building blocks, this standard identifies the following catalog requirements classes: -* <> -* <> -** <> -** <> +* <> +* <> +** <> +** <> -* <> -** <> -** <> +* <> +** <> +** <> -The <> conformance class defines the core requirements for a catalogue composed of a collection of web-accessible static files. +The <> conformance class defines the core requirements for a catalog composed of a collection of web-accessible static files. -The <>, <>, <> conformance classes define the requirements for a catalogue composed of a collection of records that is searchable via an API. +The <>, <>, <> conformance classes define the requirements for a catalog composed of a collection of records that is searchable via an API. -The <>, <>, <> conformance classes define the requirements for a local resources catalogue which is a catalogue composed of a list of resources offered by an OGC API deployment. The `/collections` endpoint is an example of a local resources catalogue but other endpoints may exist in an OGC API deployment as well. +The <>, <>, <> conformance classes define the requirements for a local resources catalog which is a catalog composed of a list of resources offered by an OGC API deployment. The `/collections` endpoint is an example of a local resources catalog but other endpoints may exist in an OGC API deployment as well. [#required_building_blocks,reftext='{table-caption} {counter:table-num}'] -.Required building blocks by catalogue deployment type +.Required building blocks by catalog deployment type [cols="<25,^25,^25,^25",options="header"] |=== -|Building block 3+|Catalogue requirements class -| |<> |<> |<> +|Building block 3+|Catalog requirements class +| |<> |<> |<> |<> |Mandatory |Mandatory |Mandatory -|<> |_Optional_ |Mandatory |Mandatory -|<> |_Optional_ |Mandatory |Mandatory -|<> |_Optional_ |_Optional_ |_Optional_ -|<> |_Optional_ |_Optional_ |_Optional_ -|<> |_Optional_ |_Optional_ |_Optional_ -|<> |_Optional_ |_Optional_ |_Optional_ +|<> |_Optional_ |Mandatory |N/A +|<> |N/A |_Mandatory_ |_Mandatory_ +|<> |N/A |Mandatory |N/A +|<> |N/A_ |_Optional_ |_Optional_ +|<> |N/A |_Optional_ |_Optional_ +|<> |_Optional_ |_Optional_ |_Optional_ +|<> |_Optional_ |_Optional_ |_Optional_ |=== === Implementations -Implementors of this specification select one or more of the <> they wish to implement and then implement the required building block requirements classes. +Implementors of this specification select one or more of the <> they wish to implement and then implement the required building block requirements classes. === Conformance testing @@ -113,20 +126,33 @@ methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site. -[#conf_class_uris,reftext='{table-caption} {counter:table-num}'] -.Conformance class URIs +[#deployment_conf_class_uris,reftext='{table-caption} {counter:table-num}'] +.Catalog Deployment Conformance class URIs +[cols="30,70",options="header"] +|=== +|Conformance class |URI +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/crawlable-catalog +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog-filtering +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog-sorting +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog-filtering +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalog-sorting +|=== + +[#building_block_conf_class_uris,reftext='{table-caption} {counter:table-num}'] +.Building Block Conformance class URIs [cols="30,70",options="header"] |=== |Conformance class |URI -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/crawlable-catalogue -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalogue -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/local-resources-catalogue |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-collection +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core-query-parameters |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-api |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/sorting -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/cql -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/json -|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/html +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/filtering +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/json +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/html +|<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/oas30 |<> |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/autodiscovery |=== diff --git a/core/standard/clause_4_terms_and_definitions.adoc b/core/standard/clause_4_terms_and_definitions.adoc index 731b5b12..c609ef24 100644 --- a/core/standard/clause_4_terms_and_definitions.adoc +++ b/core/standard/clause_4_terms_and_definitions.adoc @@ -3,7 +3,7 @@ This document uses the terms defined in Sub-clause 5 of https://docs.ogc.org/DRA For the purposes of this document, the following additional terms and definitions apply. -=== Catalogue; Record collection +=== Catalog; Record collection a collection of <> === Conformance Module; Conformance Test Module @@ -29,7 +29,7 @@ set of code (e.g. Java and CTL) that provides runtime tests for the assertions d [[record-def]] === Record -atomic unit of information of a catalogue that is used to provide information about a particular resource +atomic unit of information of a catalog that is used to provide information about a particular resource === Recommendation expression in the content of a document conveying that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others, or that a certain course of action is preferred but not necessarily required, or that (in the negative form) a certain possibility or course of action is deprecated but not prohibited (<>) @@ -44,11 +44,16 @@ aggregate of all requirement modules that must all be satisfied to satisfy a con aggregate of requirements and recommendations of a specification against a single standardization target type (<>) === Resource -an asset of interest that may be described by metadata in a catalogue for the purpose of discovery and access (i.e. binding) +an asset of interest that may be described by metadata in a catalog for the purpose of discovery and access (i.e. binding) + +=== Searchable catalog endpoint +an endpoint in the OGC API resource tree that has been enhanced to support catalog queries + +NOTE: For <>, the searchable catalog endpoint is at `/items`. For <>, an example of a searchable catalog endpoint might be `/collections` or `/processes`. === Standardization Target entity to which some requirements of a standard apply (<>) - NOTE: The standardization target is the entity which may receive a certificate of conformance for a requirements class. +NOTE: The standardization target is the entity which may receive a certificate of conformance for a requirements class. diff --git a/core/standard/clause_6_overview.adoc b/core/standard/clause_6_overview.adoc index c3aa627f..9403dffa 100644 --- a/core/standard/clause_6_overview.adoc +++ b/core/standard/clause_6_overview.adoc @@ -4,46 +4,47 @@ [[records-role]] === Role of OGC API - Records -Historically, catalogues have been used as large repositories of formal metadata like ISO 19119, ISO 19115, FGDC, etc. More recently, catalogues are migrating to a more distributed model where the metadata is intimately associated with the resource that it describes. A current example is STAC which relies on well-defined building blocks that can be integrated in different ways. +Historically, catalogs have been used as large repositories of formal metadata like ISO 19119, ISO 19115, FGDC, etc. More recently, catalogs are migrating to a more distributed model where the metadata is intimately associated with the resource that it describes. A current example is STAC which relies on well-defined building blocks that can be integrated in different ways. -Although OGC API - Records is built upon the legacy of CSW, its role in a modern SDI can be both: a large repository of metadata documents or a distributed catalogue, with the ability to provide a static or dynamic capability. +Although OGC API - Records is built upon the legacy of CSW, its role in a modern SDI can be both: a large repository of metadata documents or a distributed catalog, with the ability to provide a static or dynamic capability. -In the modern scenario, the catalogue records can be distributed and linked together so that they can be crawled or they can be harvested into a service endpoint to make them searchable. In addition, a searchable catalogue can harvest not only a metadata document describing the resource but in some cases the resource itself (e.g. harvesting the collections object from an OGC API). The implications of this are subtle yet important. In the traditional cataloguing approach (e.g. based on CSW) a client could find the record and the record might include binding information to access the resource but that is pretty much it. Using the new approach, a client interacts more intimately with the catalogue and the catalogue becomes integral to the access to the resource. An example is the cloud native ecosystem: HTTP range requests to Cloud Optimized GeoTIFF (COG) data cannot be used properly unless there is a STAC item telling the client in what ranges the bands exists, thus the catalogue becomes an integral component in the process of accessing a resource. +In the modern scenario, the catalog records can be distributed and linked together so that they can be crawled or they can be harvested into a service endpoint to make them searchable. In addition, a searchable catalog can harvest not only a metadata document describing the resource but in some cases the resource itself (e.g. harvesting the collections object from an OGC API). The implications of this are subtle yet important. In the traditional cataloguing approach (e.g. based on CSW) a client could find the record and the record might include binding information to access the resource but that is pretty much it. Using the new approach, a client interacts more intimately with the catalog and the catalog becomes integral to the access to the resource. An example is the cloud native ecosystem: HTTP range requests to Cloud Optimized GeoTIFF (COG) data cannot be used properly unless there is a STAC item telling the client in what ranges the bands exists, thus the catalog becomes an integral component in the process of accessing a resource. [[general-overview]] === General -The atomic unit of information in a catalogue is the _record_. +The atomic unit of information in a catalog is the _record_. -A _catalogue_ is a collection of _records_. The terms **collection of records** and **catalogue** are used interchangeably in this specification. +A _catalog_ is a collection of _records_. The terms **collection of records** and **catalog** are used interchangeably in this specification. A record provides a summary description (metadata) of a resource that the provider of the resource wishes to make discoverable. The record schema defined in this specification includes a small number of properties that can be used to provide a summary description of any resource. It is anticipated, and encouranged, that this list of properties be extended to enhance the information content of a record as required by specific communities of interest and/or use cases. === Building blocks -This standard defines three building blocks that may be used to deploy a catalogue: +This standard defines the following building blocks that may be used to deploy a catalog: . The _core_ schema of a record. -. The definition of a _collection_ resource that groups and describes a set of related records (i.e. a catalogue). -. An API that allows collections of records (i.e. a catalogue) to be searched using logically connected predicates that can include spatial and/or temporal predicates. +. The definition of a _collection_ resource that groups and describes a set of related records (i.e. a catalog). +. The definition of a core set of query parameters for searchable catalogs. +. An API that allows collections of records (i.e. a catalog) to be searched using logically connected predicates that can include spatial and/or temporal predicates. -Using these building blocks a catalogue can be deployed as: +Using these building blocks a catalog can be deployed as: * a set of web-accessible records that can be crawled by a search engine crawler or by using (for example) a web browser -* a searchable catalogue with records accessible through an API +* a searchable catalog with records accessible through an API -A special use case of the _searchable catalogue_ is the _**local resources catalogue**_. The OGC API resource tree has a number of endpoints that provide lists of resources. Examples of such endpoints include the `/collections` and the `/processes` endpoints. One can readily imagine a large OGC API deployment with thousands of collections where the ability to search would enhance the client's interaction with the server. Using the building blocks defined in this specification these endpoints can be extended to support catalogue-like searching using filter expressions that may also include spatial and/or temporal predicates. OGC API endpoints extended in this way behave like a catalogue of local resources. +A special use case of the _searchable catalog_ is the _**local resources catalog**_. The OGC API resource tree has a number of endpoints that provide lists of resources. Examples of such endpoints include the `/collections` and the `/processes` endpoints. One can readily imagine a large OGC API deployment with thousands of collections where the ability to search would enhance the client's interaction with the server. Using the building blocks defined in this specification these endpoints can be extended to support catalog-like searching using filter expressions that may also include spatial and/or temporal predicates. OGC API endpoints extended in this way behave like a catalog of local resources. [[record-schema-overview]] === Record Schema The core set of record properties that may be used to describe a resource include the _recordId_, _time_, _type_, _title_, _description_ and _geometry_. -A complete definition of a record can be found in clause <>. +A complete definition of a record can be found in clause <>. -The choice of which properties to include in the set of core queryables was primarily informed by the following record models: +The choice of which properties to include in the set of core properties was primarily informed by the following record models: -* The http://docs.opengeospatial.org/is/12-168r6/12-168r6.html#17[core catalogue schema] from the https://www.ogc.org/standards/cat[OGC® Catalogue Services 3.0] suite of standards, +* The http://docs.opengeospatial.org/is/12-168r6/12-168r6.html#17[core catalog schema] from the https://www.ogc.org/standards/cat[OGC® Catalogue Services 3.0] suite of standards, * the https://www.w3.org/TR/vocab-dcat/[Data Catalog Vocabulary (DCAT) - Version 2] and the https://www.unece.org/fileadmin/DAM/stats/documents/ece/ces/ge.58/2017/mtg3/2017-UNECE-topic-i-EC-GeoDCAT-ap-paper.pdf[GeoDCAT-AP] specifications. It is expected that the information necessary to populate this core set of properties is readily available for any resource that is being made discoverable by the record. @@ -57,18 +58,18 @@ Although this document does not mandate any particular encoding for a record, th Other encodings are allowed but are not described in this document. -Accessing collections of records deployed as static files is described in the <> clause. +Accessing collections of records deployed as static files is described in the <> clause. Accessing collections of records through the API defined in this document is described in the <> and <> sections. [[sc_record-collection-overview]] -=== Record collection (catalogue) +=== Record collection (catalog) -A record collection or catalogue is an object that groups and describes a set of related <>. The collection resource is the primary access point from which a deployed set of records can be accessed. Having found the collection resource (i.e. the catalogue) a client can, by following the appropriate hypermedia controls contained therein, navigate to the records of the collection. +A record collection or catalog is an object that groups and describes a set of related <>. The collection resource is the primary access point from which a deployed set of records can be accessed. Having found the collection resource (i.e. the catalog) a client can, by following the appropriate hypermedia controls contained therein, navigate to the records of the collection. Depending on the deployment pattern, the collection may provide a link to each individual record of the collection or a link to a search access point for retrieving sub-sets of records. -The core set of properties that may be used to describe a record collection or catalogue include _id_, _type_, _title_, _description_, _extent_ and _links_. A complete definition of a record can be found in clause<>. It should be noted that this list of properties is very similar to the list of core properties defined for a <>. This is intentional since the record collection object can be considered a _record_ that describes a catalogue. +The core set of properties that may be used to describe a record collection or catalog include _id_, _type_, _title_, _description_, _extent_ and _links_. A complete definition of a record can be found in clause<>. It should be noted that this list of properties is very similar to the list of core properties defined for a <>. This is intentional since the record collection object can be considered a _record_ that describes a catalog. It is anticipated that this set of properties will be extended to enrich the information content of the collection metadata to suit specific needs. @@ -77,7 +78,7 @@ It is anticipated that this set of properties will be extended to enrich the inf ==== Overview -The Records API allows a subset of records to be retrieved from a catalogue using a logically connected set of predicates that may include spatial and/or temporal predicates. +The Records API allows a subset of records to be retrieved from a catalog using a logically connected set of predicates that may include spatial and/or temporal predicates. The Records API extends https://github.com/opengeospatial/ogcapi-common[OGC API - Common] and http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Features - Core: Part 1] to: @@ -110,7 +111,7 @@ Collections of records exposed though this OGC API may be accessed through an ht Where: -* {collectionId} = an identifier for a specific record collection (i.e. catalogue identifier) +* {collectionId} = an identifier for a specific record collection (i.e. catalog identifier) * {recordId} = an identifier for a specific record within a collection [[api-behaviour-model-overview]] @@ -118,7 +119,7 @@ Where: The Records API is designed to be compatible but not conformant with the http://docs.opengeospatial.org/is/12-176r7/12-176r7.html[OGC Catalogue Service for the Web (CSW)]. This allows OGC API - Records implementations and CSW implementations to co-exist in a single processing environment. -The https://www.opengeospatial.org/standards/cat[OGC Catalogue Service standard version 3] provides an abstract core model of metadata (data about data) describing a number of different information types (datasets, services, styles, processes, etc.) on which the classic operations GetCapabilities, DescribeRecord, GetRecords, and GetRecordById can be explained naturally. This model consists of a 1..n catalogue collections residing in a CSW backend repository. It holds service metadata describing service qualities (identification, contact, operations, filtering capabilities, etc.). At its heart, a catalogue may provide discovery services to any number of metadata repositories. The core catalogue model is based on an extension of Dublin Core (CSW Record). Application profiles can be developed to target specific metadata information models (such as ISO 19115/19139, etc.). +The https://www.opengeospatial.org/standards/cat[OGC Catalogue Service standard version 3] provides an abstract core model of metadata (data about data) describing a number of different information types (datasets, services, styles, processes, etc.) on which the classic operations GetCapabilities, DescribeRecord, GetRecords, and GetRecordById can be explained naturally. This model consists of a 1..n catalog collections residing in a CSW backend repository. It holds service metadata describing service qualities (identification, contact, operations, filtering capabilities, etc.). At its heart, a catalog may provide discovery services to any number of metadata repositories. The core catalog model is based on an extension of Dublin Core (CSW Record). Application profiles can be developed to target specific metadata information models (such as ISO 19115/19139, etc.). Discussion has shown that the API model also assumes underlying service and object descriptions, so a convergence seems possible. In any case, it will be advantageous to have a similar "mental model" of the server store organization on hand to explain the various functionalities introduced below. @@ -134,10 +135,12 @@ The first or core level of search capability is based on <>, supports complex filter expressions using a rich set of logically connected query predicates. diff --git a/core/standard/clause_7_building_blocks.adoc b/core/standard/clause_7_building_blocks.adoc new file mode 100644 index 00000000..68945758 --- /dev/null +++ b/core/standard/clause_7_building_blocks.adoc @@ -0,0 +1,1046 @@ +[[building-blocks]] +== Building Blocks + +=== Overview + +This clause specifies the requirements classes that define building blocks that can be used to define various <>. + +[[clause-record-core]] +=== Requirements Class "Record Core" (Building Block) + +[[record-core-overview]] +==== Overview + +include::requirements/requirements_class_record-core.adoc[] + +The `Record` Requirements Class defines the requirements for a catalog record. + +[[record-model]] +==== Record + +The atomic unit of information in a catalog is a **_record_** which is defined in this clause. + +It is expected that the information necessary to populate the fields/properties of a catalog record is readily available for any resource that is being registered in the catalog. + +It is anticipated that the schema of a record will be extended to describe specific resource types (e.g. datasets, services, etc.) and also extended by information communities wishing to enrich the information content of the record to suit their needs. + +Although this document does not mandate any particular encoding for a record, this document does define conformance classes for two encodings: + +* a <> record encoding, +* and an <> encoding. + +Other encoding are allowed but are not described in this document. + +===== Overview + +[[core-properties]] +===== Core properties + +<> and <> define the set of properties, called the _core properties_, that may be included in a record. + +[#core-properties-record-table,reftext='{table-caption} {counter:table-num}'] +.Table of Core Properties related to the catalog record +[cols="20,5,55,20",options="header"] +|=== +|Property |Requirement |Description |GeoJSON key +|recordId |**required** |A unique record identifier assigned by the server. |id +|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 +|conformsTo |optional |The extensions/conformance classes used in this record. |conformsTo +|=== + +[#core-properties-resource-table,reftext='{table-caption} {counter:table-num}'] +.Table of Core Properties related to the resource +[cols="20,5,55,20",options="header"] +|=== +|Property |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 if there is no 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.keywords +|language |optional |The language used for textual values (i.e. titles, descriptions, etc) of this record. |properties.language +|languages |optional |The list of other languages in which this record is available. |properties.languages +|resourceLanguages |optional |The list of languages in which the resource described by this record can be retrieved. |properties.resourceLanguages +|externalIds |optional |One or more identifiers for the resource assigned by an external entity. |properties.externalIds +|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 +|contacts |optional |A list of contacts qualified by their role(s) in association to the record or resource. |properties.contacts +|license |optional |The legal provisions under which the resource is made available. |properties.license +|rights |optional |A statement that concerns all rights not addressed by the license such as a copyright statement. |properties.rights +|links |**required** |A list of links related to this record. +|=== + +include::requirements/record-core/REQ_mandatory-properties-record.adoc[] + +include::recommendations/record-core/PER_common-mark.adoc[] + +include::recommendations/record-core/PER_additional-properties-record.adoc[] + + +[[sc_record_extensions]] +===== Record extensions + +In tables <> and <> this standard defines a set of core properties for describing discoverable resources. It is anticipated that this set of core properties will be extended to suite specific use cases or requirements. For example, a catalog record may be extended to include additional properties from the https://semiceu.github.io/GeoDCAT-AP/releases/[GeoDCAT] vocabulary. The fact that a catalog record has been extended in this way can be advertised using the `conformsTo` member. The `conformsTo` member is a list of identifiers that indicate each extension used in a record. This specification does not define the specific identifiers that are used to identify specific extensions; it simply provides a place where these identifiers can be listed. + +include::recommendations/record-core/REC_record-extensions.adoc[] + +In the case where all the records of a catalog use the same set of extensions, and to prevent unnecessary duplication, there is also a `conformsTo` member at the https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/catalog.yaml[collection or catalog level] that may be used to declare which extensions are used in all records of the catalog. Extensions listed at the catalog and record levels are cumulative. + +[[sc_temporal_information]] +===== Temporal information + +====== Overview + +Many records have a geometry property that provides information about the primary spatial characteristics of the resource described by the record. Records often also have temporal information. In most cases time is either an instant (e.g., an event) or an interval (e.g., an activity or a temporal validity). In OGC API Records the temporal property is reflected in the <> parameter which supports temporal filtering. + +This standard added support for the most common temporal case: Associating a resource with a single temporal instant or interval in the Gregorian calendar. More complex cases and other temporal coordinate reference systems are out-of-scope for this Standard and might be specified in future extensions. + +Records can have multiple properties that describe the temporal characteristics of the resource(s) that the record describes. + +* In many records all temporal properties are instants (represented by a date or a timestamp) and intervals are described using two temporal instants, one for the start and one for the end. + +* Multiple temporal properties are sometimes used to describe different temporal characteristics of the resource(s) the record describes. For example, the time instant or interval when the information in the record is valid (sometimes called "valid time") and the time when the record was recorded in the catalog (sometimes called "transaction time"). Another example is the https://www.ogc.org/standards/om[Observations & Measurements standard], where an observation has multiple temporal properties including "phenomenon time", "result time" and "valid time". + +This standard does not place any containts on the number of additional temporal properties that may be added to a record to characterize temporal aspects of the resource being described by a record. This can make it difficult for a naive client to recognize and utilize temporal information stored in the record. For this reason, this standard includes the `time` property in a record. This `time` member is set by the publisher of the record and describes characteristic temporal information (an instant or an internval) associated with the resource described by a record. This `time` member can thus be used by a naive clients without the need to inspect or undestand the schema of an extended record. The value of the `time` member is either `null` (no temporal information) or an object encoding a time instant or interval. + +.Properties of the "time" object +[cols="20,10a,70a",options="header"] +|=== +|Property |Type |Description +|date |string |An instant with a granularity of a date. See below for more details about instants. +|timestamp |string |An instant with the granularity of a timestamp. See below for more details about instants. +|interval |[ string ] |An interval, described by an array of the two instants (start and end). See below for more details about intervals. +|=== + +Including both an instant and an interval is valid, if both values intersect. In this case, clients should use the interval property and may use the date or timestamp property to determine the temporal characteristics of the resource being described by the record. + +The "time" object may be extended with additional members. Clients processing a "time" object must be prepared to parse additional members. Clients should ignore members that they do not understand. For example, in cases where the "time" member neither includes an "instant" or "interval", a client may process the record as a record without temporal information. + +NOTE: The data publisher decides how additional temporal properties are encoded in a record. The schema for the `time` member does not imply a recommendation that temporal feature properties reuse the same schema. For example, it is expected that a date-valued feature attribute will in most cases be represented as string with an RFC 3339 date value. + +====== Instants + +An instant is a value that conforms to https://datatracker.ietf.org/doc/html/rfc3339[RFC 3339 (Date and Time on the Internet: Timestamps)] and is consistent with one of the following production rules of the ISO 8601 profile specified in the RFC: + +* `full-date` (e.g., `"1969-07-20"`) +* `date-time` (e.g., `"1969-07-20T20:17:40Z"`) + +Conceptually, an instant is a "temporal entity with zero extent or duration" [<>]. In practice, the temporal position of an instant is described using data types where each value has some duration or granularity. The value should be described with a granularity that is sufficient for the intended use of the data. + +In the case of a timestamp the granularity is a second or smaller. All timestamps have to be in the time zone UTC ("Z"). + +In the case of a date the granularity is a day and dates as instants will be used when a granularity of a day independent of its timezone is sufficient for the intended use of the data. If that is not the case and, for example, the timezone is important for the intended use, the temporal information should be provided as an interval with start and end timestamps. + +NOTE: This Standard only provides guidance how to represent record data in JSON. It is out-of-scope for this Standard to provide guidance how to cast record data to other data types. The https://docs.ogc.org/DRAFTS/21-065.html[Common Query Language (CQL2)] standard uses the same model of instants and intervals as used here and includes additional guidance on how to compare values. + +[#ex-time-1,reftext='{listing-caption} {counter:listing-num}'] +.A date +==== +[source,json,linenumbers] +---- +"time" : { "date": "1969-07-20" } +---- +==== + +[#ex-time-2,reftext='{listing-caption} {counter:listing-num}'] +.A timestamp +==== +[source,json,linenumbers] +---- +"time" : { "timestamp": "1969-07-20T20:17:40Z" } +---- +==== + +Dates and timestamps are the initial range of instant values. The range may be extended in the future to support additional use cases. Clients processing values of `time` must be prepared to receive other values. Clients may ignore values that they do not understand + +include::requirements/record-core/REQ_time-instant.adoc[] + +====== Intervals + +An interval is described by start and end instants. Both start and end instants are included in the interval, i.e., the interval is closed. + +The end of unbounded intervals are represented by a double-dot string ("..") for the start/end. This follows the convention of ISO 8601-2 for an open start or end. + +[#ex-time-3,reftext='{listing-caption} {counter:listing-num}'] +.An interval with dates +==== +[source,json,linenumbers] +---- +"time" : { "interval": [ "1969-07-16", "1969-07-24" ] } +---- +==== + +[#ex-time-4,reftext='{listing-caption} {counter:listing-num}'] +.An interval with timestamps +==== +[source,json,linenumbers] +---- +"time" : { "interval": [ "1969-07-16T05:32:00Z", "1969-07-24T16:50:35Z" ] } +---- +==== + +[#ex-time-5,reftext='{listing-caption} {counter:listing-num}'] +.An half-bounded interval +==== +[source,json,linenumbers] +---- +"time" : { "interval": [ "2014-04-24T10:50:18Z", ".." ] } +---- +==== + +The options described above are the initial range of interval values - the granularity is either days or (sub-)seconds and interval ends may be unbounded. The value range may be extended in the future to support additional use cases. Clients processing values of `time` must be prepared to receive other values. Clients may ignore values that they do not understand. + +include::requirements/record-core/REQ_time-interval.adoc[] + +====== Instants and intervals + +include::requirements/record-core/REQ_time-instant-interval.adoc[] + +====== Time zones + +include::requirements/record-core/REQ_time-zone.adoc[] + +[[sc_keywords_and_themes]] +===== Keywords and Themes + +A record allows for one `properties.keywords` and zero to many `properties.themes` properties. Keywords are free form terms or tags associated with the resource(s) that the record describes. Themes are concepts associated with the resource(s) that a record describes taken from one or more formal knowledge organization systems or schemes. The list of knowledge organization systems or schemes used in a <> or <> catalog can be determined by inspecting the server's OpenAPI document or, if the server implements CQL2, by exposing a queryable (e.g. named `scheme`) and enumerating the list of schemes used in the queryable's schema definition. + +include::recommendations/record-core/REC_record-keywords-themes.adoc[] + +The following provides an example of using keywords for free form terms (e.g. tags) as well as themes to articulate terms from formal vocabularies or classification systems. + +[#keywords-themes-example,reftext=`Keywords and themes Example`] +.Keywords and themes Example +[source,json] +---- +include::../examples/json/keywords-themes.json[] +---- + +[[sc_contacts]] +===== Contacts + +include::requirements/record-core/REQ_contact.adoc[] +include::recommendations/record-core/REC_contact.adoc[] + +[[sc_type]] +===== Type + +A record has one `properties.type` property. The value of this property should be a code, convenient for filtering records. + +include::recommendations/record-core/REC_record-type.adoc[] + +include::recommendations/record-core/PER_record-type.adoc[] + +In addition, links to external resources describing the record type vocabulary used to populate the `properties.type` member are recommended, as described in <>. + +[[sc_license]] +===== License + +A record may have one `properties.license` property. If present, the value of this property should be a code, convenient for filtering records. + +include::requirements/record-core/REQ_record-license.adoc[] + +[[sc_associations_and_links]] +===== Associations and Links + +A record must contain a `links` section. This `links` section many contain navigation links and/or association links. + +Navigation links are meant to encode relationships between catalog entities (i.e. <> and <>). Navigation links in the `links` section can include links to the collection (`rel="collection`) of which a record is a member, alternative representations (`rel="alternate"`) of the record, and -- in the context of an API -- navigation links to previous (`rel="prev"`) or next (`rel="next"`) records in a chain of records. Links in the `links` section may also be used to organize records in a hierarchy (`rel="root"`, `rel="parent"`, `rel="child`). + +include::requirements/record-core/REQ_record-links.adoc[] + +include::recommendations/record-core/REQ_links.adoc[] + +Links in the `links` section may also encode canoncial URIs for record properties such as `type` and `license`. + +include::recommendations/record-core/REC_record-links_type.adoc[] + +include::recommendations/record-core/REC_record-links_iana.adoc[] + +Association links point to the resource(s) being described by a record. Such links allow binding to a resource once it has been discovered by searching a catalog. Depending on how the target resource of a record is represented and how it may be accessed, there may be one or more association links. For example, if the target resource is an Earth observation imagery file, links may point to the indivdually accessible bands of the image file. + +Association links are also meant to point to other records related to the containing record. For example, consider a record that describes a set of vector features and another record that describes a rendering style for that feature set. These two records may, in their respective `links` sections point to each other to encode this "styles"/"styled-by" relationship. + +Finally, association links are meant to point to other resources external to the catalog that are related to the containing record or the resource(s) that the record describes. + +include::recommendations/record-core/REC_record-associations_relate.adoc[] + +In some instances additional context may be desirable or required in order to access (or bind to) the resource(s) being described by a record. This is the case when, for example, access to the resource is through a service interface that requires mandatory parameters to be provided. The OGC Web Map Service (WMS) is an example of such a service. It may also be the case that efficient access to the resource would be facilitated by providing additional context. Accessing data from a large data repository such as a data cube would be more efficient if the context of the query used to discover the resource (e.g. bbox, datetime) were passed down to the link used to access the data. + +include::recommendations/record-core/REC_record-associations_templated.adoc[] + +NOTE: This specification does not define any specific link relations that should be used for links in the `links` section. Such relationships are typically domain specific and so it is left to communities of interest to standardize the links that relations should use. + +The following provides an example of using association links for related resources of a record, as both traditional link relations as well as API resources via URI templates. + +[#associations-simple-and-uri-template-example,reftext=`Associations simple and URI Template Example`] +.Associations simple and URI Template Example +[source,json] +---- +include::../examples/json/associations-simple-and-uri-template.json[] +---- + +[[example_11]] +.Links in a record payload +===== +The links in a record could be (in this example represented as link headers): + +[source] +---- +Link: ; rel="self"; type="application/geo+json" +Link: ; rel="alternate"; type="text/html" +Link: ; rel="collection"; type="application/json" +Link: ; rel="collection"; type="text/html" +---- +===== + +[[sc_templated_links_with_variables]] +===== Templated links with variables + +OGC API - Records uses links to express associations between resources including links that bind to the resource(s) being described by a record. In some situations, a static link does not adequately express all the information necessary to retrieve the referenced resource OR does not allow for the resource to be retrieved in an efficient manner. + +Consider the case where a record describing a coverage resource is discovered by searching the catalog using a spatial constraint (e.g. a bbox). Further consider that the found record contains a link to retrieve the coverage. Using a static link for the binding link would only allow retrieval of the entire coverage. Using a templated link, however, would allow the context of the catalog query (i.e. the bbox) to be passed to down to the binding link. The templated link with all substitution values resolved would thus retrieve the subset of the coverage that corresponds to the spatial contraint used to discover the record in the first place which presumably represents the area of interest. + +Templated links may also be used to bind to resources that may require additional information in order to access the resources. For example, simply knowing the URL of a legacy OGC service such as WMS or WFS is not sufficient to access resources offered by those services. Additional information in the form of request parameters and values are required in order to have a complete link to a resources. A templated link with variables can provide this additional context. + +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://schemas.opengis.net/ogcapi/common/part1/1.0/openapi/schemas/link.yaml[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[] + +[#templated-link-with-variables,reftext=`Associations simple and URI Template Example`] +.Templated link with variables example +[source,json] +---- +include::../examples/json/templated-link.json[] +---- + +===== Resource timestamps + +A <> contains information, encoded in the links section, for accessing one or more resources described by the record. 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-records/blob/master/core/openapi/schemas/common/link.yaml[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_record_language_handling]] +===== Language handling + +====== Overview + +A catalog record can include language information about: + +* the resource that the record describes, +* the language used for text values in the current record representation, +* and alternate languages in which the current record can be represented. + +====== Language of the record + +include::recommendations/record-core/REC_record-lang.adoc[] + +The https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/common/link.yaml[link object] based on https://docs.ogc.org/is/17-069r4/17-069r4.html#rfc8228[RFC 8288 (Web Linking)] includes a `hreflang` attribute that can be used to state the language of a referenced resource. This can be used to include links to the same record in different languges. + +[[minting-language-specific-uris]] +A server that wants to use language-specific links will have to support a mechanism to mint language-specific URIs in order to express links to the same record in other languages or to express links to the resource described by record in multiple languages. This document does not mandate any particular approach how such a capability is supported by a server. + +[NOTE] +====================================================================== +Two common approaches are: + +* an additional path element for each language-specific encoding of a record or resource (this can be expressed, for example, using a language-specific path element like `.../en-ca/...`); + +* an additional query parameter (for example, https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/parameter/language.yaml["language"] or "l") that overrides the Accept-Language header of the HTTP request. +====================================================================== + +[NOTE] +====================================================================== +There is no provision in the record schema to allow a response containing text fields simultaneously presented in multiple languages (e.g. multiple titles in different languages). To obtain a record in multiple languages would require multiple requests to the server each negotiating to a desired language. +====================================================================== + +====== Language of the resource + +include::recommendations/record-core/REC_resource-langs.adoc[] + +[[clause-record-collection]] +=== Requirements Class "Record Collection" (Building Block) + +[[record-collection-overview]] +==== Overview + +include::requirements/requirements_class_record-collection.adoc[] + +This requirements class defines the requirements for a record collection. + +A _collection_ is an object that provides information about and access to a set of related <>. Such a collection of records is also referred to as a _catalog_. + +The schema for the collection resource is an extension of the collection schema defined in http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features]. + +While http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features] defines a specific location for the collection resource (path: `/collections/{collectionId}`), OGC API - Records only fixes the location of the collection in the <> conformance class. Otherwise the collection resource can live anywhere the provider wishes to place it including as a static file in web space (e.g. a web-accessible directory or an S3 bucket). + +Although this document does not mandate any particular encoding for a record collection, this document does define conformance classes for two encodings: + +* a <> record encoding, +* and an <> encoding. + +Other encoding are allowed but are not described in this document. + +[[record-collection-schema]] +==== Record collection schema + +<> defines the set of properties that may be used to describe a collection of records. + +[#collection-properties-table,reftext='{table-caption} {counter:table-num}'] +.Table of collection properties +[cols="30,5,65",options="header"] +|=== +|Property |Requirement |Description +|_**id**_ |**required** |A unique identifier for this collection. +|_**title**_ |**required** |A human-readable name given to this collection. +|_**description**_ |optional |A free-text description of this collection. +|_**links**_ |**required** |A list of links related to this collection. +|_**extent**_ |optional |The spatio-temporal coverage of this collection. +|_**itemType**_ |**required** |Fixed to the value "record". +|_**crs**_ |optional |A list of coordinate reference systems used for spatial-temporal values. +|type |**required** |The nature or genre of the resource. Fixed to "Catalog". +|keywords |optional |A list of free-form keywords or tags associated with this collection. +|language |optional |The language used for textual values (i.e. titles, descriptions, etc) of this collection object. +|languages |optional |The list of other languages in which this collection object is available. +|recordLanguages |optional |The list of languages in which records from the collection can be represented. +|created |optional |The date this collection was created. +|updated |optional |The more recent date on which this collection was changed. +|contacts |optional |A list of contacts qualified by their role(s). +|themes |optional |A knowledge organization system used to classify this collection. +|license |optional |The legal provisions under which this collection is made available. +|rights |optional |A statement that concerns all rights not addressed by the license such as a copyright statement. +|=== + +NOTE: The properties _id_, _title_, _description_, _links_, _extent_, _itemsType_ and _crs_ were inherited from http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features]. + +include::requirements/record-collection/REQ_mandatory-properties.adoc[] + +include::recommendations/record-collection/PER_common-mark.adoc[] + +include::recommendations/record-collection/PER_additional-properties.adoc[] + +==== Keywords and Themes + +See <> for a record. + +==== Links + +include::requirements/record-collection/REQ_links.adoc[] + +include::recommendations/record-collection/PER_links.adoc[] + +==== Templated links with variables + +See <> for a record. + +==== Language handling + +Language handling for the collection object is analogous to <> for a record. + +include::recommendations/record-collection/REC_collection-lang.adoc[] + +include::recommendations/record-collection/REC_record-langs.adoc[] + +==== Encodings + +This specification defines requirements for JSON and HTML encoding of a catalog. See <>. + +[[clause-record-core-query-parameters]] +=== Requirements Class "Record Core Query Parameters" (Building Block) + +[[record-core-query-parameters-overview]] +==== Overview + +include::requirements/requirements_class_record-core-query-parameters.adoc[] + +This conformance class defines a minimum core set of query parameters that shoule be implemented at an searchable catalog endpoint. The <> lists this minimum set of query parameters. + +The parameters `bbox`, `datetime`, `limit` and `ids` are inherited from https://docs.opengeospatial.org/is/17-069r4/17-069r4.html[OGC API Features - Part 1: Core]. The remaining parameters are defined in this standard. + +[#core-query-parameters-table,reftext='{table-caption} {counter:table-num}'] +.Table of Core Query Parameters +[cols="15,85",options="header"] +|=== +|Parameter name |Description +|https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_parameter_bbox[bbox] |A bounding box. If the spatial extent of the record intersects the specified bounding box then the record shall be presented in the response document. +|https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_parameter_datetime[datetime] |A time instance or time period. If the temporal extent of the record intersects the specified data/time value then the record shall be presented in the response document. +|https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_parameter_limit[limit] |The number of records to be presented in a response document. +|<> |A comma-separated list of search terms. If any server-chosen text field in the record contains 1 or more of the terms listed then this records shall appear in the response set. +|<> |An equality predicate consistent of a comma-separated list of resource types. Only records of the listed type shall appear in the resource set. +|https://fix.me[ids] |An equality predicate consisting of a comma-separated list of record identifiers. Only records with the specified identifiers shall appear in the response set. +|<> |An equality predicate consisting of a comma-separated list of external resource identifiers. Only records with the specified external identifiers shall appear in the response set. +|<> |Equality predicates with any <> not already listed in this table. +|=== + +[[core-query-parameters]] +==== Query parameters + +[[core-query-parameters-bbox]] +===== Parameter bbox +include::requirements/record-core-query-parameters/REQ_query-param-bbox.adoc[] + +[[core-query-parameters-datetime]] +===== Parameter datetime +include::requirements/record-core-query-parameters/REQ_query-param-datetime.adoc[] + +[[core-query-parameters-limit]] +===== Parameter limit +include::requirements/record-core-query-parameters/REQ_query-param-limit.adoc[] + +[[core-query-parameters-q]] +===== Parameter q + +include::requirements/record-core-query-parameters/REQ_query-param-q-definition.adoc[] + +include::recommendations/record-core-query-parameters/REC_param-q.adoc[] + +include::requirements/record-core-query-parameters/REQ_query-param-q-response.adoc[] + +[[core-query-parameters-type]] +===== Parameter type + +include::requirements/record-core-query-parameters/REQ_query-param-type-definition.adoc[] + +include::recommendations/record-core-query-parameters/REC_query-param-type-definition.adoc[] + +include::requirements/record-core-query-parameters/REQ_query-param-type-response.adoc[] + +[[core-query-parameters-ids]] +===== Parameter ids + +include::requirements/record-core-query-parameters/REQ_query-param-ids-definition.adoc[] + +include::requirements/record-core-query-parameters/REQ_query-param-ids-response.adoc[] + +[[core-query-parameters-externalid]] +===== Parameter externalId + +include::requirements/record-core-query-parameters/REQ_query-param-externalid-definition.adoc[] + +include::requirements/record-core-query-parameters/REQ_query-param-externalid-response.adoc[] + +[[additional-query-parameters]] +===== Additional query parameters + +This standard defines the following URL query parameters based on the set of +<> to support record selection +based on the resource type and/or an external identifier associated with the +resource. + +* <> +* <> + +include::recommendations/record-core-query-parameters/REC_additional-query-parameters.adoc[] + +[[clause-records-api]] +=== Requirements Class "Records API" (Building Block) + +[[records-api-overview]] +==== Overview + +include::requirements/requirements_class_records-api.adoc[] + +The core API for a catalog is defined by the http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] standard. + +include::requirements/records-api/REQ_resource-name-mapping.adoc[] + +==== Declarations of conformance class + +include::requirements/records-api/REQ_conformance-classes.adoc[] + +include::recommendations/records-api/PER_conformance-classes.adoc[] + +==== Encodings + +While OGC API - Records does not specify any mandatory encoding, support for the following encodings is recommended. + +include::recommendations/records-api/REC_html.adoc[] + +include::recommendations/records-api/REC_json.adoc[] + +The requirements specified in the <> sub-clause imply that the encoding of a server response is determined using content negotiation as specified by the HTTP RFC. + +The <> sub-clause includes guidance on media types for encodings that are specified in this document. + +Note that any server that supports multiple encodings will have to support a mechanism to mint encoding-specific URIs for resources in order to express links, for example, to alternate representations of the same resource. This document does not mandate any particular approach how this is supported by the server. + +As clients simply need to dereference the URI of the link, the implementation details and the mechanism how the encoding is included in the URI of the link are not important. Developers interested in the approach of a particular implementation, for example, to manipulate ("hack") URIs in the browser address bar, can study the API definition. + +[NOTE] +====================================================================== +Two common approaches are: + +* an additional path for each encoding of each resource (this can be expressed, +for example, using format specific suffixes like ".html"); + +* an additional query parameter (for example, "accept" or "f") that overrides +the Accept header of the HTTP request. +====================================================================== + +[[record-collection]] +==== Record collection response + +include::requirements/records-api/REQ_record-collection-response.adoc[] + +[[record-collections]] +==== Record collections response + +include::requirements/records-api/REQ_record-collections-response.adoc[] + +[[records-access]] +==== Records access + +===== Operation + +include::requirements/records-api/REQ_records-op.adoc[] + +===== Combinations of Filtering Parameters + +Any combination of query parameters from the <> and any <> may be specified for filtering. Note that the requirements on these parameters imply that only records matching all the predicates are in the result set; i.e., the logical operator between the predicates is **AND** (exclusive). + +[[query-response]] +===== Response + +<> lists specific requirements based on the negotiated representation of the response. + +[#response-encodings,reftext='{table-caption} {counter:table-num}'] +.Negotiated representation of response +[width=40%,cols="30%,70%",options="header"] +|=== +|Representation |Requirements +|JSON/GeoJSON |<> +|HTML |<> +|=== + +===== Examples + +The following is an example of a response to an OGC API - Records query operation (path: `/collections/{collectionId}/items`). This example shows a JSON response and the response container is a GeoJSON feature collection. Specific records are not presented in this example in order to illustrate the structure of the response container in GeoJSON. + +[#records-example,reftext=`Records Example`] +.Records Example in GeoJSON +[source,json] +---- +include::../examples/json/record-collection.json[] +---- + +The following is an example of a single catalog record encoded in GeoJSON. +Such a record might appear in the `features` array of a +<> or it may be the response when a specific, +single record is accessed (path: `/collections/{collectionId}/items/{recordId}`). + +[#record-example,reftext=`Record Example`] +.Record Example in GeoJSON +[source,json] +---- +include::../examples/json/record.json[] +---- + +[[record-access]] +==== Record access + +===== Operation + +include::requirements/records-api/REQ_record-op.adoc[] + +===== Response + +include::requirements/records-api/REQ_record-response.adoc[] + +[[clause-sorting]] +=== Requirements Class "Sorting" (Building Block) + +[[sorting-overview]] +==== Overview + +include::requirements/requirements_class_sorting.adoc[] + +The `Sorting` Requirements Class defines the requirements for specifying how records in a response should be ordered for presentation. + +[[sorting-parameter-sortby]] +==== Parameter sortby + +include::requirements/sorting/REQ_sortby-definition.adoc[] + +NOTE: The core definition of the `sortby` parameter only defines a single directive that controls the sort order of the corresponding property. It is anticipated extensions would add additional search facets such as directives for: +handling missing values; specifying a high value indicating that the corresponding property be sorted as if it were the highest possible value; specifying a low value indicating that the corresponding property be sorted as if it were the lowest possible value; allowing records to be omitted from the result set based on their sort order; specify a fixed value and a fixed value that sorts the corresponding property as if it were the specified fixed value. + +include::requirements/sorting/REQ_sortby-response.adoc[] + +include::requirements/sorting/REQ_get-sortables-op.adoc[] + +include::requirements/sorting/REQ_get-sortables-success.adoc[] + +The response is returned as a JSON Schema document that describes a single JSON object where each property is a sortable. Note that the sortables schema does not specify a schema of any object that can be retrieved from the API. JSON Schema is used for the sortables to have a consistent approach for describing schema information and JSON Schema is/will be used in other parts of OGC API - Features to describe schemas for GeoJSON feature content including in OpenAPI documents. + +NOTE: The OGC Features API Standards Working Group has a schema harmonization task that could lead to a future OGC API standard that will deprecate the approach for the sortables resource specified in this document. + +To support clients, providing additional detail about the meaning of the sortables is recommended: + +include::recommendations/sorting/REC_sortables-schema.adoc[] + +In an OpenAPI 3.0 document, the Sortables resource has the following schema: + +[[schema_sortables]] +.link:http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/responses/Sortables.yaml[Schema for the list of sortable properties (Sortables.yaml)] +[source,YAML] +---- +include::../openapi/responses/Sortables.yaml[] +---- + +==== Declaring default sort order + +This specification does not mandate a specific default sort order for records +fetched from a searchable catalog. However, servers can declare a default +sort order. + +include::requirements/sorting/REQ_defaultSortOrder-definition.adoc[] + +==== Examples + +[#defaultSortOrder-example,reftext=`Default Sort Order Example`] +.Default Sort Order Example +[source,json] +---- +include::../examples/json/defaultSortOrder.json[] +---- + +This examples indicates that by default, response records are sorted by the `updated` sortable and the `area` sortable with the most recent record with the largest area being presented first. + +[#sortables-example,reftext=`Sortables Example`] +.Sortables Example +[source,json] +---- +include::../examples/json/sortables.json[] +---- + +[#sortby-example,reftext=`SortBy Example`] +.sortby Example of descending sort by updated date and ascending sort of record identifier. +[source] +---- +.../collections/mycat/items?...&sortby=-updated,id&... +---- + +[#sortby-extent-example,reftext=`SortBy Extent Example`] +.sortby Example of an ascending sort by extent (i.e. smaller area first) +[source] +---- +.../collections/mycat/items?...&sortby=%2Bextent&... +---- + +[[clause-filtering]] +=== Requirements Class "Filtering" (Building Block) + +[[record-filter-overview]] +==== Overview + +include::requirements/requirements_class_record-filter.adoc[] + +This clause defines the binding to the filter parameters defined in the https://docs.ogc.org/DRAFTS/19-079.html#_requirements_class_filter[OGC API - Features - Part 3: Filtering and the Common Query Language (CQL), Requirements Class "Filter"] clause. + +==== Records + +===== Operation + +As specified in the <> clause, records are accessed using the HTTP GET method via the `/collections/{collectionId}/items` path. The following additional requirements bind the parameters https://docs.ogc.org/DRAFTS/19-079.html#filter-param[filter], https://docs.ogc.org/DRAFTS/19-079.html#filter-lang-param[filter-lang] and https://docs.ogc.org/DRAFTS/19-079.html#filter-filter-crs[filter-crs] to the GET operation on this path. + +include::requirements/record-filter/REQ_filter-param.adoc[] + +include::requirements/record-filter/REQ_filter-lang-param.adoc[] + +include::recommendations/record-filter/REC_text-encoding.adoc[] + +include::recommendations/record-filter/REC_json-encoding.adoc[] + +include::requirements/record-filter/REQ_filter-crs-param.adoc[] + +===== Response + +include::requirements/record-filter/REQ_response.adoc[] + +==== Filtering on links + +===== Overview + +Links can be added to a catalog record in various ways. This clause +describes the various linking patterns and describes how to use CQL to +filter based on links. + +===== Linking in records + +Links can be added to the following sections in a catalog record: + +. the <> section. +. the <> section. + +The schema for links added to the <> section is based on https://tools.ietf.org/html/rfc8288[RFC 8288] and is described in https://docs.ogc.org/DRAFTS/19-072.html#link-relation-conventions[OGC API - Common - Part 1: Core] and http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml[OGC API - Features - Part 1: Core]. + +Links added directly to the <> section of a catalog record can be +added using the following patterns: + +. The link relation is the key for an array of links with a schema similar to that used in the <> section but omitting the `rel` key. +. The link relation is the key for an array of `href` values. +. The link relation is the key for an an `href` value. + +The following examples illustrate each of these linking patterns: + +[#linking-pattern-1,reftext=`Adding links to the **links** section.`] +.Adding links to the **links** section +---- +{ + . + . + ., + "properties": { + . + . + ., + "links": + [ + . + . + ., + { + "rel" : "alternate", + "title" : "This records as XML.", + "href" : "https://example.org/collections/mycat/items/rec01.xml" + }, + { + "rel": "next", + "title": "The next record in this result set.", + "href" : "https://example.org/collections/mycat/items/rec02" + }, + . + . + . + ], + . + . + . + } +} +---- + +[#linking-pattern-2,reftext=`Adding links to the **properties** section.`] +.Adding links to the **properties** section +---- +{ + . + . + ., + "properties": { + . + . + ., + + "related": [ + { + "title" : "A related record", + "href" : "https://example.org/related-record-path/rec15" + } + ], + "license": { + "title" : "CC BY 2.0", + "href" : "https://creativecommons.org/licenses/by/2.0/" + }, + . + . + . + } +} +---- + +[#linking-pattern-3,reftext=`Adding links to the **properties** section.`] +.Adding links to the **properties** section +---- +{ + . + . + ., + "properties": { + . + . + ., + + "related": ["https://example.org/related-record-path/rec15"], + "license": "https://creativecommons.org/licenses/by/2.0/", + . + . + . + } +} +---- + +===== Examples + +====== CQL filters on links + +The following example illustrates how to filter links that may appear in a catalog record. + +[#filter-pattern-1,reftext=`Filtering links in the **links** section.`] +.Filtering links in the **links** section +---- +links[rel='license'].title LIKE 'CC%' +---- + +[#filter-pattern-2,reftext=`Filtering links in the **properties** section.`] +.Filtering links in the **properties** section +---- +properties.related[*].href LIKE '%/rec15' AND properties.license.title LIKE 'CC%' +---- + +[#filter-pattern-3,reftext=`Filtering links in the **properties** section.`] +.Filtering links in the **properties** section +---- +properties.related LIKE '%/rec15' AND properties.license LIKE 'https://creativecommons.org/licenses/%' +---- + +====== Filtering by keyword from a controlled vocabulary + +The following example illustrates how to use https://docs.ogc.org/DRAFTS/19-079r1.html[OGC API - Feature - Part 3: Filtering] and https://docs.ogc.org/DRAFTS/21-065.html[CQL2] to query by keywords from a specific controlled vocabulary. + +The use of keywords from a controlled voacbulary is encoded in a record using the <> member. Consider a record that have the following `themes` member: + +---- + "themes": [ + { + "concepts": [ + "dobson", + "brewer", + "vassey", + "pion", + "microtops", + "spectral", + "hoelper", + "saoz", + "filter" + ], + "scheme": "https://geo.woudc.org/codelists.xml#WOUDC_InstrumentCode" + }, + { + "concepts": [ + "atmosphericComposition", + "pollution", + "observationPlatform", + "rocketSounding" + ], + "scheme": "https://wis.wmo.int/2012/codelists/WMOCodeLists.xml#WMO_CategoryCode" + } + ], +---- + +Using https://docs.ogc.org/DRAFTS/19-079r1.html[OGC API - Feature - Part 3: Filtering], a server would need to expose two https://docs.ogc.org/DRAFTS/19-079r1.html#queryables[queryables], `scheme` and `concept` for the purpose of filtering using keywords from a specific controlled vocabulary. Using these queryables, the following filter could be expressed: + +---- +https://www.someserver.com/collections/myCatalog/items?filter-lang=cql2-text&filter=scheme%3D%27https%3A%2F%2Fgeo.woudc.org%2Fcodelists.xml%23WOUDC_InstrumentCode%27%20and%20concept%3D%27spectral%27%2C%0Ahoelper%27 +---- + +An alternative approach that does rely on using https://docs.ogc.org/DRAFTS/19-079r1.html[OGC API - Feature - Part 3: Filtering] and https://docs.ogc.org/DRAFTS/21-065.html[CQL2] would rely on the server defining a set of https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameters_for_filtering_on_feature_properties[query parameters] in the server's https://docs.ogc.org/is/17-069r4/17-069r4.html#_api_definition[API description document], again named `scheme` and `concept`, that would allow the following filter to be expressed: + +---- +https://www.someserver.com/collections/myCatalog/items?scheme=https%3A%2F%2Fgeo.woudc.org%2Fcodelists.xml%23WOUDC_InstrumentCode&concept=spectral,hoelper +---- + +[[clause-autodiscovery]] +=== Requirements Class "Autodiscovery" (Building Block) + +==== Overview + +include::requirements/requirements_class_autodiscovery.adoc[] + +The purpose of autodiscovery is, knowing the URI of a web page, to find the location of that page's associated catalog. + +==== Autodiscovery links + +include::requirements/autodiscovery/REQ_autodiscovery_link.adoc[] + +For example, a client could retrieve the landing page of an OGC API deployment, find the location of the site's catalog by locating the `rel=http://www.opengis.net/def/rel/ogc/1.0/catalog` link and then use that catalog to search for resources offered by the site. + +include::recommendations/autodiscovery/PER_autodiscovery_links.adoc[] + +[[clause-encodings]] +=== Encodings + +[[requirements-class-json-clause]] +==== Requirements Class JSON (Building Block) + +===== Overview + +include::requirements/requirements_class_json.adoc[] + +[[clause-record-encoding]] +===== Record encoding + +GeoJSON is a commonly used format base on JSON that is simple to understand and well supported by tools and software libraries. Since most Web developers are comfortable with using a JSON-based format supporting GeoJSON is recommended, if record data can be represented in GeoJSON for the intended use. + +The following requirements apply when: + +. The API advertises conformance to the JSON Conformance Class +. The client negotiates to a record response in GeoJSON response. + +include::requirements/json/REQ_record-response.adoc[] + +include::requirements/json/REQ_record-content.adoc[] + +[[schema_json_record]] +.link:https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/recordGeoJSON.yaml[Schema for a catalog record in GeoJSON (recordGeoJSON.yaml)] +[source,YAML] +---- +include::../openapi/schemas/recordGeoJSON.yaml[] +---- + +NOTE: Referenced schemas can be found at https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/common/confClasses.yaml[confClasses.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/time.yaml[time.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/geometryGeoJSON.yaml[geometryGeoJSON.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/language.yaml[language.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/theme.yaml[theme.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/contact.yaml[contact.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/license.yaml[license.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/common/link.yaml[common/link.yaml]. + +include::recommendations/json/PER_time.adoc[] + +[[clause-catalog-encoding]] +===== Catalog encoding + +https://datatracker.ietf.org/doc/html/rfc8259[JSON] is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays (or other serializable values). It is a common data format with diverse uses in electronic data interchange, including that of web applications with servers and so is recommended if catalog (i.e. a collection of record) data can be represented in JSON for the intended use. + +The following requirements apply when: + +. The API advertises conformance to the JSON Conformance Class +. The client negotiates to a catalog or record collection response in JSON. + +include::requirements/json/REQ_collection-response.adoc[] + +include::requirements/json/REQ_collection-content.adoc[] + +[[schema_json_collection]] +.link:http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas/catalog.yaml[Schema for a catalog or record collection in JSON(catalog.yaml)] +[source,YAML] +---- +include::../openapi/schemas/catalog.yaml[] +---- + +NOTE: Referenced schemas can be found at http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml[collection.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/common/confClasses.yaml[confClasses.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/language.yaml[language.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/theme.yaml[theme.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/contact.yaml[contact.yaml], https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/license.yaml[license.yaml]. + +[[requirements-class-html-clause]] +==== Requirements Class HTML (Building Block) + +include::requirements/requirements_class_html.adoc[] + +The following requirements apply to an OGC API - Records implementation when the following conditions apply: + +. The API advertises conformance to the HTML Conformance Class +. The client negotiates an HTML format + +Catalog information that is only accessible in formats primarily intended to +be read by machines, such as JSON or XML, have two issues: + +* The data is not discoverable using the most common mechanism for discovering information, that is the search engines of the Web; + +* The data can not be viewed directly in a browser - additional tools are required to view the data. + +Therefore, sharing data on the Web should include publication in HTML. To be consistent with the Web, it should be done in a way that enables users and search engines to access all data. + +This is discussed in detail in link:https://www.w3.org/TR/sdw-bp/#indexable-by-search-engines[Best Practice 2: Make your spatial data indexable by search engines] <>. This standard therefore <>. + +include::requirements/html/REQ_definition.adoc[] + +include::requirements/html/REQ_content.adoc[] + +include::recommendations/html/REC_schema-org.adoc[] + diff --git a/core/standard/clause_7_record.adoc b/core/standard/clause_7_record.adoc deleted file mode 100644 index 6cf74d95..00000000 --- a/core/standard/clause_7_record.adoc +++ /dev/null @@ -1,257 +0,0 @@ -[[clause-record-core]] -== Requirements Class "Record Core" - -[[record-core-overview]] -=== Overview - -include::requirements/requirements_class_record-core.adoc[] - -The `Record` Requirements Class defines the requirements for a catalogue record. - -[[record-model]] -=== Record - -The atomic unit of information in a catalogue is a **_record_** which is defined in this clause. - -It is expected that the information necessary to populate the fields/properties of a catalogue record is readily available for any resource that is being registered in the catalogue. - -It is anticipated that the schema of a record will be extended to describe specific resource types (e.g. datasets, services, etc.) and also extended by information communities wishing to enrich the information content of the record to suit their needs. - -Although this document does not mandate any particular encoding for a record, this document does define conformance classes for two encodings: - -* a <> record encoding, -* and an <> encoding. - -Other encoding are allowed but are not described in this document. - -==== Overview - -[[core-queryables]] -==== Core queryables - -<> and <> define the set of properties, called the _core queryables_, that may be included in a record. - -[#core-queryables-record-table,reftext='{table-caption} {counter:table-num}'] -.Table of Core Queryables related to the catalogue record -[cols="20,5,55,20",options="header"] -|=== -|Queryables |Requirement |Description |GeoJSON key -|recordId |**required** |A unique record identifier assigned by the server. |id -|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 -|conformsTo |optional |The extensions/conformance classes used in this record. |conformsTo -|=== - -[#core-queryables-resource-table,reftext='{table-caption} {counter:table-num}'] -.Table of Core Queryables related to the resource -[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 if there is no 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.keywords -|language |optional |The language used for textual values (i.e. titles, descriptions, etc) of this record. |properties.language -|languages |optional |The list of other languages in which this record is available. |properties.languages -|resourceLanguages |optional |The list of languages in which the resource described by this record can be retrieved. |properties.resourceLanguages -|externalIds |optional |One or more identifiers for the resource assigned by an external entity. |properties.externalIds -|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 -|contacts |optional |A list of contacts qualified by their role(s) in association to the record or resource. |properties.contacts -|license |optional |The legal provisions under which the resource is made available. |properties.license -|rights |optional |A statement that concerns all rights not addressed by the license such as a copyright statement. |properties.rights -|links |**required** |A list of links related to this record. -|=== - -include::requirements/record-core/REQ_mandatory-queryables-record.adoc[] - -include::recommendations/record-core/PER_common-mark.adoc[] - -include::recommendations/record-core/PER_additional-queryables-record.adoc[] - - -[[sc_record_extensions]] -==== Record extensions - -In tables <> and <> this standard defines a set of core properties for describing discoverable resources. It is anticipated that this set of core properties will be extended to suite specific use cases or requirements. For example, a catalogue record may be extended to include additional properties from the https://semiceu.github.io/GeoDCAT-AP/releases/[GeoDCAT] vocabulary. The fact that a catalogue record has been extended in this way can be advertised using the `conformsTo` member. The `conformsTo` member is a list of identifiers that indicate each extension used in a record. This specification does not define the specific identifiers that are used to identify specific extensions; it simply provides a place where these identifiers can be listed. - -include::recommendations/record-core/REC_record-extensions.adoc[] - -In the case where all the records of a catalogue use the same set of extensions, and to prevent unnecessary duplication, there is also a `conformsTo` member at the https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/catalogue.yaml[collection or catalogue level] that may be used to declare which extensions are used in all records of the catalogue. Extensions listed at the catalogue and record levels are cumulative. - -[[sc_temporal_information]] -==== Temporal information - -===== Instants - -include::requirements/record-core/REQ_time-instant.adoc[] - -===== Intervals - -include::requirements/record-core/REQ_time-interval.adoc[] - -===== Instants and intervals - -include::requirements/record-core/REQ_time-instant-interval.adoc[] - -===== Time zones - -include::requirements/record-core/REQ_time-zone.adoc[] - -[[sc_keywords_and_themes]] -==== Keywords and Themes - -A record allows for one `properties.keywords` and zero to many `properties.themes` properties. Keywords are free form terms or tags associated with the resource(s) that the record describes. Themes are concepts associated with the resource(s) that a record describes taken from one or more formal knowledge organization systems or schemes. The list of knowledge organization systems or schemes used in a <> or <> catalogue can be determined by inspecting the server's OpenAPI document or, if the server implements CQL2, by exposing a queryable (e.g. named `scheme`) and enumerating the list of schemes used in the queryable's schema definition. - -include::recommendations/record-core/REC_record-keywords-themes.adoc[] - -The following provides an example of using keywords for free form terms (e.g. tags) as well as themes to articulate terms from formal vocabularies or classification systems. - -[#keywords-themes-example,reftext=`Keywords and themes Example`] -.Keywords and themes Example -[source,json] ----- -include::../examples/json/keywords-themes.json[] ----- - -[[sc_contacts]] -==== Contacts - -include::requirements/record-core/REQ_contact.adoc[] -include::recommendations/record-core/REC_contact.adoc[] - -[[sc_type]] -==== Type - -A record has one `properties.type` property. The value of this property should be a code, convenient for filtering records. - -include::recommendations/record-core/REC_record-type.adoc[] - -include::recommendations/record-core/PER_record-type.adoc[] - -In addition, links to external resources describing the record type vocabulary used to populate the `properties.type` member are recommended, as described in <>. - -[[sc_license]] -==== License - -A record may have one `properties.license` property. If present, the value of this property should be a code, convenient for filtering records. - -include::requirements/record-core/REQ_record-license.adoc[] - -[[sc_associations_and_links]] -==== Associations and Links - -A record must contain a `links` section. This `links` section many contain navigation links and/or association links. - -Navigation links are meant to encode relationships between catalogue entities (i.e. <> and <>). Navigation links in the `links` section can include links to the collection (`rel="collection`) of which a record is a member, alternative representations (`rel="alternate"`) of the record, and -- in the context of an API -- navigation links to previous (`rel="prev"`) or next (`rel="next"`) records in a chain of records. Links in the `links` section may also be used to organize records in a hierarchy (`rel="root"`, `rel="parent"`, `rel="child`). - -include::requirements/record-core/REQ_record-links.adoc[] - -Links in the `links` section may also encode canoncial URIs for record properties such as `type` and `license`. - -include::recommendations/record-core/REC_record-links_type.adoc[] - -include::recommendations/record-core/REC_record-links_iana.adoc[] - -Association links point to the resource(s) being described by a record. Such links allow binding to a resource once it has been discovered by searching a catalogue. Depending on how the target resource of a record is represented and how it may be accessed, there may be one or more association links. For example, if the target resource is an Earth observation imagery file, links may point to the indivdually accessible bands of the image file. - -Association links are also meant to point to other records related to the containing record. For example, consider a record that describes a set of vector features and another record that describes a rendering style for that feature set. These two records may, in their respective `links` sections point to each other to encode this "styles"/"styled-by" relationship. - -Finally, association links are meant to point to other resources external to the catalogue that are related to the containing record or the resource(s) that the record describes. - -include::recommendations/record-core/REC_record-associations_relate.adoc[] - -In some instances additional context may be desirable or required in order to access (or bind to) the resource(s) being described by a record. This is the case when, for example, access to the resource is through a service interface that requires mandatory parameters to be provided. The OGC Web Map Service (WMS) is an example of such a service. It may also be the case that efficient access to the resource would be facilitated by providing additional context. Accessing data from a large data repository such as a data cube would be more efficient if the context of the query used to discover the resource (e.g. bbox, datetime) were passed down to the link used to access the data. - -include::recommendations/record-core/REC_record-associations_templated.adoc[] - -NOTE: This specification does not define any specific link relations that should be used for links in the `links` section. Such relationships are typically domain specific and so it is left to communities of interest to standardize the links that relations should use. - -The following provides an example of using association links for related resources of a record, as both traditional link relations as well as API resources via URI templates. - -[#associations-simple-and-uri-template-example,reftext=`Associations simple and URI Template Example`] -.Associations simple and URI Template Example -[source,json] ----- -include::../examples/json/associations-simple-and-uri-template.json[] ----- - -[[example_11]] -.Links in a record payload -==== -The links in a record could be (in this example represented as link headers): - -[source] ----- -Link: ; rel="self"; type="application/geo+json" -Link: ; rel="alternate"; type="text/html" -Link: ; rel="collection"; type="application/json" -Link: ; rel="collection"; type="text/html" ----- -==== - -[[sc_templated_links_with_variables]] -==== Templated links with variables - -OGC API - Records uses links to express associations between resources including links that bind to the resource(s) being described by a record. In some situations, a static link does not adequately express all the information necessary to retrieve the referenced resource OR does not allow for the resource to be retrieved in an efficient manner. - -Consider the case where a record describing a coverage resource is discovered by searching the catalogue using a spatial constraint (e.g. a bbox). Further consider that the found record contains a link to retrieve the coverage. Using a static link for the binding link would only allow retrieval of the entire coverage. Using a templated link, however, would allow the context of the catalogue query (i.e. the bbox) to be passed to down to the binding link. The templated link with all substitution values resolved would thus retrieve the subset of the coverage that corresponds to the spatial contraint used to discover the record in the first place which presumably represents the area of interest. - -Templated links may also be used to bind to resources that may require additional information in order to access the resources. For example, simply knowing the URL of a legacy OGC service such as WMS or WFS is not sufficient to access resources offered by those services. Additional information in the form of request parameters and values are required in order to have a complete link to a resources. A templated link with variables can provide this additional context. - -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://schemas.opengis.net/ogcapi/common/part1/1.0/openapi/schemas/link.yaml[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[] - -[#templated-link-with-variables,reftext=`Associations simple and URI Template Example`] -.Templated link with variables example -[source,json] ----- -include::../examples/json/templated-link.json[] ----- - -==== Resource timestamps - -A <> contains information, encoded in the links section, for accessing one or more resources described by the record. 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-records/blob/master/core/openapi/schemas/common/link.yaml[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_record_language_handling]] -==== Language handling - -===== Overview - -A catalogue record can include language information about: - -* the resource that the record describes, -* the language used for text values in the current record representation, -* and alternate languages in which the current record can be represented. - -===== Language of the record - -include::recommendations/record-core/REC_record-lang.adoc[] - -The https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/common/link.yaml[link object] based on https://docs.ogc.org/is/17-069r4/17-069r4.html#rfc8228[RFC 8288 (Web Linking)] includes a `hreflang` attribute that can be used to state the language of a referenced resource. This can be used to include links to the same record in different languges. - -[[minting-language-specific-uris]] -A server that wants to use language-specific links will have to support a mechanism to mint language-specific URIs in order to express links to the same record in other languages or to express links to the resource described by record in multiple languages. This document does not mandate any particular approach how such a capability is supported by a server. - -[NOTE] -===================================================================== -Two common approaches are: - -* an additional path element for each language-specific encoding of a record or resource (this can be expressed, for example, using a language-specific path element like `.../en-ca/...`); - -* an additional query parameter (for example, https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/parameter/language.yaml["language"] or "l") that overrides the Accept-Language header of the HTTP request. -===================================================================== - -[NOTE] -===================================================================== -There is no provision in the record schema to allow a response containing text fields simultaneously presented in multiple languages (e.g. multiple titles in different languages). To obtain a record in multiple languages would require multiple requests to the server each negotiating to a desired language. -===================================================================== - -===== Language of the resource - -include::recommendations/record-core/REC_resource-langs.adoc[] diff --git a/core/standard/clause_8_collection.adoc b/core/standard/clause_8_collection.adoc deleted file mode 100644 index ed970560..00000000 --- a/core/standard/clause_8_collection.adoc +++ /dev/null @@ -1,79 +0,0 @@ -[[clause-record-collection]] -== Requirements Class "Record Collection" - -[[record-collection-overview]] -=== Overview - -include::requirements/requirements_class_record-collection.adoc[] - -This requirements class defines the requirements for a record collection. - -A _collection_ is an object that provides information about and access to a set of related <>. Such a collection of records is also referred to as a _catalogue_. - -The schema for the collection resource is an extension of the collection schema defined in http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features]. - -While http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features] defines a specific location for the collection resource (path: `/collections/{collectionId}`), OGC API - Records only fixes the location of the collection in the <> conformance class. Otherwise the collection resource can live anywhere the provider wishes to place it including as a static file in web space (e.g. a web-accessible directory or an S3 bucket). - -[[record-collection-schema]] -=== Record collection schema - -<> defines the set of properties that may be used to describe a collection of records. - -[#collection-properties-table,reftext='{table-caption} {counter:table-num}'] -.Table of collection properties -[cols="30,5,65",options="header"] -|=== -|Queryables |Requirement |Description -|_**id**_ |**required** |A unique identifier for this collection. -|_**title**_ |**required** |A human-readable name given to this collection. -|_**description**_ |optional |A free-text description of this collection. -|_**links**_ |**required** |A list of links related to this collection. -|_**extent**_ |optional |The spatio-temporal coverage of thos collection. -|_**itemType**_ |**required** |Fixed to the value "record". -|_**crs**_ |optional |A list of coordinate reference systems used for spatial-temporal values. -|type |**required** |The nature or genre of the resource. Fixed to "Collection". -|keywords |optional |A list of free-form keywords or tags associated with this collection. -|language |optional |The language used for textual values (i.e. titles, descriptions, etc) of this collection object. -|languages |optional |The list of other languages in which this collection object is available. -|recordLanguages |optional |The list of languages in which records from the collection can be represented. -|created |optional |The date this collection was created. -|updated |optional |The more recent date on which this collection was changed. -|contacts |optional |A list of contacts qualified by their role(s). -|themes |optional |A knowledge organization system used to classify this collection. -|license |optional |The legal provisions under which this collection is made available. -|rights |optional |A statement that concerns all rights not addressed by the license such as a copyright statement. -|=== - -NOTE: The properties _id_, _title_, _description_, _links_, _extent_, _itemsType_ and _crs_ were inherited from http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#\_collection\_[OGC API - Features]. - -include::requirements/record-collection/REQ_mandatory-queryables.adoc[] - -include::recommendations/record-collection/PER_common-mark.adoc[] - -include::recommendations/record-collection/PER_additional-queryables.adoc[] - -=== Keywords and Themes - -See <> for a record. - -=== Links - -include::requirements/record-collection/REQ_links.adoc[] - -include::recommendations/record-collection/PER_links.adoc[] - -=== Templated links with variables - -See <> for a record. - -=== Language handling - -Language handling for the collection object is analogous to <> for a record. - -include::recommendations/record-collection/REC_collection-lang.adoc[] - -include::recommendations/record-collection/REC_record-langs.adoc[] - -=== Encodings - -This specification defines requirements for JSON and HTML encoding of a catalogue. See <>. diff --git a/core/standard/clause_8_deployments.adoc b/core/standard/clause_8_deployments.adoc new file mode 100644 index 00000000..52f1ecc4 --- /dev/null +++ b/core/standard/clause_8_deployments.adoc @@ -0,0 +1,375 @@ +[[catalog-deployments]] +== Catalog deployments + +=== Overview + +This clause uses the <> defined in this standard to define various catalog deployments. + +[[clause-crawlable-catalog]] +=== Requirements Class "Crawlable Catalog" (Deployment) + +[[crawlable-catalog-overview]] +==== Overview + +include::requirements/requirements_class_crawlable-catalog.adoc[] + +The `Crawlable Catalog` Requirements Class defines the requirements for a catalog composed of static, web-accessible files. + +The goal of a crawlable catalog is to expose metadata about resources online with as low an entry barrier as possible, thus making those resource more easily discoverable. + +A crawlable catalog is a deployment pattern that uses the <> and <> building blocks defined in this standard. It is simply a set of files deployed on the web that encode, usually in HTML or JSON, the <> and <> defined in this standard. The files contain embedded links to enable navigation from one to another. Any HTTP server or cloud storage service, for example, could be used to expose the files of a crawlable catalog. + +A crawlable catalog is not searchable and does not respond to query requests. As the name implies, it can only be crawled (or harvested) by following the embedded links; typically by search engines and other active catalogs or browsed using a web browser. However, due to its simplicity, a crawlable catalog is easy to deploy and maintain, and is very reliable. + +NOTE: It should be pointed out that a <> can also behave as a crawlable catalog as long as the requirements in this clause are satisfied by the <> implementation. + +[[crawlable-catalog-record]] +==== Making a resource discoverable + +include::requirements/crawlable-catalog/REQ_record.adoc[] + +Attention is drawn to requirement <> that allows the information content of the record to be enriched as required to describe the resource being made discoverable. + +include::requirements/crawlable-catalog/REQ_record-links.adoc[] + +include::requirements/crawlable-catalog/REQ_record-file-location.adoc[] + +include::recommendations/crawlable-catalog/REC_record-file-name.adoc[] + +include::recommendations/crawlable-catalog/REC_record-file-location.adoc[] + +For example, the record file could be placed in the same web-accessible directory or object store as the resource(s) that the record describes. + +[[crawlable-catalog]] +==== Grouping a collection of records into a catalog + +include::requirements/crawlable-catalog/REQ_catalog.adoc[] + +include::requirements/crawlable-catalog/REQ_catalog-location.adoc[] + +include::requirements/crawlable-catalog/REQ_catalog-links.adoc[] + +[[crawlable-collections]] +==== Grouping catalogs (and other resources) into collections + +In order to provide flexibility with regard to how crawlable catalogs can be organized (e.g. a hierarchy) the same catalog object (see: http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas/catalog.yaml[catalog.yaml]) used to organized related collections of records into a catalog may also be used as a common entry point for crawling to multiple, related, sub-collections, catalogs, records and other resources. In this use case, the term _collection_ is used to refer to a http://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas/catalog.yaml[catalog object]. + +include::requirements/crawlable-catalog/REQ_collection.adoc[] + +include::recommendations/crawlable-catalog/PER_additional-collection-properties.adoc[] + +include::requirements/crawlable-catalog/REQ_collection-location.adoc[] + +include::requirements/crawlable-catalog/REQ_itemType.adoc[] + +include::requirements/crawlable-catalog/REQ_collection-links.adoc[] + +include::recommendations/crawlable-catalog/REC_collection-links.adoc[] + +[[clause-searchable-catalog]] +=== Requirements Class "Searchable Catalog" (Deployment) + +include::requirements/requirements_class_searchable-catalog.adoc[] + +The `Searchable Catalog` Requirements Class defines the requirements for a catalog that is searchable through an API. A searchable catalog is an implementation of <> that uses a defined information model. In the case of OGC API - Records, that information model is the <>. + +include::requirements/searchable-catalog/REQ_core.adoc[] + +include::recommendations/searchable-catalog/PER_additional-requirements.adoc[] + +include::requirements/searchable-catalog/REQ_mandatory-properties.adoc[] + +include::recommendations/searchable-catalog/PER_additional-properties.adoc[] + +[[clause-searchable-catalog_sorting]] +==== Requirements Class "Searchable Catalog - Sorting" (Deployment) + +include::requirements/requirements_class_searchable-catalog_sorting.adoc[] + +This conformance class specifies requirements for supporting sorting of responses at searchable catalog endpoints. + +include::requirements/searchable-catalog_sorting/REQ_sorting.adoc[] + +[[clause-searchable-catalog_filtering]] +==== Requirements Class "Searchable Catalog - Filtering" (Deployment) + +include::requirements/requirements_class_searchable-catalog_filtering.adoc[] + +This conformance class specifies requirements and recommendations for supporting advanced filtering at searchable catalog endpoints. + +===== Filter queryables + +include::requirements/searchable-catalog_filtering/REQ_mandatory-queryables.adoc[] + +include::recommendations/searchable-catalog_filtering/REQ_additional-queryables.adoc[] + +===== Coordinate reference systems + +include::requirements/searchable-catalog_crs/REQ_crs.adoc[] + +[[clause-local-resources-catalog]] +=== Requirements Class "Local Resources Catalog" (Deployment) + +[[local-resources-catalog-overview]] +==== Overview + +include::requirements/requirements_class_local-resources-catalog.adoc[] + +This conformance class specifies requirements for a _local resources catalog_. + +The OGC API defines a number of resource endpoints that provide lists of +sub-resources. These endpoints are referred to as _local resources catalogs_ in this standard because they provide metadata about resources offered locally by an OGC API deployment. + +NOTE: The term _local resources endpoint_ is used to reference to the resource path of the _local resources catalog_. The term _local resources object_ is used to refer to an instance of the object or resource that can be retrieved from the _local resources endpoint_. + +The `/collections` endpoint is an example of a _local resources endpoint_. This endpoint provides a list of objects describing the collections of items offered by an OGC API deployment. Each offered collection (path `/collections/{collectionId}`) is described by a _local resources object_ containing a small number of properties. A common set of properties is defined in https://docs.ogc.org/DRAFTS/20-024.html[OGC API - Common - Part 2: Geospatial Data] and can be extended by resource-specific specifications (e.g. http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC API - Feature - Part 1: Core]). In this respect, the `/collections` endpoint is a catalog of records (i.e. `/collections/{collectionId}` objects) describing the collections of items offered by the OGC API deployment. + +Other _local resources catalogs_ available in the OGC API resource tree include the `/processes` endpoint which provides a list of offered processes and the `/collections/{collectionId}/scenes` endpoint which provides a list of source images of a coverage. + +In order to enable catalog-like searching at these local resources endpoints, this conformance class defines requirements and recommendations that: + +1. enhance the information content of each local resources object (e.g. the `/collection/{collectionId}` object) with additional members from the list of <> defined for a catalog <>, + +2. define or extend the set of query parameters available at the local resources endpoint (e.g. `/collections`) to enhance it searchability. + +This conformance class does not define the specific endpoints in the OGC API resource tree that should be enabled with catalog-like query capabilities. It only defines how those endpoints should be enhanced should the requirement for catalog-line searching be identified by the responsible OGC standard. + +==== Resource Description + +===== Overview + +The clause defines requirements and recommendations for the information content of a local resources object that can be retrieved from local resources endpoint. + +As an example of a local resources endpoint, consider the `/collections` endpoint. The object that can be retrieved from this endpoint is defined in https://docs.ogc.org/DRAFTS/20-024.html[OGC API - Common] and http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collections_[OGC API - Features]. The following table cross-walks the information content of the collection object with the <> defined for the <> building block: + +[[record-collection-crosswalk]] +[reftext='{table-caption} {counter:table-num}'] +.Crosswalk of core properties with collection information object properties +[cols="25,25,25,25",options="header"] +|=== +|Collection property |Requirement |Core Property |Requirement +|id |M |id |M +|title |O |title |M +|description |O |description |M +|itemType |O |-- |-- +|extent |O |extent |O +|links |M |links |O +|crs |O |-- |-- +|=== + +It is evident that there is significant overlap of the properties of each resource. This standard defines the following requirements and recommendations with regard to information content of a local resources object such as the collection object that is retrievable from the `/collections` endpoint. + +===== Property `title` + +include::requirements/local-resources-catalog/REQ_property-title.adoc[] + +===== Property `description` + +include::requirements/local-resources-catalog/REQ_property-description.adoc[] + +include::recommendations/local-resources-catalog/PER_common-mark.adoc[] + +===== Property `extent` + +include::recommendations/local-resources-catalog/REC_property-extent.adoc[] + +===== Property `links` + +include::recommendations/local-resources-catalog/REC_property-links.adoc[] + +===== Property `type` + +include::requirements/local-resources-catalog/REQ_property-type.adoc[] + +===== Property `created` + +include::requirements/local-resources-catalog/REQ_property-created.adoc[] + +===== Property `updated` + +include::requirements/local-resources-catalog/REQ_property-updated.adoc[] + +NOTE: Adding, modifying, or deleting items from a collection are all examples of changes that may occur that would require an update of the collection object that can be retrieved from the `/collections` endpoint. + +===== Property `keywords` + +include::requirements/local-resources-catalog/REQ_property-keywords.adoc[] + +===== Additional properties + +include::recommendations/local-resources-catalog/PER_additional-properties.adoc[] + +===== Example + +The following JSON Schema fragment illustrates how the feature collection object (path: `/collection/{collectionId}`) can be extended to include properties required and recommended by this conformance class: + +[source,yaml] +---- + allOf: + - $ref: "http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml" + - type: object + required: + - type + - created + - updated + - keywords + properties: + type: + description: + The nature or genre of the items of the collection (e.g. feature, + coverage) + type: string + created: + description: + The date this collection was created in the server. + type: string + format: date-time + updated: + description: + The most recent date on which the collection was updated. + type: string + format: date-time + keywords: + description: + A list of free-form keywords or tag associated with the collection + type: array + items: + type: string + language: + description: + The natural language used for textual values (i.e. titles, + descriptions, etc) of items in the collection. + type: string + themes: + type: array + description: + A knowledge organization system used to classify the resource. + minItems: 1 + items: + type: object + properties: + concepts: + type: array + description: + One or more entity/concept identifers from this knowledge + system. it is recommended that a resolvable URI be used + for each entity/concept identifier. + minItems: 1 + items: + type: object + properties: + id: + type: string + description: + An identifier for the concept. + title: + type: string + description: + A human readable title for the concept. + description: + type: string + description: + A human readable description for the concept. + url: + type: string + format: uri + description: + A URI providing further description of the concept. + required: + - id + scheme: + type: string + description: + An identifier for the knowledge organization system used + to classify the resource. It is recommended that the + identifier be a resolvable URI. + required: + - concepts + - scheme + contacts: + description: + The entity to contact about the collection. + type: array + items: + $ref: contact.yaml + license: + description: + The legal provisions under which the collection is made available. + type: string + rights: + description: + A statement that concerns all rights not addressed by the license + such as a copyright statement. + type: string +---- + +T.D.B. Should add an instance example of a collection object. + +==== Query parameters + +include::requirements/local-resources-catalog/REQ_query-parameters.adoc[] + +==== Response + +include::requirements/local-resources-catalog/REQ_response.adoc[] + +[[clause-local-resources-catalog_sorting]] +==== Requirements Class "Local Resources Catalog - Sorting" (Deployment) + +include::requirements/requirements_class_local-resources-catalog_sorting.adoc[] + +This conformance class specifies requirements and recommendations for supporting sorting of responses at _local resource catalog_ endpoints. + +===== Operation + +include::requirements/local-resources-catalog_sorting/REQ_param-sortby-def.adoc[] + +===== Response + +include::requirements/local-resources-catalog_sorting/REQ_param-sortby-response.adoc[] + +See also: <>, <>. + +===== Examples + +Example 1: List all the collections that lie within a specific bounding box and contain the keyword `weather`. + +---- + Client Server + | | + | GET /collections?bbox=41.875315,-96.767601,56.732861,-73.476| + | 586&q=weather HTTP/1.1 | + | Accept: application/json | + |-------------------------------------------------------------->| + | | + | HTTP/1.1 200 OK | + | Content-Type: application/json | + | | + | T.B.D. Need example output here... | + |<--------------------------------------------------------------| +---- + +[[clause-local-resources-catalog_filtering]] +==== Requirements Class "Local Resources Catalog - Filtering" (Deployment) + +include::requirements/requirements_class_local-resources-catalog_filtering.adoc[] + +This conformance class specifies requirements and recommendations for supporting advanced filtering at _local resource catalog_ endpoints. + +===== Operation + +include::requirements/local-resources-catalog_filtering/REQ_filter-param.adoc[] + +include::requirements/local-resources-catalog_filtering/REQ_filter-lang-param.adoc[] + +include::recommendations/local-resources-catalog_filtering/REC_text-encoding.adoc[] + +include::recommendations/local-resources-catalog_filtering/REC_json-encoding.adoc[] + +include::requirements/local-resources-catalog_filtering/REQ_filter-crs-param.adoc[] + +include::requirements/local-resources-catalog_filtering/REQ_queryables-link.adoc[] + +===== Response + +include::requirements/local-resources-catalog_filtering/REQ_filter-response.adoc[] diff --git a/core/standard/clause_9_api.adoc b/core/standard/clause_9_api.adoc deleted file mode 100644 index 25bd8260..00000000 --- a/core/standard/clause_9_api.adoc +++ /dev/null @@ -1,172 +0,0 @@ -[[clause-records-api]] -== Requirements Class "Records API" - -[[records-api-overview]] -=== Overview - -include::requirements/requirements_class_records-api.adoc[] - -The core API for a catalogue is defined by the http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] standard. - -include::requirements/records-api/REQ_resource-name-mapping.adoc[] - -=== Declarations of conformance class - -include::requirements/records-api/REQ_conformance-classes.adoc[] - -include::recommendations/records-api/PER_conformance-classes.adoc[] - -=== Encodings - -While OGC API - Records does not specify any mandatory encoding, support for the following encodings is recommended. - -include::recommendations/records-api/REC_html.adoc[] - -include::recommendations/records-api/REC_json.adoc[] - -The requirements specified in the <> sub-clause imply that the encoding of a server response is determined using content negotiation as specified by the HTTP RFC. - -The <> sub-clause includes guidance on media types for encodings that are specified in this document. - -Note that any server that supports multiple encodings will have to support a mechanism to mint encoding-specific URIs for resources in order to express links, for example, to alternate representations of the same resource. This document does not mandate any particular approach how this is supported by the server. - -As clients simply need to dereference the URI of the link, the implementation details and the mechanism how the encoding is included in the URI of the link are not important. Developers interested in the approach of a particular implementation, for example, to manipulate ("hack") URIs in the browser address bar, can study the API definition. - -[NOTE] -===================================================================== -Two common approaches are: - -* an additional path for each encoding of each resource (this can be expressed, -for example, using format specific suffixes like ".html"); - -* an additional query parameter (for example, "accept" or "f") that overrides -the Accept header of the HTTP request. -===================================================================== - -[[record-collection]] -=== Record collection response - -include::requirements/records-api/REQ_record-collection-response.adoc[] - -[[record-collections]] -=== Record collections response - -include::requirements/records-api/REQ_record-collections-response.adoc[] - -[[records-access]] -=== Records access - -==== Operation - -include::requirements/records-api/REQ_records-op.adoc[] - -[[parameters-section]] -==== Parameters - -===== Overview - -include::requirements/records-api/REQ_mandatory-params.adoc[] - -[#core-query-parameters-table,reftext='{table-caption} {counter:table-num}'] -.Table of Query Parameters -[cols="15,85",options="header"] -|=== -|Parameter name |Description -|https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_parameter_bbox[bbox] |A bounding box. If the spatial extent of the record intersects the specified bounding box then the record shall be presented in the response document. -|https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_parameter_datetime[datetime] |A time instance or time period. If the temporal extent of the record intersects the specified data/time value then the record shall be presented in the response document. -|https://docs.opengeospatial.org/is/17-069r4/17-069r4.html#_parameter_limit[limit] |The number of records to be presented in a response document. -|q |A comma-separated list of search terms. If any server-chosen text field in the record contains 1 or more of the terms listed then this records shall appear in the response set. -|type |An equality predicate consistent of a comma-separated list of resource types. Only records of the listed type shall appear in the resource set. -|externalid |An equality predicate consistent of a comma-separated list of external resource identifiers. Only records with the specified external identifiers shall appear in the response set. -|_prop_=_value_ |Equality predicates with any <> not already listed in this table. -|=== - -[[core-query-parameters-q]] -===== Parameter q - -include::requirements/records-api/REQ_query-param-q-definition.adoc[] - -include::recommendations/records-api/REC_param-q.adoc[] - -include::requirements/records-api/REQ_query-param-q-response.adoc[] - -[[core-query-parameters-type]] -===== Parameter type - -include::requirements/records-api/REQ_query-param-type-definition.adoc[] - -include::recommendations/records-api/REC_query-param-type-definition.adoc[] - -include::requirements/records-api/REQ_query-param-type-response.adoc[] - -[[core-query-parameters-externalid]] -===== Parameter externalId - -include::requirements/records-api/REQ_query-param-externalid-definition.adoc[] - -include::requirements/records-api/REQ_query-param-externalid-response.adoc[] - -[[additional-query-parameters]] -===== Additional query parameters - -This standard defines the following URL query parameters based on the set of -<> to support record selection -based on the resource type and/or an external identifier associated with the -resource. - -* <> -* <> - -include::recommendations/records-api/REC_additional-query-parameters.adoc[] - -===== Combinations of Filtering Parameters - -Any combination of query parameters from the <> and any <> may be specified for filtering. Note that the requirements on these parameters imply that only records matching all the predicates are in the result set; i.e., the logical operator between the predicates is **AND** (exclusive). - -[[query-response]] -==== Response - -<> lists specific requirements based on the negotiated representation of the response. - -[#response-encodings,reftext='{table-caption} {counter:table-num}'] -.Negotiated representation of response -[width=40%,cols="30%,70%",options="header"] -|=== -|Representation |Requirements -|JSON/GeoJSON |<> -|HTML |<> -|=== - -==== Examples - -The following is an example of a response to an OGC API - Records query operation (path: `/collections/{collectionId}/items`). This example shows a JSON response and the response container is a GeoJSON feature collection. Specific records are not presented in this example in order to illustrate the structure of the response container in GeoJSON. - -[#records-example,reftext=`Records Example`] -.Records Example in GeoJSON -[source,json] ----- -include::../examples/json/record-collection.json[] ----- - -The following is an example of a single catalogue record encoded in GeoJSON. -Such a record might appear in the `features` array of a -<> or it may be the response when a specific, -single record is accessed (path: `/collections/{collectionId}/items/{recordId}`). - -[#record-example,reftext=`Record Example`] -.Record Example in GeoJSON -[source,json] ----- -include::../examples/json/record.json[] ----- - -[[record-access]] -=== Record access - -==== Operation - -include::requirements/records-api/REQ_record-op.adoc[] - -==== Response - -include::requirements/records-api/REQ_record-response.adoc[] diff --git a/core/standard/clause_17_media_types.adoc b/core/standard/clause_9_media_types.adoc similarity index 84% rename from core/standard/clause_17_media_types.adoc rename to core/standard/clause_9_media_types.adoc index 8c39164a..524dc1b7 100644 --- a/core/standard/clause_17_media_types.adoc +++ b/core/standard/clause_9_media_types.adoc @@ -22,23 +22,21 @@ Support for JSON is recommended. JSON is a commonly used format that is simple t GeoJSON provides a simple way of representing OGC Records in JSON and is supported by numerous geospatial tools and software libraries. It is best used for content which has a spatial extent that can be used with the World Geodetic System 1984 Coordinate Reference System. -=== XML Encoding -XML is a commonly used format that is well supported by tools and software libraries. +==== Media types -XML structures documented in this standard are defined using XML Schema. These schemas are available from http://schemas.opengis.net/ogcapi/records/part1/1.0/xml/core.xsd[OGC API - Records Core XML Schema]. - -=== Media Types A description of the MIME-types is mandatory for any OGC standard which involves data encodings. The list of suitable MIME-types for the API - Records standard in provided in <>. [#media-types-table,reftext='{table-caption} {counter:table-num}'] .API - Records MIME Types [width="90%",cols="2,4"] |==== -^|*Encoding* ^|*MIME Type* -|HTML |`text/html` -|JSON |`application/json` -|GeoJSON |`application/geo+json` -|XML |`application/xml` +^|*Encoding* ^|*MIME Type* + |Record encoded as HTML |`text/html` + |Record encoded as GeoJSON |`application/geo+json; application=ogc-record` + |Catalog encoded as HTML |`text/html` + |Catalog encoded as JSON |`application/ogc-catalog+json` + |Collection encoded as HTML |`text/html` + |Collection encoded as JSON |`application/ogc-collection+json` |==== [[media-type-defaults]] diff --git a/core/standard/recommendations/autodiscovery/PER_autodiscovery_links.adoc b/core/standard/recommendations/autodiscovery/PER_autodiscovery_links.adoc index cc841553..e6062683 100644 --- a/core/standard/recommendations/autodiscovery/PER_autodiscovery_links.adoc +++ b/core/standard/recommendations/autodiscovery/PER_autodiscovery_links.adoc @@ -3,5 +3,5 @@ |=== ^|*Permission {counter:per-id}* |*/per/autodiscovery/links* -A web page MAY contain multiple <> pointing to multiple associated catalogues. +A web page MAY contain multiple <> pointing to multiple associated catalogs. |=== diff --git a/core/standard/recommendations/crawlable-catalog/PER_additional-collection-properties.adoc b/core/standard/recommendations/crawlable-catalog/PER_additional-collection-properties.adoc new file mode 100644 index 00000000..059d6bf5 --- /dev/null +++ b/core/standard/recommendations/crawlable-catalog/PER_additional-collection-properties.adoc @@ -0,0 +1,8 @@ +[per_crawlable-catalog_additional-collection-properties]] +[width="90%",cols="2,6a"] +|=== +^|*Permission {counter:per-id}* |*/per/crawlable-catalog/additional-collection-properties* + +^|A |A collection MAY contain zero or more of the optional properties listed in <>. +^|B |A collections MAY contain any number of additional properties not listed in <>. The meaning of these additional properties is not specified in this document. +|=== diff --git a/core/standard/recommendations/crawlable-catalogue/PER_common-mark.adoc b/core/standard/recommendations/crawlable-catalog/PER_common-mark.adoc similarity index 61% rename from core/standard/recommendations/crawlable-catalogue/PER_common-mark.adoc rename to core/standard/recommendations/crawlable-catalog/PER_common-mark.adoc index c7409f5b..d2b45b5d 100644 --- a/core/standard/recommendations/crawlable-catalogue/PER_common-mark.adoc +++ b/core/standard/recommendations/crawlable-catalog/PER_common-mark.adoc @@ -1,7 +1,7 @@ -[[per_crawlable-catalogue_common-mark]] +[[per_crawlable-catalog_common-mark]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/per/crawlable-catalogue/common-mark* +^|*Recommendation {counter:rec-id}* |*/per/crawlable-catalog/common-mark* For any `description` member in a _collections object_, https://spec.commonmark.org/current/[CommonMark] MAY be used for a rich text representation. |=== diff --git a/core/standard/recommendations/crawlable-catalog/REC_collection-links.adoc b/core/standard/recommendations/crawlable-catalog/REC_collection-links.adoc new file mode 100644 index 00000000..a87b5f86 --- /dev/null +++ b/core/standard/recommendations/crawlable-catalog/REC_collection-links.adoc @@ -0,0 +1,8 @@ +[[rec_crawlable-catalog_collection-links]] +[width="90%",cols="2,6a"] +|=== +^|*Recommendation {counter:rec-id}* |*/rec/crawlable-catalog/collection-links* + +^|A |A collection object SHOULD include one or more links (`rel=child`) that point to each child entity (sub-collection, catalog, record, other resources) of this collection. +^|B |A collection object SHOULD include a link (`rel=parent`) that points to this collection's parent collection. +|=== diff --git a/core/standard/recommendations/crawlable-catalog/REC_record-file-location.adoc b/core/standard/recommendations/crawlable-catalog/REC_record-file-location.adoc new file mode 100644 index 00000000..989e5f40 --- /dev/null +++ b/core/standard/recommendations/crawlable-catalog/REC_record-file-location.adoc @@ -0,0 +1,7 @@ +[[rec_crawlable-catalog_record-file-location]] +[width="90%",cols="2,6a"] +|=== +^|*Recommendation {counter:rec-id}* |*/rec/crawlable-catalog/record-file-location* + +The record file SHOULD be located close to the resource(s) that the record describes. +|=== diff --git a/core/standard/recommendations/crawlable-catalogue/REC_record-file-name.adoc b/core/standard/recommendations/crawlable-catalog/REC_record-file-name.adoc similarity index 51% rename from core/standard/recommendations/crawlable-catalogue/REC_record-file-name.adoc rename to core/standard/recommendations/crawlable-catalog/REC_record-file-name.adoc index 9ff4104d..99b24dd8 100644 --- a/core/standard/recommendations/crawlable-catalogue/REC_record-file-name.adoc +++ b/core/standard/recommendations/crawlable-catalog/REC_record-file-name.adoc @@ -1,7 +1,7 @@ -[[rec_crawlable-catalogue_record-file-name]] +[[rec_crawlable-catalog_record-file-name]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/crawlable-catalogue/record-file-name* +^|*Recommendation {counter:rec-id}* |*/rec/crawlable-catalog/record-file-name* The name of the record file should be `{id}.json` where `{id}` is the identifier of the record. |=== diff --git a/core/standard/recommendations/crawlable-catalogue/PER_additions-collections-properties.adoc b/core/standard/recommendations/crawlable-catalogue/PER_additions-collections-properties.adoc deleted file mode 100644 index fa284e78..00000000 --- a/core/standard/recommendations/crawlable-catalogue/PER_additions-collections-properties.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[per_crawlable-catalogue_additional-collections-properties]] -[width="90%",cols="2,6a"] -|=== -^|*Permission {counter:per-id}* |*/per/crawlable-catalogue/additional-collections-properties* - -^|A |A _collections object_ MAY contain zero or more of the optional properties listed in <>. -^|B |A _collections object_ MAY contain any number of additional properties not listed in <>. The meaning of these additional properties is not specified in this document. -|=== - diff --git a/core/standard/recommendations/crawlable-catalogue/REC_collections-links.adoc b/core/standard/recommendations/crawlable-catalogue/REC_collections-links.adoc deleted file mode 100644 index 8b7b8005..00000000 --- a/core/standard/recommendations/crawlable-catalogue/REC_collections-links.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[rec_crawlable-catalogue_collections-links]] -[width="90%",cols="2,6a"] -|=== -^|*Recommendation {counter:rec-id}* |*/rec/crawlable-catalogue/collections-links* - -^|A |The collections object SHOULD include one or more links (`rel=child`) that point to each child entity (sub-collection, catalogue, record, other resources) of this collections object. -^|B |The collections object SHOULD include a link (`rel=parent`) that points to this collections object's parent collections object. -|=== diff --git a/core/standard/recommendations/crawlable-catalogue/REC_record-file-location.adoc b/core/standard/recommendations/crawlable-catalogue/REC_record-file-location.adoc deleted file mode 100644 index 22b95660..00000000 --- a/core/standard/recommendations/crawlable-catalogue/REC_record-file-location.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[rec_crawlable-catalogue_record-file-location]] -[width="90%",cols="2,6a"] -|=== -^|*Recommendation {counter:rec-id}* |*/rec/crawlable-catalogue/record-file-location* - -The record file SHOULD be located close to the resource(s) that the record describes. -|=== diff --git a/core/standard/recommendations/json/PER_time.adoc b/core/standard/recommendations/json/PER_time.adoc new file mode 100644 index 00000000..12c56a1a --- /dev/null +++ b/core/standard/recommendations/json/PER_time.adoc @@ -0,0 +1,7 @@ +[[per_json_time]] +[width="90%",cols="2,6a"] +|=== +^|*Permission {counter:per-id}* |*/per/json/time* + +In the GeoJSON encoding of a record, the `time` member is a top level field. Since some popular GeoJSON tools only manipulate record properties encoded in the `properties` section of a GeoJSON record, implementations MAY duplicate the `time` member from the top level into the `properties` section in order to take advantage of these available tools. +|=== diff --git a/core/standard/recommendations/local-resources-catalogue/PER_additional-properties.adoc b/core/standard/recommendations/local-resources-catalog/PER_additional-properties.adoc similarity index 89% rename from core/standard/recommendations/local-resources-catalogue/PER_additional-properties.adoc rename to core/standard/recommendations/local-resources-catalog/PER_additional-properties.adoc index 74c7a863..bc41bdf6 100644 --- a/core/standard/recommendations/local-resources-catalogue/PER_additional-properties.adoc +++ b/core/standard/recommendations/local-resources-catalog/PER_additional-properties.adoc @@ -1,7 +1,7 @@ -[[per_collections_additional-properties]] +[[per_collection_additional-properties]] [width="90%",cols="2,6a"] |=== -^|*Permission {counter:per-id}* |*/per/collections/additional-properties* +^|*Permission {counter:per-id}* |*/per/collection/additional-properties* ^|A | <> contains a list of recommended additional properties that MAY be added to the information model of a local resource object to enhance the searchability of the resource offered at an OGC API endpoint. |=== diff --git a/core/standard/recommendations/local-resources-catalogue/PER_common-mark.adoc b/core/standard/recommendations/local-resources-catalog/PER_common-mark.adoc similarity index 65% rename from core/standard/recommendations/local-resources-catalogue/PER_common-mark.adoc rename to core/standard/recommendations/local-resources-catalog/PER_common-mark.adoc index 6df98d0e..d9b56d1c 100644 --- a/core/standard/recommendations/local-resources-catalogue/PER_common-mark.adoc +++ b/core/standard/recommendations/local-resources-catalog/PER_common-mark.adoc @@ -1,7 +1,7 @@ -[[per_collections_common-mark]] +[[per_collection_common-mark]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/per/collections/common-mark* +^|*Recommendation {counter:rec-id}* |*/per/collection/common-mark* For any `description` member in a local resources object, https://spec.commonmark.org/current/[CommonMark] MAY be used for a rich text representation. |=== diff --git a/core/standard/recommendations/local-resources-catalogue/REC_additional-query-parameters.adoc b/core/standard/recommendations/local-resources-catalog/REC_additional-query-parameters.adoc similarity index 94% rename from core/standard/recommendations/local-resources-catalogue/REC_additional-query-parameters.adoc rename to core/standard/recommendations/local-resources-catalog/REC_additional-query-parameters.adoc index 1e9b9717..02abac28 100644 --- a/core/standard/recommendations/local-resources-catalogue/REC_additional-query-parameters.adoc +++ b/core/standard/recommendations/local-resources-catalog/REC_additional-query-parameters.adoc @@ -1,4 +1,4 @@ -[[rec_local-resources-catalogue_additional-query-parameters]] +[[rec_local-resources-catalog_additional-query-parameters]] [width="90%",cols="2,6a"] |=== ^|*Recommendation {counter:rec-id}* |*/rec/record-api/additional-query-parameters* diff --git a/core/standard/recommendations/local-resources-catalogue/REC_local-resources-catalogue_additional-properties.adoc b/core/standard/recommendations/local-resources-catalog/REC_local-resources-catalogue_additional-properties.adoc similarity index 100% rename from core/standard/recommendations/local-resources-catalogue/REC_local-resources-catalogue_additional-properties.adoc rename to core/standard/recommendations/local-resources-catalog/REC_local-resources-catalogue_additional-properties.adoc diff --git a/core/standard/recommendations/local-resources-catalog/REC_param-q.adoc b/core/standard/recommendations/local-resources-catalog/REC_param-q.adoc new file mode 100644 index 00000000..197f20c9 --- /dev/null +++ b/core/standard/recommendations/local-resources-catalog/REC_param-q.adoc @@ -0,0 +1,10 @@ +[[rec_local-resources-catalog_param-q]] +[width="90%",cols="2,6a"] +|=== +^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalog/param-q* +^|A |The `q` operator SHOULD at least be applied to the following core properties: + +* title +* description +* keywords +|=== diff --git a/core/standard/recommendations/local-resources-catalogue/REC_param-type.adoc b/core/standard/recommendations/local-resources-catalog/REC_param-type.adoc similarity index 76% rename from core/standard/recommendations/local-resources-catalogue/REC_param-type.adoc rename to core/standard/recommendations/local-resources-catalog/REC_param-type.adoc index e87b329d..c2242487 100644 --- a/core/standard/recommendations/local-resources-catalogue/REC_param-type.adoc +++ b/core/standard/recommendations/local-resources-catalog/REC_param-type.adoc @@ -1,7 +1,7 @@ -[[rec_local-resources-catalogue_param-type]] +[[rec_local-resources-catalog_param-type]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalogue/param-type* +^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalog/param-type* The definition of the `type` parameter SHOULD be extended to enumerate the list of known resource types. |=== diff --git a/core/standard/recommendations/local-resources-catalogue/REC_property-extent.adoc b/core/standard/recommendations/local-resources-catalog/REC_property-extent.adoc similarity index 71% rename from core/standard/recommendations/local-resources-catalogue/REC_property-extent.adoc rename to core/standard/recommendations/local-resources-catalog/REC_property-extent.adoc index d260bfce..f24061a8 100644 --- a/core/standard/recommendations/local-resources-catalogue/REC_property-extent.adoc +++ b/core/standard/recommendations/local-resources-catalog/REC_property-extent.adoc @@ -1,6 +1,6 @@ -[[rec_local-resources-catalogue_property-extent-def]] +[[rec_local-resources-catalog_property-extent-def]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalogue/property-extent-def* +^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalog/property-extent-def* ^|A |The `extent` property SHOULD be present in the information model of the local resource object. |=== diff --git a/core/standard/recommendations/local-resources-catalogue/REC_property-links.adoc b/core/standard/recommendations/local-resources-catalog/REC_property-links.adoc similarity index 79% rename from core/standard/recommendations/local-resources-catalogue/REC_property-links.adoc rename to core/standard/recommendations/local-resources-catalog/REC_property-links.adoc index d8ce75ed..c608d31d 100644 --- a/core/standard/recommendations/local-resources-catalogue/REC_property-links.adoc +++ b/core/standard/recommendations/local-resources-catalog/REC_property-links.adoc @@ -1,6 +1,6 @@ -[rec_local-resources-catalogue_links]] +[rec_local-resources-catalog_links]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalogue/links* +^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalog/links* ^|A |The `links` property SHOULD be present in the information model of the local resource object. |=== diff --git a/core/standard/recommendations/local-resources-catalogue_cql2-filter/REC_json-encoding.adoc b/core/standard/recommendations/local-resources-catalog_filtering/REC_json-encoding.adoc similarity index 75% rename from core/standard/recommendations/local-resources-catalogue_cql2-filter/REC_json-encoding.adoc rename to core/standard/recommendations/local-resources-catalog_filtering/REC_json-encoding.adoc index b4acce24..96401700 100644 --- a/core/standard/recommendations/local-resources-catalogue_cql2-filter/REC_json-encoding.adoc +++ b/core/standard/recommendations/local-resources-catalog_filtering/REC_json-encoding.adoc @@ -1,7 +1,7 @@ -[[rec_local-resource-catalogue_cql2-filter_JSON-encoding]] +[[rec_local-resource-catalog_filtering_cql2-JSON-encoding]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalogue/cql2-filter/JSON-encoding* +^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalog/filtering/cql2-JSON-encoding* If a filter expression can be represented for its intended use as JSON, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/19-079.html#cql-json[CQL JSON] encoding. |=== diff --git a/core/standard/recommendations/local-resources-catalogue_cql2-filter/REC_text-encoding.adoc b/core/standard/recommendations/local-resources-catalog_filtering/REC_text-encoding.adoc similarity index 75% rename from core/standard/recommendations/local-resources-catalogue_cql2-filter/REC_text-encoding.adoc rename to core/standard/recommendations/local-resources-catalog_filtering/REC_text-encoding.adoc index d369eaab..b1d8fcb9 100644 --- a/core/standard/recommendations/local-resources-catalogue_cql2-filter/REC_text-encoding.adoc +++ b/core/standard/recommendations/local-resources-catalog_filtering/REC_text-encoding.adoc @@ -1,7 +1,7 @@ -[[rec_local-resource-catalogue_cql2-filter_text-encoding]] +[[rec_local-resource-catalog_filtering_cql2-text-encoding]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalogue/cql2-filter/text-encoding* +^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalog/filter/cql2-text-encoding* If a filter expression can be represented for its intended use as text, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/19-079.html#cql-text[CQL text] encoding. |=== diff --git a/core/standard/recommendations/local-resources-catalogue/REC_param-q.adoc b/core/standard/recommendations/local-resources-catalogue/REC_param-q.adoc deleted file mode 100644 index df51d205..00000000 --- a/core/standard/recommendations/local-resources-catalogue/REC_param-q.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[[rec_local-resources-catalogue_param-q]] -[width="90%",cols="2,6a"] -|=== -^|*Recommendation {counter:rec-id}* |*/rec/local-resources-catalogue/param-q* -^|A |The q operator SHOULD at least be applied to the following core queryables: - -* title -* description -* keywords - -|=== diff --git a/core/standard/recommendations/record-collection/PER_additional-queryables.adoc b/core/standard/recommendations/record-collection/PER_additional-properties.adoc similarity index 100% rename from core/standard/recommendations/record-collection/PER_additional-queryables.adoc rename to core/standard/recommendations/record-collection/PER_additional-properties.adoc diff --git a/core/standard/recommendations/record-core-query-parameters/REC_additional-query-parameters.adoc b/core/standard/recommendations/record-core-query-parameters/REC_additional-query-parameters.adoc new file mode 100644 index 00000000..b9a9e2ac --- /dev/null +++ b/core/standard/recommendations/record-core-query-parameters/REC_additional-query-parameters.adoc @@ -0,0 +1,30 @@ +[[rec_records-core-query-parameters_additional-query-parameters]] +[width="90%",cols="2,6a"] +|=== +^|*Recommendation {counter:rec-id}* |*/rec/records-core-query-parameters/additional-query-parameters* +^|A |If any additional property (see <>) is expected to be useful for applications using at a searchable catalog endpoint, a parameter with the name of that property SHOULD be supported. +^|B |If the parameter has a simple value (e.g. a string or integer) then it SHOULD have the following characteristics (using an OpenAPI Specification 3.0 fragment): + +[source,YAML] +---- +name: +in: query +required: false +style: form +explode: false +---- + +^|C |If the parameter is an array of simple values then it SHOULD have the following characteristics (using an OpenAPI Specification 3.0 fragment): + +[source,YAML] +---- +name: +in: query +required: false +schema: + type: array +explode: false +---- + +^|D |The `schema` property SHOULD be the same as the definition of the property from which the parameter is derived (see <>). +|=== diff --git a/core/standard/recommendations/record-core-query-parameters/REC_param-q.adoc b/core/standard/recommendations/record-core-query-parameters/REC_param-q.adoc new file mode 100644 index 00000000..46ad764d --- /dev/null +++ b/core/standard/recommendations/record-core-query-parameters/REC_param-q.adoc @@ -0,0 +1,10 @@ +[[rec_records-core-query-parameters_param-q]] +[width="90%",cols="2,6a"] +|=== +^|*Recommendation {counter:rec-id}* |*/rec/records-core-query-parameters/param-q* +The q operator SHOULD at least be applied to the following core properties: + +* title +* description +* keywords +|=== diff --git a/core/standard/recommendations/record-core-query-parameters/REC_query-param-type-definition.adoc b/core/standard/recommendations/record-core-query-parameters/REC_query-param-type-definition.adoc new file mode 100644 index 00000000..542c607c --- /dev/null +++ b/core/standard/recommendations/record-core-query-parameters/REC_query-param-type-definition.adoc @@ -0,0 +1,6 @@ +[[rec_records-core-query-parameters_param-type-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Recommendation {counter:rec-id}* |*/rec/records-core-query-parameters/param-type-definition* +^|A |The definition of the `type` parameter SHOULD be extended to enumerate the list of known record or resource types. +|=== diff --git a/core/standard/recommendations/record-core/PER_additional-queryables-record.adoc b/core/standard/recommendations/record-core/PER_additional-properties-record.adoc similarity index 60% rename from core/standard/recommendations/record-core/PER_additional-queryables-record.adoc rename to core/standard/recommendations/record-core/PER_additional-properties-record.adoc index f6e25b6f..74a9e079 100644 --- a/core/standard/recommendations/record-core/PER_additional-queryables-record.adoc +++ b/core/standard/recommendations/record-core/PER_additional-properties-record.adoc @@ -2,6 +2,6 @@ [width="90%",cols="2,6a"] |=== ^|*Permission {counter:per-id}* |*/per/record-core/additional-properties-record* -^|A |Each record in a response MAY contain zero or more of the optional properties listed in <> and <>. -^|B |Each record in a response MAY contain any number of additional properties not listed in <> and <>. The meaning of these additional properties is not specified in this document. +^|A |Each record in a response MAY contain zero or more of the optional properties listed in <> and <>. +^|B |Each record in a response MAY contain any number of additional properties not listed in <> and <>. The meaning of these additional properties is not specified in this document. |=== diff --git a/core/standard/recommendations/record-core/REC_record-lang.adoc b/core/standard/recommendations/record-core/REC_record-lang.adoc index eeaec00c..14170856 100644 --- a/core/standard/recommendations/record-core/REC_record-lang.adoc +++ b/core/standard/recommendations/record-core/REC_record-lang.adoc @@ -2,7 +2,7 @@ [width="90%",cols="2,6a"] |=== ^|*Recommendation {counter:rec-id}* |*/rec/record-core/langs* -^|A |The language used to express text values in a record SHOULD be specified using the <> property of the record. -^|B |The list of other languges in which a record may be retrieved SHOULD be specified in the record using the <> property. -^|C |If one or more language-specific links are included in the links section of a record (path: `links`) pointing to alternate language representations of this record, the language used as the `hreflang` value SHOULD be one of the languages listed as the value of the <> property of the record. +^|A |The language used to express text values in a record SHOULD be specified using the <> property of the record. +^|B |The list of other languges in which a record may be retrieved SHOULD be specified in the record using the <> property. +^|C |If one or more language-specific links are included in the links section of a record (path: `links`) pointing to alternate language representations of this record, the language used as the `hreflang` value SHOULD be one of the languages listed as the value of the <> property of the record. |=== diff --git a/core/standard/recommendations/record-core/REC_resource-langs.adoc b/core/standard/recommendations/record-core/REC_resource-langs.adoc index e11a8ffb..6b4b10be 100644 --- a/core/standard/recommendations/record-core/REC_resource-langs.adoc +++ b/core/standard/recommendations/record-core/REC_resource-langs.adoc @@ -3,5 +3,5 @@ |=== ^|*Recommendation {counter:rec-id}* |*/rec/record-core/resource-langs* -If there are one or more languages associated with the resource that a catalogue record describes, those languages SHOULD be listed in the record using the <> property. +If there are one or more languages associated with the resource that a catalog record describes, those languages SHOULD be listed in the record using the <> property. |=== diff --git a/core/standard/recommendations/record-core/REQ_links.adoc b/core/standard/recommendations/record-core/REQ_links.adoc new file mode 100644 index 00000000..fb61db73 --- /dev/null +++ b/core/standard/recommendations/record-core/REQ_links.adoc @@ -0,0 +1,7 @@ +[[rec_record-links]] +[width="90%",cols="2,6a"] +|=== +^|*Recommendation {counter:rec-id}* |*/rec/core/record-links* + +Each record SHOULD include one or more links (`rel="describes"`) pointing to the resource(s) that this record describes. +|=== diff --git a/core/standard/recommendations/record-filter/REC_json-encoding.adoc b/core/standard/recommendations/record-filter/REC_json-encoding.adoc index ff865e1d..1ffb5252 100644 --- a/core/standard/recommendations/record-filter/REC_json-encoding.adoc +++ b/core/standard/recommendations/record-filter/REC_json-encoding.adoc @@ -1,6 +1,6 @@ -[[rec_record-filter_JSON-encoding]] +[[rec_record-filtering_cql2-JSON-encoding]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/record-filter/JSON-encoding* +^|*Recommendation {counter:rec-id}* |*/rec/record-filtering/cql2-JSON-encoding* ^|A |If a filter expression can be represented for its intended use as JSON, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/19-079.html#cql-json[CQL JSON] encoding. |=== diff --git a/core/standard/recommendations/record-filter/REC_text-encoding.adoc b/core/standard/recommendations/record-filter/REC_text-encoding.adoc index 97e38573..aa62f891 100644 --- a/core/standard/recommendations/record-filter/REC_text-encoding.adoc +++ b/core/standard/recommendations/record-filter/REC_text-encoding.adoc @@ -1,6 +1,6 @@ -[[rec_record-filter_text-encoding]] +[[rec_record-filtering_cql2-text-encoding]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/record-filter/text-encoding* +^|*Recommendation {counter:rec-id}* |*/rec/record-filtering/cql2-text-encoding* ^|A |If a filter expression can be represented for its intended use as text, servers SHOULD consider supporting the https://docs.ogc.org/DRAFTS/19-079.html#cql-text[CQL text] encoding. |=== diff --git a/core/standard/recommendations/records-api/PER_conformance-classes.adoc b/core/standard/recommendations/records-api/PER_conformance-classes.adoc index 50ba742a..87cc236a 100644 --- a/core/standard/recommendations/records-api/PER_conformance-classes.adoc +++ b/core/standard/recommendations/records-api/PER_conformance-classes.adoc @@ -6,7 +6,7 @@ A conformance declaration MAY include one or more of the following conformance classes: * http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/sorting -* http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/cql +* http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/filtering * http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/json * http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/html * http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/autodiscovery diff --git a/core/standard/recommendations/records-api/REC_additional-query-parameters.adoc b/core/standard/recommendations/records-api/REC_additional-query-parameters.adoc deleted file mode 100644 index 83cb270c..00000000 --- a/core/standard/recommendations/records-api/REC_additional-query-parameters.adoc +++ /dev/null @@ -1,29 +0,0 @@ -[[rec_records-api_additional-query-parameters]] -[width="90%",cols="2,6a"] -|=== -^|*Recommendation {counter:rec-id}* |*/rec/record-api/additional-query-parameters* -^|A |If any <> is expected to be useful for applications using the service to filter records in a collection based on this property, a parameter with the name of the property SHOULD be supported. -^|B |If the parameter has a simple value (e.g. a string or integer) then it SHOULD have the following characteristics (using an OpenAPI Specification 3.0 fragment): - -[source,YAML] ----- -in: query -required: false -style: form -explode: false ----- - -^|C |If the parameter is an array of simple values then it SHOULD have the following characteristics (using an OpenAPI Specification 3.0 fragment): - -[source,YAML] ----- -name: q -in: query -required: false -schema: - type: array -explode: false ----- - -^|D |The `schema` property SHOULD be the same as the definition of the <> in the response schema. -|=== diff --git a/core/standard/recommendations/records-api/REC_html.adoc b/core/standard/recommendations/records-api/REC_html.adoc index 8607cc56..83b6c7b2 100644 --- a/core/standard/recommendations/records-api/REC_html.adoc +++ b/core/standard/recommendations/records-api/REC_html.adoc @@ -3,5 +3,5 @@ |=== ^|*Recommendation {counter:rec-id}* |*/rec/records-api/html* -To support browsing the catalogue and its records with a web browser and to enable search engines to crawl and index the catalogue, implementations SHOULD consider supporting an HTML encoding. +To support browsing the catalog and its records with a web browser and to enable search engines to crawl and index the catalog, implementations SHOULD consider supporting an HTML encoding. |=== diff --git a/core/standard/recommendations/records-api/REC_json.adoc b/core/standard/recommendations/records-api/REC_json.adoc index 056047e9..5cfe2303 100644 --- a/core/standard/recommendations/records-api/REC_json.adoc +++ b/core/standard/recommendations/records-api/REC_json.adoc @@ -3,6 +3,6 @@ |=== ^|*Recommendation {counter:rec-id}* |*/rec/records-api/json* -^|A |If the records can be represented for the intended use in GeoJSON, implementations SHOULD consider supporting GeoJSON as an encoding for records and catalogues (i.e. record collections). -^|B |If a catalogue (i.e. record collection) can be represented for the intended use in JSON, implementations SHOULD consider supporting JSON as an encoding for a catalogue (i.e. record collection). +^|A |If the records can be represented for the intended use in GeoJSON, implementations SHOULD consider supporting GeoJSON as an encoding for records and catalogs (i.e. record collections). +^|B |If a catalog (i.e. record collection) can be represented for the intended use in JSON, implementations SHOULD consider supporting JSON as an encoding for a catalog (i.e. record collection). |=== diff --git a/core/standard/recommendations/records-api/REC_param-q.adoc b/core/standard/recommendations/records-api/REC_param-q.adoc deleted file mode 100644 index f8cfed54..00000000 --- a/core/standard/recommendations/records-api/REC_param-q.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[[rec_records-api_param-q]] -[width="90%",cols="2,6a"] -|=== -^|*Recommendation {counter:rec-id}* |*/rec/records-api/param-q* -The q operator SHOULD at least be applied to the following core queryables: - -* title -* description -* keywords -|=== diff --git a/core/standard/recommendations/records-api/REC_query-param-type-definition.adoc b/core/standard/recommendations/records-api/REC_query-param-type-definition.adoc deleted file mode 100644 index a0f9cc9a..00000000 --- a/core/standard/recommendations/records-api/REC_query-param-type-definition.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[[rec_records-api_param-type-definition]] -[width="90%",cols="2,6a"] -|=== -^|*Recommendation {counter:rec-id}* |*/rec/records-api/param-type-definition* -^|A |The definition of the `type` parameter SHOULD be extended to enumerate the list of known record types. -|=== diff --git a/core/standard/recommendations/searchable-catalogue/PER_additional-properties.adoc b/core/standard/recommendations/searchable-catalog/PER_additional-properties.adoc similarity index 61% rename from core/standard/recommendations/searchable-catalogue/PER_additional-properties.adoc rename to core/standard/recommendations/searchable-catalog/PER_additional-properties.adoc index b4fb8081..3409359b 100644 --- a/core/standard/recommendations/searchable-catalogue/PER_additional-properties.adoc +++ b/core/standard/recommendations/searchable-catalog/PER_additional-properties.adoc @@ -3,5 +3,5 @@ |=== ^|*Permission {counter:per-id}* |*/per/core/additional-properties* -In addition to the properties listed in <> and <> servers may add any number of additional properties to the schema of a record. +In addition to the properties listed in <> and <> servers may add any number of additional properties to the schema of a record. |=== diff --git a/core/standard/recommendations/searchable-catalogue/PER_additional-requirements.adoc b/core/standard/recommendations/searchable-catalog/PER_additional-requirements.adoc similarity index 86% rename from core/standard/recommendations/searchable-catalogue/PER_additional-requirements.adoc rename to core/standard/recommendations/searchable-catalog/PER_additional-requirements.adoc index df5f998b..ee9f553c 100644 --- a/core/standard/recommendations/searchable-catalogue/PER_additional-requirements.adoc +++ b/core/standard/recommendations/searchable-catalog/PER_additional-requirements.adoc @@ -3,7 +3,7 @@ |=== ^|*Permission {counter:per-id}* |*/per/core/additional-conformance* 2+|Implementation of this conformance MAY, additionally, implement the following requirements: -^|A |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/cql-filter +^|A |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/filtering ^|B |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/sorting ^|C |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/json ^|D |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/html diff --git a/core/standard/recommendations/searchable-catalog_filtering/REQ_additional-queryables.adoc b/core/standard/recommendations/searchable-catalog_filtering/REQ_additional-queryables.adoc new file mode 100644 index 00000000..492f84f4 --- /dev/null +++ b/core/standard/recommendations/searchable-catalog_filtering/REQ_additional-queryables.adoc @@ -0,0 +1,8 @@ +[[per_searchable-catalog_additional-queryables]] +[width="90%",cols="2,6a"] +|=== +^|*Permission {counter:per-id}* |*/per/core/additional-conformance* +2+|The list of queryables MAY also include: +^|A |zero or more of the optional properties listed in <> and <>, +^|B |any number of additional properties that are part of the record but are not listed in <> and <>. +|=== diff --git a/core/standard/recommendations/searchable-catalogue_cql2-filter/REQ_additional-queryables.adoc b/core/standard/recommendations/searchable-catalogue_cql2-filter/REQ_additional-queryables.adoc deleted file mode 100644 index ad08bd6e..00000000 --- a/core/standard/recommendations/searchable-catalogue_cql2-filter/REQ_additional-queryables.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[per_searchable-catalogue_additional-queryables]] -[width="90%",cols="2,6a"] -|=== -^|*Permission {counter:per-id}* |*/per/core/additional-conformance* -2+|The list of queryables MAY also include: -^|A |zero or more of the optional queryables listed in <> and <>, -^|B |any number of additional queryables that are part of the record but are not listed in <> and <>. -|=== diff --git a/core/standard/requirements/autodiscovery/REQ_autodiscovery_link.adoc b/core/standard/requirements/autodiscovery/REQ_autodiscovery_link.adoc index 43c542ab..1753df04 100644 --- a/core/standard/requirements/autodiscovery/REQ_autodiscovery_link.adoc +++ b/core/standard/requirements/autodiscovery/REQ_autodiscovery_link.adoc @@ -3,9 +3,9 @@ |=== ^|*Requirement {counter:req-id}* |*/req/autodiscovery/link* -^|A |A web page SHALL include a link that points to a catalogue associated with that page. -^|B |The link SHALL include a `rel` attribute with the value `http://www.opengis.net/def/rel/ogc/1.0/catalogue`. +^|A |A web page SHALL include a link that points to a catalog associated with that page. +^|B |The link SHALL include a `rel` attribute with the value `http://www.opengis.net/def/rel/ogc/1.0/catalog`. ^|C |The link SHALL include a `type` attribute. -^|D |The value of the `type` attribute SHALL indicate the media type of the catalogue resource (see: <>, <>. -^|E |The link SHALL include a `href` attribute whose value is the URI of the catalogue. +^|D |The value of the `type` attribute SHALL indicate the media type of the catalog resource (see: <>, <>. +^|E |The link SHALL include a `href` attribute whose value is the URI of the catalog. |=== diff --git a/core/standard/requirements/crawlable-catalogue/REQ_collections.adoc b/core/standard/requirements/crawlable-catalog/OLD/REQ_collections.adoc similarity index 56% rename from core/standard/requirements/crawlable-catalogue/REQ_collections.adoc rename to core/standard/requirements/crawlable-catalog/OLD/REQ_collections.adoc index 9463f9a2..889a3af9 100644 --- a/core/standard/requirements/crawlable-catalogue/REQ_collections.adoc +++ b/core/standard/requirements/crawlable-catalog/OLD/REQ_collections.adoc @@ -1,7 +1,7 @@ -[[req_crawlable-catalogue_collections]] +[[req_crawlable-catalog_collections]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/crawlable-catalogue/collections* +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/collections* A _collections object_ SHALL contain all the mandatory properties listed in <>. |=== diff --git a/core/standard/requirements/crawlable-catalog/REQ_catalog-links.adoc b/core/standard/requirements/crawlable-catalog/REQ_catalog-links.adoc new file mode 100644 index 00000000..e69fdf4b --- /dev/null +++ b/core/standard/requirements/crawlable-catalog/REQ_catalog-links.adoc @@ -0,0 +1,13 @@ +[[req_crawlable-catalog_catalog-links]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/catalog-links* + +^|A |A catalog's `links` section SHALL include a link (`rel=self`) that points to itself. +^|B |A catalog's `links` section SHALL include one or more typed links (`rel=alternate`) that point to each alternate representation of this catalog. +^|B |A catalog's `links` section SHALL include one link (`rel=item`) pointing to each record of the catalog. +|=== + +NOTE: The term "typed link" means a link that specifies a value for the `type` attribute. + + diff --git a/core/standard/requirements/crawlable-catalog/REQ_catalog-location.adoc b/core/standard/requirements/crawlable-catalog/REQ_catalog-location.adoc new file mode 100644 index 00000000..68ec0b4d --- /dev/null +++ b/core/standard/requirements/crawlable-catalog/REQ_catalog-location.adoc @@ -0,0 +1,7 @@ +[[req_crawlable-catalog_catalog-location]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/catalog-location* + +A catalog SHALL be placed in a web-accessible location. +|=== diff --git a/core/standard/requirements/crawlable-catalog/REQ_catalog.adoc b/core/standard/requirements/crawlable-catalog/REQ_catalog.adoc new file mode 100644 index 00000000..d7e43487 --- /dev/null +++ b/core/standard/requirements/crawlable-catalog/REQ_catalog.adoc @@ -0,0 +1,7 @@ +[[req_crawlable-catalog_catalog]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/catalog* + +A collection of related records, called a _catalog_, SHALL be described by a <>. +|=== diff --git a/core/standard/requirements/crawlable-catalog/REQ_collection-links.adoc b/core/standard/requirements/crawlable-catalog/REQ_collection-links.adoc new file mode 100644 index 00000000..436fbb02 --- /dev/null +++ b/core/standard/requirements/crawlable-catalog/REQ_collection-links.adoc @@ -0,0 +1,12 @@ +[[req_crawlable-catalogue_collection-links]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/collection-links* + +^|A |A collection SHALL include a link (`rel=self`) that points to itself. +^|B |A collection SHALL include a link (`rel=root`) that points to its root collection. +^|C |If this collection object is the root then it SHALL point to itself. +^|C |A collection SHALL include one typed link (`rel=alternate`) for each alternative representation of itself. +|=== + +NOTE: The term "typed link" means a link that specifies a value for the `type` attribute diff --git a/core/standard/requirements/crawlable-catalog/REQ_collection-location.adoc b/core/standard/requirements/crawlable-catalog/REQ_collection-location.adoc new file mode 100644 index 00000000..b097f1f5 --- /dev/null +++ b/core/standard/requirements/crawlable-catalog/REQ_collection-location.adoc @@ -0,0 +1,7 @@ +[[req_crawlable-catalog_collection-location]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/collection-location* + +A collection SHALL be placed in a web-accessible location. +|=== diff --git a/core/standard/requirements/crawlable-catalog/REQ_collection.adoc b/core/standard/requirements/crawlable-catalog/REQ_collection.adoc new file mode 100644 index 00000000..587b5062 --- /dev/null +++ b/core/standard/requirements/crawlable-catalog/REQ_collection.adoc @@ -0,0 +1,7 @@ +[[req_crawlable-catalog_collection]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/collection* + +A _collection_ SHALL include all the mandatory properties listed in <>. +|=== diff --git a/core/standard/requirements/crawlable-catalog/REQ_itemType.adoc b/core/standard/requirements/crawlable-catalog/REQ_itemType.adoc new file mode 100644 index 00000000..4664554b --- /dev/null +++ b/core/standard/requirements/crawlable-catalog/REQ_itemType.adoc @@ -0,0 +1,11 @@ +[[req_crawlable-catalog_itemType]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/itemType* + +^|A |The _itemType_ member of the _collection_ SHALL be an array whose elements enumerate the types of resources referenced by this collection. +^|B |The value `record` SHALL be used to indicate that this collection includes references to <>. +^|C |The value `catalog` SHALL be used to indicate that this collection includes references to <>. +^|D |The value `collection` SHALL be used to indicate that this collection includes references to other <>. +^|E |The value `other` SHALL be used to indicate that this collection includes references to other types of resources (i.e. not `record`, `catalog` or `collection`). +|=== diff --git a/core/standard/requirements/crawlable-catalog/REQ_record-file-location.adoc b/core/standard/requirements/crawlable-catalog/REQ_record-file-location.adoc new file mode 100644 index 00000000..89fa99dd --- /dev/null +++ b/core/standard/requirements/crawlable-catalog/REQ_record-file-location.adoc @@ -0,0 +1,7 @@ +[[req_crawlable-catalog_record-file-location]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/record-file-location* + +The record SHALL be placed in a web-accessible location. +|=== diff --git a/core/standard/requirements/crawlable-catalogue/REQ_record-links.adoc b/core/standard/requirements/crawlable-catalog/REQ_record-links.adoc similarity index 69% rename from core/standard/requirements/crawlable-catalogue/REQ_record-links.adoc rename to core/standard/requirements/crawlable-catalog/REQ_record-links.adoc index 914bf983..a34d52b8 100644 --- a/core/standard/requirements/crawlable-catalogue/REQ_record-links.adoc +++ b/core/standard/requirements/crawlable-catalog/REQ_record-links.adoc @@ -1,11 +1,11 @@ -[[req_crawlable-catalogue_record-links]] +[[req_crawlable-catalog_record-links]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/crawlable-catalogue/record-links* +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/record-links* ^|A |The record SHALL include a link (`rel=self`) that points to itself. ^|B |The record SHALL include one typed link (`rel=alternate`) for each alternative representation of this record. -^|C |The record SHALL include one link (`rel=collection`) that points to the collection to which this record belongs. +^|C |The record SHALL include one link (`rel=collection`) that points to the catalog to which this record belongs. |=== NOTE: The term "typed link" means a link that specifies a value for the `type` attribute. diff --git a/core/standard/requirements/crawlable-catalogue/REQ_record.adoc b/core/standard/requirements/crawlable-catalog/REQ_record.adoc similarity index 54% rename from core/standard/requirements/crawlable-catalogue/REQ_record.adoc rename to core/standard/requirements/crawlable-catalog/REQ_record.adoc index cdd852c5..0dad0ca4 100644 --- a/core/standard/requirements/crawlable-catalogue/REQ_record.adoc +++ b/core/standard/requirements/crawlable-catalog/REQ_record.adoc @@ -1,7 +1,7 @@ -[[req_crawlable-catalogue_record]] +[[req_crawlable-catalog_record]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/crawlable-catalogue/record* +^|*Requirement {counter:req-id}* |*/req/crawlable-catalog/record* A <> SHALL be created for each resource to be made discoverable. |=== diff --git a/core/standard/requirements/crawlable-catalogue/REQ_collection-links.adoc b/core/standard/requirements/crawlable-catalogue/REQ_collection-links.adoc deleted file mode 100644 index 628ae85b..00000000 --- a/core/standard/requirements/crawlable-catalogue/REQ_collection-links.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[[req_crawlable-catalogue_collection-links]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/crawlable-catalogue/record-links* - -^|A |A catalogue's `links` section SHALL include a link (`rel=self`) that points to itself. -^|B |A catalogue's `links` section SHALL include one or more typed links (`rel=alternate`) that point to each alternate representation of the collection object describing the catalogue. -^|B |A catalogue's `links` section SHALL include one link (`rel=item`) pointing to each record of the catalogue. -|=== - -NOTE: The term "typed link" means a link that specifies a value for the `type` attribute. - - diff --git a/core/standard/requirements/crawlable-catalogue/REQ_collection-location.adoc b/core/standard/requirements/crawlable-catalogue/REQ_collection-location.adoc deleted file mode 100644 index 5288b6c6..00000000 --- a/core/standard/requirements/crawlable-catalogue/REQ_collection-location.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_crawlable-catalogue_collection-location]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/crawlable-catalogue/collection-location* - -The collection object describing a catalogue SHALL be placed in a web-accessible location. -|=== diff --git a/core/standard/requirements/crawlable-catalogue/REQ_collection.adoc b/core/standard/requirements/crawlable-catalogue/REQ_collection.adoc deleted file mode 100644 index 64086e1b..00000000 --- a/core/standard/requirements/crawlable-catalogue/REQ_collection.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_crawlable-catalogue_collection]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/crawlable-catalogue/collection* - -A collection of related records, called a catalogue, SHALL be described by a <>. -|=== diff --git a/core/standard/requirements/crawlable-catalogue/REQ_collections-links.adoc b/core/standard/requirements/crawlable-catalogue/REQ_collections-links.adoc deleted file mode 100644 index adfb0eca..00000000 --- a/core/standard/requirements/crawlable-catalogue/REQ_collections-links.adoc +++ /dev/null @@ -1,11 +0,0 @@ -[[req_crawlable-collections-links]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/crawlable-catalogue/collections-links* - -^|A |A collections object SHALL include a link (`rel=self`) that points to itself. -^|B |A collections object SHALL include a link (`rel=root`) that points to its root collections object. If this collections object is the root then it SHALL point to itself. -^|C |A collections object SHALL include one typed link (`rel=alternate`) for each alternative representation of itself. -|=== - -NOTE: The term "typed link" means a link that specifies a value for the `type` attribute diff --git a/core/standard/requirements/crawlable-catalogue/REQ_record-file-location.adoc b/core/standard/requirements/crawlable-catalogue/REQ_record-file-location.adoc deleted file mode 100644 index 66278030..00000000 --- a/core/standard/requirements/crawlable-catalogue/REQ_record-file-location.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_crawlable-catalogue_record-file-location]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/crawlable-catalogue/record-file-location* - -The record SHALL be placed in a web-accessible location. -|=== diff --git a/core/standard/requirements/geojson/REQ_conformance.adoc b/core/standard/requirements/geojson/REQ_conformance.adoc deleted file mode 100644 index 0aa8ff78..00000000 --- a/core/standard/requirements/geojson/REQ_conformance.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_geojson_conformance]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/geojson/conformance* -2+|The list of Conformance Classes advertised by the API SHALL include: -^|A |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/geojson -|=== diff --git a/core/standard/requirements/geojson/REQ_api-common.adoc b/core/standard/requirements/json/REQ_api-common.adoc similarity index 74% rename from core/standard/requirements/geojson/REQ_api-common.adoc rename to core/standard/requirements/json/REQ_api-common.adoc index 0f8d414c..b74a81c5 100644 --- a/core/standard/requirements/geojson/REQ_api-common.adoc +++ b/core/standard/requirements/json/REQ_api-common.adoc @@ -1,7 +1,7 @@ -[[req_geojson_api-common]] +[[req_json_api-common]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/geojson/api-common* +^|*Requirement {counter:req-id}* |*/req/json/api-common* ^|**Extends** |/req/core/api-common 2+|The API SHALL demonstrate conformance with the following Requirements Class of the OGC API - Common version 1.0 Standard. ^|A |http://www.opengis.net/spec/ogcapi_common-1/1.0/req/json diff --git a/core/standard/requirements/json/REQ_collection-content.adoc b/core/standard/requirements/json/REQ_collection-content.adoc new file mode 100644 index 00000000..21633593 --- /dev/null +++ b/core/standard/requirements/json/REQ_collection-content.adoc @@ -0,0 +1,7 @@ +[[req_json_collection-content]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/json/collection-content* + +The schema of all responses with the media type `application/ogc-catalog+json` SHALL validate against the OpenAPI 3.0 schema document `catalog.yaml`. +|=== diff --git a/core/standard/requirements/json/REQ_collection-response.adoc b/core/standard/requirements/json/REQ_collection-response.adoc new file mode 100644 index 00000000..c0d6cd59 --- /dev/null +++ b/core/standard/requirements/json/REQ_collection-response.adoc @@ -0,0 +1,8 @@ +[[req_json_collection-response]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/json/collection-response* +^|A |200-responses of the server SHALL support the following media type: + +* `application/ogc-catalog+json` for catalog or record collection resources. +|=== diff --git a/core/standard/requirements/json/REQ_conformance.adoc b/core/standard/requirements/json/REQ_conformance.adoc new file mode 100644 index 00000000..e7df5886 --- /dev/null +++ b/core/standard/requirements/json/REQ_conformance.adoc @@ -0,0 +1,7 @@ +[[req_json_conformance]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/json/conformance* +2+|The list of Conformance Classes advertised by the API SHALL include: +^|A |http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/json +|=== diff --git a/core/standard/requirements/geojson/REQ_content.adoc b/core/standard/requirements/json/REQ_record-content.adoc similarity index 88% rename from core/standard/requirements/geojson/REQ_content.adoc rename to core/standard/requirements/json/REQ_record-content.adoc index 0d78ff2f..3c9c06d7 100644 --- a/core/standard/requirements/geojson/REQ_content.adoc +++ b/core/standard/requirements/json/REQ_record-content.adoc @@ -1,7 +1,7 @@ -[[req_geojson_content]] +[[req_json_record-content]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/geojson/content* +^|*Requirement {counter:req-id}* |*/req/json/record-content* ^|A |Every 200-response with the media type `application/geo+json` SHALL be * a link:https://tools.ietf.org/html/rfc7946#section-3.3[GeoJSON FeatureCollection Object] for records, and diff --git a/core/standard/requirements/geojson/REQ_response.adoc b/core/standard/requirements/json/REQ_record-response.adoc similarity index 88% rename from core/standard/requirements/geojson/REQ_response.adoc rename to core/standard/requirements/json/REQ_record-response.adoc index e472ca6c..3b0f8078 100644 --- a/core/standard/requirements/geojson/REQ_response.adoc +++ b/core/standard/requirements/json/REQ_record-response.adoc @@ -1,7 +1,7 @@ -[[req_geojson-response]] +[[req_json-record-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/geojson/response* +^|*Requirement {counter:req-id}* |*/req/json/record-response* ^|A |200-responses of the server SHALL support the following media type: * `application/geo+json` for resources that include record content. diff --git a/core/standard/requirements/local-resources-catalogue/REQ_param-bbox-def.adoc b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-bbox-def.adoc similarity index 76% rename from core/standard/requirements/local-resources-catalogue/REQ_param-bbox-def.adoc rename to core/standard/requirements/local-resources-catalog/OLD/REQ_param-bbox-def.adoc index b54fea72..c37228ec 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_param-bbox-def.adoc +++ b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-bbox-def.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_param-bbox-def]] +[[req_local-resources-catalog_param-bbox-def]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/param-bbox-def* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/param-bbox-def* ^|A |Implementations SHALL support the `bbox` query parameter for the HTTP GET operation at the local resources endpoint. ^|B |The characteristics of the `bbox` parameter shall be as defined by requirement http://docs.ogc.org/is/17-069r3/17-069r3.html#_parameter_bbox[`req/core/fc-bbox-definition`] of the http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] standard. diff --git a/core/standard/requirements/local-resources-catalogue/REQ_param-bbox-response.adoc b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-bbox-response.adoc similarity index 81% rename from core/standard/requirements/local-resources-catalogue/REQ_param-bbox-response.adoc rename to core/standard/requirements/local-resources-catalog/OLD/REQ_param-bbox-response.adoc index 5a3cf0da..6355409c 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_param-bbox-response.adoc +++ b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-bbox-response.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_param-bbox-response]] +[[req_local-resources-catalog_param-bbox-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/param-bbox-response* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/param-bbox-response* ^|A |If the `bbox` parameter is provided, only resources that have a spatial geometry that intersects the bounding box SHALL be part of the result set. ^|B |If a resource has multiple spatial geometry properties, it is the decision of the server whether only a single spatial geometry property is used to determine the extent or all relevant geometries. diff --git a/core/standard/requirements/local-resources-catalogue/REQ_param-datetime-def.adoc b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-datetime-def.adoc similarity index 76% rename from core/standard/requirements/local-resources-catalogue/REQ_param-datetime-def.adoc rename to core/standard/requirements/local-resources-catalog/OLD/REQ_param-datetime-def.adoc index b140812c..d926c36c 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_param-datetime-def.adoc +++ b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-datetime-def.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_param-datetime-def]] +[[req_local-resources-catalog_param-datetime-def]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/param-datetime-def* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/param-datetime-def* ^|A |Implementations SHALL support the `datetime` query parameter for the HTTP GET operation at the local resources endpoint. ^|B |The characteristics of the `datetime` parameter SHALL be as defined by requirement http://docs.ogc.org/is/17-069r3/17-069r3.html#_parameter_datetime[`req/core/fc-datetime-definition`] of the http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] standard. diff --git a/core/standard/requirements/local-resources-catalogue/REQ_param-datetime-response.adoc b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-datetime-response.adoc similarity index 90% rename from core/standard/requirements/local-resources-catalogue/REQ_param-datetime-response.adoc rename to core/standard/requirements/local-resources-catalog/OLD/REQ_param-datetime-response.adoc index e7be53d9..a7a98787 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_param-datetime-response.adoc +++ b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-datetime-response.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_datetime-response]] +[[req_local-resources-catalog_datetime-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/datetime-response* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/datetime-response* ^|A |Only resources that have a temporal geometry that intersects the temporal information in the `datetime` parameter SHALL be part of the result set, if the parameter is provided. ^|B |If a resource has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties. diff --git a/core/standard/requirements/local-resources-catalogue/REQ_param-limit-def.adoc b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-limit-def.adoc similarity index 76% rename from core/standard/requirements/local-resources-catalogue/REQ_param-limit-def.adoc rename to core/standard/requirements/local-resources-catalog/OLD/REQ_param-limit-def.adoc index 84b6a2ba..fac30052 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_param-limit-def.adoc +++ b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-limit-def.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_param-limit-def]] +[[req_local-resources-catalog_param-limit-def]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/param-limit-def* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/param-limit-def* ^|A |Implementations SHALL support the `limit` query parameter for the HTTP GET operation at the local resources endpoint. ^|B |The characteristics of the `limit` parameter SHALL be as defined by requirements http://docs.ogc.org/is/17-069r3/17-069r3.html#_parameter_limit[`req/core/fc-limit-definition`] of the http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] standard. diff --git a/core/standard/requirements/local-resources-catalogue/REQ_param-limit-response.adoc b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-limit-response.adoc similarity index 83% rename from core/standard/requirements/local-resources-catalogue/REQ_param-limit-response.adoc rename to core/standard/requirements/local-resources-catalog/OLD/REQ_param-limit-response.adoc index 8ece9b04..66ce591a 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_param-limit-response.adoc +++ b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-limit-response.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_param-limit-response]] +[[req_local-resources-catalog_param-limit-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/param-limit-response* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/param-limit-response* ^|A |The response SHALL not contain more resources from the local resources endpoint than specified by the optional `limit` parameter. ^|B |If the API definition specifies a maximum value for the `limit` parameter, the response SHALL not contain more resources from the local resources endpoint than this maximum value. diff --git a/core/standard/requirements/local-resources-catalogue/REQ_param-q-def.adoc b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-q-def.adoc similarity index 83% rename from core/standard/requirements/local-resources-catalogue/REQ_param-q-def.adoc rename to core/standard/requirements/local-resources-catalog/OLD/REQ_param-q-def.adoc index 75e4ffb8..61a1b15b 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_param-q-def.adoc +++ b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-q-def.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_param-q-def]] +[[req_local-resources-catalog_param-q-def]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/param-q-def* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/param-q-def* ^|A |An implementation SHALL support the Text Search (`q`) parameter for the HTTP GET operation at the local resources endpoint. ^|B |The `q` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): diff --git a/core/standard/requirements/local-resources-catalogue/REQ_param-q-response.adoc b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-q-response.adoc similarity index 60% rename from core/standard/requirements/local-resources-catalogue/REQ_param-q-response.adoc rename to core/standard/requirements/local-resources-catalog/OLD/REQ_param-q-response.adoc index f3796f1d..34089a49 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_param-q-response.adoc +++ b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-q-response.adoc @@ -1,6 +1,6 @@ -[[req_local-resources-catalogue_param-q-response]] +[[req_local-resources-catalog_param-q-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/param-q-response* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/param-q-response* ^|A |If the `q` parameter is provided by the client, only local resources whose text fields contains one or more of the specified search terms SHALL be in the result set. |=== diff --git a/core/standard/requirements/local-resources-catalogue/REQ_param-type-def.adoc b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-type-def.adoc similarity index 75% rename from core/standard/requirements/local-resources-catalogue/REQ_param-type-def.adoc rename to core/standard/requirements/local-resources-catalog/OLD/REQ_param-type-def.adoc index c62093b5..f447cb8e 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_param-type-def.adoc +++ b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-type-def.adoc @@ -1,7 +1,7 @@ -[[req_local-resource-catalogue_param-type-def]] +[[req_local-resource-catalog_param-type-def]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/param-type-definition* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/param-type-definition* ^|A |An implementation SHALL support the search by Type (`type`) parameter for the HTTP GET operation at the local resources endpoint. ^|B |The `type` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): diff --git a/core/standard/requirements/local-resources-catalogue/REQ_param-type-response.adoc b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-type-response.adoc similarity index 65% rename from core/standard/requirements/local-resources-catalogue/REQ_param-type-response.adoc rename to core/standard/requirements/local-resources-catalog/OLD/REQ_param-type-response.adoc index 87bfaabf..e604d004 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_param-type-response.adoc +++ b/core/standard/requirements/local-resources-catalog/OLD/REQ_param-type-response.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_param-type-response]] +[[req_local-resources-catalog_param-type-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/param-type-response* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/param-type-response* If the `type` parameter is provided by the client, only resources from the local resources endpoint whose type, as indicated by the value of the `type` parameter, is equal to one of the listed values SHALL be in the result set. |=== diff --git a/core/standard/requirements/local-resources-catalogue/REQ_property-created.adoc b/core/standard/requirements/local-resources-catalog/REQ_property-created.adoc similarity index 76% rename from core/standard/requirements/local-resources-catalogue/REQ_property-created.adoc rename to core/standard/requirements/local-resources-catalog/REQ_property-created.adoc index a12ed343..c9d55df2 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_property-created.adoc +++ b/core/standard/requirements/local-resources-catalog/REQ_property-created.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_created]] +[[req_local-resources-catalog_created]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/created* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/created* ^|A |The `created` property SHALL be present in the information model of the local resource object. ^|B |The value of the `created` property SHALL conform to the date-time production of https://tools.ietf.org/html/rfc3339#section-5.6[RFC 3339]. diff --git a/core/standard/requirements/local-resources-catalog/REQ_property-description.adoc b/core/standard/requirements/local-resources-catalog/REQ_property-description.adoc new file mode 100644 index 00000000..501f3ea9 --- /dev/null +++ b/core/standard/requirements/local-resources-catalog/REQ_property-description.adoc @@ -0,0 +1,8 @@ +[[req_local-resources-catalog_property-description-def]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/property-description-def* + +The `description` property SHALL be present in the information model of the local resource object. +|=== + diff --git a/core/standard/requirements/local-resources-catalogue/REQ_property-keywords.adoc b/core/standard/requirements/local-resources-catalog/REQ_property-keywords.adoc similarity index 68% rename from core/standard/requirements/local-resources-catalogue/REQ_property-keywords.adoc rename to core/standard/requirements/local-resources-catalog/REQ_property-keywords.adoc index fcc178a7..49d2291a 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_property-keywords.adoc +++ b/core/standard/requirements/local-resources-catalog/REQ_property-keywords.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_keywords]] +[[req_local-resources-catalog_keywords]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/keywords* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/keywords* ^|A |The `keywords` property SHALL be present in the information model of the local resource object. ^|B |The value of the `keywords` property SHALL be a list of free-form keywords or tags associated with the local resource. diff --git a/core/standard/requirements/local-resources-catalog/REQ_property-title.adoc b/core/standard/requirements/local-resources-catalog/REQ_property-title.adoc new file mode 100644 index 00000000..4b66bf27 --- /dev/null +++ b/core/standard/requirements/local-resources-catalog/REQ_property-title.adoc @@ -0,0 +1,7 @@ +[[req_local-resources-catalog_property-title-def]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/property-title-def* + +The `title` property SHALL be present in the information model of the local resource object. +|=== diff --git a/core/standard/requirements/local-resources-catalogue/REQ_property-type.adoc b/core/standard/requirements/local-resources-catalog/REQ_property-type.adoc similarity index 78% rename from core/standard/requirements/local-resources-catalogue/REQ_property-type.adoc rename to core/standard/requirements/local-resources-catalog/REQ_property-type.adoc index 51f03817..7a0d0aea 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_property-type.adoc +++ b/core/standard/requirements/local-resources-catalog/REQ_property-type.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_type]] +[[req_local-resources-catalog_type]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/type* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/type* ^|A |The `type` property SHALL be present in the information model of the local resource object. ^|B |The value of the `type` property SHALL be the same as the value of the `itemType` property if the latter is present. diff --git a/core/standard/requirements/local-resources-catalogue/REQ_property-updated.adoc b/core/standard/requirements/local-resources-catalog/REQ_property-updated.adoc similarity index 77% rename from core/standard/requirements/local-resources-catalogue/REQ_property-updated.adoc rename to core/standard/requirements/local-resources-catalog/REQ_property-updated.adoc index 3efdf39f..1c696cba 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_property-updated.adoc +++ b/core/standard/requirements/local-resources-catalog/REQ_property-updated.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_updated]] +[[req_local-resources-catalog_updated]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/updated* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/updated* ^|A |The `updated` property SHALL be present in the information model of the local resource object. ^|B |The value of the `updated` property SHALL conform to the date-time production of https://tools.ietf.org/html/rfc3339#section-5.6[RFC 3339]. diff --git a/core/standard/requirements/local-resources-catalog/REQ_query-parameters.adoc b/core/standard/requirements/local-resources-catalog/REQ_query-parameters.adoc new file mode 100644 index 00000000..bcc6562c --- /dev/null +++ b/core/standard/requirements/local-resources-catalog/REQ_query-parameters.adoc @@ -0,0 +1,7 @@ +[[req_local-resource-catalog_query-parameters]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/query-parameters* + +Implementations of this conformance class SHALL, at the local resources endpoint, implement the parameters defined by the <> building block. +|=== diff --git a/core/standard/requirements/local-resources-catalogue/REQ_response.adoc b/core/standard/requirements/local-resources-catalog/REQ_response.adoc similarity index 52% rename from core/standard/requirements/local-resources-catalogue/REQ_response.adoc rename to core/standard/requirements/local-resources-catalog/REQ_response.adoc index 54d2c4c5..66a8bbac 100644 --- a/core/standard/requirements/local-resources-catalogue/REQ_response.adoc +++ b/core/standard/requirements/local-resources-catalog/REQ_response.adoc @@ -1,8 +1,8 @@ -[[req_local-resources-catalogue_response]] +[[req_local-resources-catalog_response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/param-type-response* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/response* ^|A |A successful execution of the operation SHALL be reported as a response with a HTTP status code `200`. ^|B |The response SHALL conform to the requirements of the local resource being extended. -^|C |The response SHALL only include local resources selected by the request (e.g. only the selected collections from the `/collections` endoint). +^|C |The response SHALL only include local resources selected by the request (e.g. only collections that satisfy the <> applied to the `/collections` endoint). |=== diff --git a/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-crs-param.adoc b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-crs-param.adoc similarity index 50% rename from core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-crs-param.adoc rename to core/standard/requirements/local-resources-catalog_filtering/REQ_filter-crs-param.adoc index 78759e5f..7485eeef 100644 --- a/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-crs-param.adoc +++ b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-crs-param.adoc @@ -1,8 +1,8 @@ -[[req_local-resources-catalogue_cql2-filter_filter-crs-param]] +[[req_local-resources-catalog_filtering_filter-crs-param]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/cql2-filter/filter-crs-param* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/filtering/filter-crs-param* ^|Condition |Server implements <> -Implementations of this conformance class SHALL, at the local resources endpoint and for the HTTP GET operation, support the `filter-crs` parameter as defined in https://docs.ogc.org/DRAFTS/19-079.html#filter-filter-crs[Parameter filter-crs]. +Implementations of this conformance class SHALL, at the local resources endpoint and for the HTTP GET operation, support the `filter-crs` parameter as defined by the <>. |=== diff --git a/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-lang-param.adoc b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-lang-param.adoc new file mode 100644 index 00000000..200bf815 --- /dev/null +++ b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-lang-param.adoc @@ -0,0 +1,7 @@ +[[req_local-resources-catalog_filtering_filter-lang-param]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/filtering/filter-lang-param* + +Implementation of the conformance class SHALL, at the local resource endpoint and for the HTTP GET operation, support the `filter-lang` parameter as defined as defined by the <> building block. +|=== diff --git a/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-param.adoc b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-param.adoc new file mode 100644 index 00000000..7b1df757 --- /dev/null +++ b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-param.adoc @@ -0,0 +1,7 @@ +[[req_local-resources-catalog_filtering_filter-param]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/features-filter/filtering/filter-param* + +Implementations SHALL, at the local resources endpoint and for the HTTP GET operation, support the `filter` parameter as defined by the <> building block. +|=== diff --git a/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-response.adoc b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-response.adoc new file mode 100644 index 00000000..6c8f5f03 --- /dev/null +++ b/core/standard/requirements/local-resources-catalog_filtering/REQ_filter-response.adoc @@ -0,0 +1,10 @@ +[[req_local-resources-catalog_filtering_filter-response]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/filtering/filter-response* + +^|A |A filter expression SHALL be evaluated for each local resources object at the local resources endpoint. +^|B |All other filtering parameters specified (i.e. zero or more of <>, <>, <>, <>, <> and any <>) SHALL be evaluated for each local resources object at the local resources endpoint. +^|C |If the filter expression AND all other specified filtering parameters (i.e. zero or more of <>, <>, <>, <>, <> and any <>) evaluate to `TRUE` then the local resources object SHALL be included in the result. +^|D |If the filter expression OR any other specified filtering parameter (i.e. zero or more of <>, <>, <>, <>, <> and any <>) evaluates to `FALSE` then the local resources object SHALL be excluded from the result. +|=== diff --git a/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_queryables-link.adoc b/core/standard/requirements/local-resources-catalog_filtering/REQ_queryables-link.adoc similarity index 71% rename from core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_queryables-link.adoc rename to core/standard/requirements/local-resources-catalog_filtering/REQ_queryables-link.adoc index c97b1cf1..47b708cc 100644 --- a/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_queryables-link.adoc +++ b/core/standard/requirements/local-resources-catalog_filtering/REQ_queryables-link.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_cql2-filter_queryables-link]] +[[req_local-resources-catalog_filtering_queryables-link]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/features-filter/cql2-filter/queryables-link* +^|*Requirement {counter:req-id}* |*/req/features-filter/filtering/queryables-link* ^|A |Implementations SHALL, at the local resources endpoint, include a `links` section that contains a link with `rel="http://www.opengis.net/def/rel/ogc/1.0/queryables"`. ^|B |This link SHALL point to a resource for discovering the list of record properties (and their types) that may be used to construct a filter expression. |=== diff --git a/core/standard/requirements/local-resources-catalogue_sorting/REQ_param-sortby-def.adoc b/core/standard/requirements/local-resources-catalog_sorting/REQ_param-sortby-def.adoc similarity index 67% rename from core/standard/requirements/local-resources-catalogue_sorting/REQ_param-sortby-def.adoc rename to core/standard/requirements/local-resources-catalog_sorting/REQ_param-sortby-def.adoc index 3b53481f..f36355db 100644 --- a/core/standard/requirements/local-resources-catalogue_sorting/REQ_param-sortby-def.adoc +++ b/core/standard/requirements/local-resources-catalog_sorting/REQ_param-sortby-def.adoc @@ -1,7 +1,7 @@ -[[req_local-resource-catalogue_sorting_param-sortby-def]] +[[req_local-resource-catalog_sorting_param-sortby-def]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resource-catalogue/sorting/param-sortby-def* +^|*Requirement {counter:req-id}* |*/req/local-resource-catalog/sorting/param-sortby-def* ^|A |Implementations SHALL, at the local resources endpoint and for the HTTP GET operation, support a parameter `sortby`. ^|B |The characteristics of the `sortby` parameter SHALL be as defined by requirement <>. diff --git a/core/standard/requirements/local-resources-catalogue_sorting/REQ_param-sortby-response.adoc b/core/standard/requirements/local-resources-catalog_sorting/REQ_param-sortby-response.adoc similarity index 69% rename from core/standard/requirements/local-resources-catalogue_sorting/REQ_param-sortby-response.adoc rename to core/standard/requirements/local-resources-catalog_sorting/REQ_param-sortby-response.adoc index 133305f8..6a0983ca 100644 --- a/core/standard/requirements/local-resources-catalogue_sorting/REQ_param-sortby-response.adoc +++ b/core/standard/requirements/local-resources-catalog_sorting/REQ_param-sortby-response.adoc @@ -1,7 +1,7 @@ -[[req_local-resources-catalogue_sorting_param-sortby-response]] +[[req_local-resources-catalog_sorting_param-sortby-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/sorting/param-sortby-response* +^|*Requirement {counter:req-id}* |*/req/local-resources-catalog/sorting/param-sortby-response* ^|A |If the `sortby` parameter is specified, then the resources from the local resources endpoint in a response SHALL be ordered by the keys and sort directions (i.e. ascending or descending) specified. ^|B |The specific set of keys that may be used for sorting SHALL be specified by the `/collections/{collectionId}/sortables` resource. diff --git a/core/standard/requirements/local-resources-catalogue/REQ_property-description.adoc b/core/standard/requirements/local-resources-catalogue/REQ_property-description.adoc deleted file mode 100644 index f29408e0..00000000 --- a/core/standard/requirements/local-resources-catalogue/REQ_property-description.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[req_local-resources-catalogue_property-description-def]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/property-description-def* - -The `description` property SHALL be present in the information model of the local resource object. -|=== - diff --git a/core/standard/requirements/local-resources-catalogue/REQ_property-title.adoc b/core/standard/requirements/local-resources-catalogue/REQ_property-title.adoc deleted file mode 100644 index 3b22f4d9..00000000 --- a/core/standard/requirements/local-resources-catalogue/REQ_property-title.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_local-resources-catalogue_property-title-def]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/property-title-def* - -The `title` property SHALL be present in the information model of the local resource object. -|=== diff --git a/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-lang-param.adoc b/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-lang-param.adoc deleted file mode 100644 index 656d952b..00000000 --- a/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-lang-param.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_local-resources-catalogue_cql2-filter_filter-lang-param]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/cql2-filter/filter-lang-param* - -Implementation of the conformance class SHALL, at the local resource endpoint and for the HTTP GET operation, support the `filter-lang` parameter as defined in https://docs.ogc.org/DRAFTS/19-079.html#filter-lang-param[Parameter filter-lang]. -|=== diff --git a/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-param.adoc b/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-param.adoc deleted file mode 100644 index f30297ee..00000000 --- a/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-param.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_local-resources-catalogue_cql2-filter_filter-param]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/features-filter/cql2-filter/filter-param* - -Implementations SHALL, at the local resources endpoint and for the HTTP GET operation, support the `filter` parameter as defined in https://docs.ogc.org/DRAFTS/19-079.html#filter-param[Parameter filter]. -|=== diff --git a/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-response.adoc b/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-response.adoc deleted file mode 100644 index 40bc7e89..00000000 --- a/core/standard/requirements/local-resources-catalogue_cql2-filter/REQ_filter-response.adoc +++ /dev/null @@ -1,10 +0,0 @@ -[[req_local-resources-catalogue_cql2-filter_filter-response]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/local-resources-catalogue/cql2-filter/filter-response* - -^|A |A filter expression SHALL be evaluated for each local resources object at the local resources endpoint. -^|B |All other filtering parameters specified (i.e. zero or more of <>, <>, <>, <>, <> and any <>) SHALL be evaluated for each local resources object at the local resources endpoint. -^|C |If the filter expression AND all other specified filtering parameters (i.e. zero or more of <>, <>, <>, <>, <> and any <>) evaluate to `TRUE` then the local resources object SHALL be included in the result. -^|D |If the filter expression OR any other specified filtering parameter (i.e. zero or more of <>, <>, <>, <>, <> and any <>) evaluates to `FALSE` then the local resources object SHALL be excluded from the result. -|=== diff --git a/core/standard/requirements/record-collection/REQ_links.adoc b/core/standard/requirements/record-collection/REQ_links.adoc index 31a57df9..62abab05 100644 --- a/core/standard/requirements/record-collection/REQ_links.adoc +++ b/core/standard/requirements/record-collection/REQ_links.adoc @@ -2,6 +2,6 @@ [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/record-collection/links* -^|A |If the catalogue is a <>, the collection SHALL contain one or more links (`rel="item"`) in the `links` section that explicitly point to each record in the collection. -^|B |If the catalogue is a <>, the collection SHALL contain a link (`rel="items"`) in the `links` section that point to the search/access endpoint for the records of the collection. +^|A |If the catalog is a <>, the collection SHALL contain one or more links (`rel="item"`) in the `links` section that explicitly point to each record in the collection. +^|B |If the catalog is a <>, the collection SHALL contain a link (`rel="items"`) in the `links` section that point to the search/access endpoint for the records of the collection. |=== diff --git a/core/standard/requirements/record-collection/REQ_mandatory-queryables.adoc b/core/standard/requirements/record-collection/REQ_mandatory-properties.adoc similarity index 70% rename from core/standard/requirements/record-collection/REQ_mandatory-queryables.adoc rename to core/standard/requirements/record-collection/REQ_mandatory-properties.adoc index db1d80b5..17a9175b 100644 --- a/core/standard/requirements/record-collection/REQ_mandatory-queryables.adoc +++ b/core/standard/requirements/record-collection/REQ_mandatory-properties.adoc @@ -1,7 +1,7 @@ -[[req_record-collection_mandatory-queryables-collection]] +[[req_record-collection_mandatory-properties-collection]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/record-collection/mandatory-queryables-collection* +^|*Requirement {counter:req-id}* |*/req/record-collection/mandatory-properties-collection* A collection object SHALL contain all the mandatory properties listed in <>. |=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-bbox.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-bbox.adoc new file mode 100644 index 00000000..d4fb88c1 --- /dev/null +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-bbox.adoc @@ -0,0 +1,7 @@ +[[req_records-core-query-parameters_bbox]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/bbox* +^|A |A searchable endpoint SHALL support the Bounding Box Search (`bbox`) parameter as defined in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_bbox[OGC API - Features - Part 1: Core]. +^|B |All references to the term "features" in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_bbox[OGC API - Features - Part 1: Core] SHALL be replaced by the term "record" or "local resource" as the context may indicate. +|=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-datetime.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-datetime.adoc new file mode 100644 index 00000000..6307fee9 --- /dev/null +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-datetime.adoc @@ -0,0 +1,7 @@ +[[req_records-core-query-parameters_datetime]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/datetime* +^|A |A searchable endpoint SHALL support a Temporal Searching (`datetime`) parameter as defined in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_datetime[OGC API - Features - Part 1: Core]. +^|B |All references to the term "features" in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_datetim[OGC API - Features - Part 1: Core] SHALL be replaced by the term "record" or "local resource" as the context may indicate. +|=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalid-definition.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalid-definition.adoc new file mode 100644 index 00000000..91fdc845 --- /dev/null +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalid-definition.adoc @@ -0,0 +1,19 @@ +[[req_records-core-query-parameters_externalids-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/externalids-definition* +^|A |A searchable endpoint SHALL support search by External Identifiers (`externalIds`) parameter for the operation. +^|B |The `externalIds` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): + +[source,YAML] +---- +name: externalIds +in: query +required: false +schema: + type: array + items: + type: string +explode: false +---- +|=== diff --git a/core/standard/requirements/records-api/REQ_query-param-externalid-response.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalid-response.adoc similarity index 62% rename from core/standard/requirements/records-api/REQ_query-param-externalid-response.adoc rename to core/standard/requirements/record-core-query-parameters/REQ_query-param-externalid-response.adoc index fb24069f..1b6b78d5 100644 --- a/core/standard/requirements/records-api/REQ_query-param-externalid-response.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-externalid-response.adoc @@ -1,7 +1,7 @@ -[[req_records-api_param-externalid-response]] +[[req_records-core-query-parameters_externalids-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-api/param-type-response* +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/externalids-response* Only records that have an external identifier, as indicated by the values of the `externalIds` core queryable, equal to one of the listed values specified using the `externalIds` parameter SHALL be in the result set. |=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-definition.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-definition.adoc new file mode 100644 index 00000000..b5996e9c --- /dev/null +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-definition.adoc @@ -0,0 +1,23 @@ +[[req_records-core-query-parameters_ids-definition]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/ids-definition* +^|A |A Records API SHALL support the query-by-ids (ids) parameter for the operation. +^|B |The characteristics of the `ids` parameter SHALL be as defined by requirement http://fix.em[`req/ids/fc-ids-definition`] of the http://fix.me[OGC API - Features - Part X: Title Unknown] standard. The definition is copied here for convenience. + +[source,YAML] +---- +name: ids +in: query +required: false +schema: + type: array + items: + type: string +explode: false +---- + +^|C |An empty list of identifiers is a valid value for the `ids` parameter and indicates that the result set SHALL be empty. +|=== + +NOTE: Is the behaviour in C correct? If the `ids` parameter is empty should the server just ignore it? ... which would imply that all records should be part of results set (subject to any other filters of course). diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-response.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-response.adoc new file mode 100644 index 00000000..b35bb10f --- /dev/null +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-ids-response.adoc @@ -0,0 +1,7 @@ +[[req_records-core-query-parameters_ids-response]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/ids-response* + +Only records whose identifier match one of the identifiers specified using `ids` parameter SHALL be in the results set. +|=== diff --git a/core/standard/requirements/record-core-query-parameters/REQ_query-param-limit.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-limit.adoc new file mode 100644 index 00000000..4e061ef3 --- /dev/null +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-limit.adoc @@ -0,0 +1,7 @@ +[[req_records-core-query-parameters_limit]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/limit* +^|A |A searchable endpoint SHALL support a Paging (`limit`) parameter as defined in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_limit[OGC API - Features - Part 1: Core]. +^|B |All references to the term "features" in https://docs.ogc.org/is/17-069r4/17-069r4.html#_parameter_limit[OGC API - Features - Part 1: Core] SHALL be replaced by the term "record" or "local resource" as the context may indicate. +|=== diff --git a/core/standard/requirements/records-api/REQ_query-param-q-definition.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-definition.adoc similarity index 72% rename from core/standard/requirements/records-api/REQ_query-param-q-definition.adoc rename to core/standard/requirements/record-core-query-parameters/REQ_query-param-q-definition.adoc index 4c673b27..4defefd7 100644 --- a/core/standard/requirements/records-api/REQ_query-param-q-definition.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-definition.adoc @@ -1,8 +1,8 @@ -[[req_records-api_param-q-definition]] +[[req_records-core-query-parameters_q-definition]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-api/param-q-definition* -^|A |A Records API SHALL support the Text Search (q) parameter for the operation. +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/q-definition* +^|A |A searchable endpoint SHALL support the Text Search (`q`) parameter for the operation. ^|B |The `q` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): [source,YAML] diff --git a/core/standard/requirements/records-api/REQ_query-param-q-response.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-response.adoc similarity index 56% rename from core/standard/requirements/records-api/REQ_query-param-q-response.adoc rename to core/standard/requirements/record-core-query-parameters/REQ_query-param-q-response.adoc index 2c580ea4..d39cbef5 100644 --- a/core/standard/requirements/records-api/REQ_query-param-q-response.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-q-response.adoc @@ -1,7 +1,7 @@ -[[req_records-api_param-q-response]] +[[req_records-core-query-parameters_q-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-api/param-q-response* +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/q-response* Only records whose text fields contains one or more of the search terms specified using the `q` parameter SHALL be in the result set. |=== diff --git a/core/standard/requirements/records-api/REQ_query-param-type-definition.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-definition.adoc similarity index 55% rename from core/standard/requirements/records-api/REQ_query-param-type-definition.adoc rename to core/standard/requirements/record-core-query-parameters/REQ_query-param-type-definition.adoc index c42736dd..e2c781ed 100644 --- a/core/standard/requirements/records-api/REQ_query-param-type-definition.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-definition.adoc @@ -1,8 +1,8 @@ -[[req_records-api_param-type-definition]] +[[req_records-core-query-parameters_type-definition]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-api/param-type-definition* -^|A |A Records API SHALL support the search by Type (type) parameter for the operation. +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/type-definition* +^|A |A searchable endpoint SHALL support the search by Type (`type`) parameter for the operation. ^|B |The `type` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): [source,YAML] diff --git a/core/standard/requirements/records-api/REQ_query-param-type-response.adoc b/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-response.adoc similarity index 61% rename from core/standard/requirements/records-api/REQ_query-param-type-response.adoc rename to core/standard/requirements/record-core-query-parameters/REQ_query-param-type-response.adoc index fb244f09..6c5b70ed 100644 --- a/core/standard/requirements/records-api/REQ_query-param-type-response.adoc +++ b/core/standard/requirements/record-core-query-parameters/REQ_query-param-type-response.adoc @@ -1,7 +1,7 @@ -[[req_records-api_param-type-response]] +[[req_records-core-query-parameters_type-response]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/records-api/param-type-response* +^|*Requirement {counter:req-id}* |*/req/records-core-query-parameters/type-response* Only records whose type, as indicated by the value of the `type` core queryable, is equal to one of the listed values specified using the `type` parameter SHALL be in the result set. |=== diff --git a/core/standard/requirements/record-core/REQ_mandatory-properties-record.adoc b/core/standard/requirements/record-core/REQ_mandatory-properties-record.adoc new file mode 100644 index 00000000..9b2f1664 --- /dev/null +++ b/core/standard/requirements/record-core/REQ_mandatory-properties-record.adoc @@ -0,0 +1,7 @@ +[[req_record-core_mandatory-properties-record]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/record-core/mandatory-properties-record* + +Each record in a response SHALL contain all the mandatory properties listed in <> and <>. +|=== diff --git a/core/standard/requirements/record-core/REQ_mandatory-queryables-record.adoc b/core/standard/requirements/record-core/REQ_mandatory-queryables-record.adoc deleted file mode 100644 index 340e8f5a..00000000 --- a/core/standard/requirements/record-core/REQ_mandatory-queryables-record.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_record-core_mandatory-queryables-record]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/record-core/mandatory-queryables-record* - -Each record in a response SHALL contain all the mandatory properties listed in <> and <>. -|=== diff --git a/core/standard/requirements/record-core/REQ_record-license.adoc b/core/standard/requirements/record-core/REQ_record-license.adoc index 125991fb..8875c800 100644 --- a/core/standard/requirements/record-core/REQ_record-license.adoc +++ b/core/standard/requirements/record-core/REQ_record-license.adoc @@ -7,4 +7,4 @@ ^|C |If the resource is being made available under one or more licenses that haven't been assigned an https://spdx.org/licenses/[SPDX license identifier] or one or more custom licenses then the value of the `license` member SHALL be the value `other` and one or more links (relation: `license`) SHALL be included in the `links` section of the record pointing to the file(s) that contain the text of the licenses. |=== -NOTE: There is also the case of a resource that is private or unpublished and is thus unlicensed; in this case do not register such a resource in the catalogue in the first place since there is no point in making such a resource discoverable. +NOTE: There is also the case of a resource that is private or unpublished and is thus unlicensed; in this case do not register such a resource in the catalog in the first place since there is no point in making such a resource discoverable. diff --git a/core/standard/requirements/record-core/REQ_record-links.adoc b/core/standard/requirements/record-core/REQ_record-links.adoc index b8b28690..9349911e 100644 --- a/core/standard/requirements/record-core/REQ_record-links.adoc +++ b/core/standard/requirements/record-core/REQ_record-links.adoc @@ -4,7 +4,7 @@ ^|*Requirement {counter:req-id}* |*/req/core/record-links* ^|A |Each record SHALL include a link (`rel="self"`) to itself. ^|B |Each record SHALL, if it is a member of a collection, include a link (`rel="collection"`) pointing to the collection of which this record in a member. -^|C |Each record SHALL, if they exist, include typed links (`rel="alternate"`) to each alternative representation of the record. +^|C |Each record SHALL, if they exist, include typed links (`rel="alternate"`) to each alternative representation of this record. |=== NOTE: The term "typed link" means a link that specifies a value for the `type` attribute diff --git a/core/standard/requirements/records-api/REQ_conformance-classes.adoc b/core/standard/requirements/records-api/REQ_conformance-classes.adoc index 47b88265..aff0dc70 100644 --- a/core/standard/requirements/records-api/REQ_conformance-classes.adoc +++ b/core/standard/requirements/records-api/REQ_conformance-classes.adoc @@ -2,11 +2,14 @@ [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/records-api/conformance* - An implementation of the Records API SHALL declare the following conformance classes in the conformance declaration retrieved from the `/conformance` endpoint as defined in the http://docs.ogc.org/is/17-069r3/17-069r3.html#_declaration_of_conformance_classes[Declaration of conformance classes] clause of the http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] standard. -* http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalogue +* http://http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core * http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-core * http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-collection +* http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/record-query-parameters * http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/records-api +* http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/searchable-catalog |=== + +NOTE: Do we need to include the "record" conformance class URIs? The searchable catalog conformance class already implies dependencies on all these ... no? diff --git a/core/standard/requirements/records-api/REQ_query-param-externalid-definition.adoc b/core/standard/requirements/records-api/REQ_query-param-externalid-definition.adoc deleted file mode 100644 index 28850807..00000000 --- a/core/standard/requirements/records-api/REQ_query-param-externalid-definition.adoc +++ /dev/null @@ -1,19 +0,0 @@ -[[req_records-api_param-externalid-definition]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/records-api/param-externalid-definition* -^|A |A Records API SHALL support the search by External Identifier (externalId) parameter for the operation. -^|B |The `externalId` parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment): - -[source,YAML] ----- -name: externalId -in: query -required: false -schema: - type: array - items: - type: string -explode: false ----- -|=== diff --git a/core/standard/requirements/records-api/REQ_record-collection-response.adoc b/core/standard/requirements/records-api/REQ_record-collection-response.adoc index 8b9230c6..d9f0fa1e 100644 --- a/core/standard/requirements/records-api/REQ_record-collection-response.adoc +++ b/core/standard/requirements/records-api/REQ_record-collection-response.adoc @@ -3,10 +3,12 @@ |=== ^|*Requirement {counter:req-id}* |*/req/records-api/record-collection-response* -For an operation that selects a collection object, the body of the response SHALL contain a description of the catalogue based upon the following schema fragment which extends the http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml[collection.yaml] schema defined in the http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] standard: +^|A |For an operation that selects a collection object, the body of the response SHALL contain a description of the catalog based upon the following schema fragment which extends the http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml[collection.yaml] schema defined in the http://docs.ogc.org/is/17-069r3/17-069r3.html[OGC API - Features - Part 1: Core] standard: [source,YAML] ---- -include::../../../openapi/schemas/catalogue.yaml[] +include::../../../openapi/schemas/catalog.yaml[] ---- + +^|B |The `itemType` member SHALL be a string with the value `record`. |=== diff --git a/core/standard/requirements/records-api/REQ_record-collections-response.adoc b/core/standard/requirements/records-api/REQ_record-collections-response.adoc index e33c0fb3..795089e2 100644 --- a/core/standard/requirements/records-api/REQ_record-collections-response.adoc +++ b/core/standard/requirements/records-api/REQ_record-collections-response.adoc @@ -2,6 +2,6 @@ [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/records-api/record-collections-response* -^|A |The schema of each record collection or catalogue in the response SHALL be based upon the schema defined in the <> requirement. -^|B |For an operation that select a list of collection objects, only collections where the value of the `itemType` property (JSONPath: `$.collections[*].itemType`) is `record` SHALL be considered record collections or catalogues. +^|A |The schema of each record collection or catalog in the response SHALL be based upon the schema defined in the <> requirement. +^|B |For an operation that select a list of collection objects, only collections where the value of the `itemType` property (JSONPath: `$.collections[*].itemType`) is `record` SHALL be considered record collections or catalogs. |=== diff --git a/core/standard/requirements/requirements_class_crawlable-catalogue.adoc b/core/standard/requirements/requirements_class_crawlable-catalog.adoc similarity index 71% rename from core/standard/requirements/requirements_class_crawlable-catalogue.adoc rename to core/standard/requirements/requirements_class_crawlable-catalog.adoc index 18a0d067..ccea7c4c 100644 --- a/core/standard/requirements/requirements_class_crawlable-catalogue.adoc +++ b/core/standard/requirements/requirements_class_crawlable-catalog.adoc @@ -1,9 +1,9 @@ -[[rc_crawlable_catalogue]] +[[rc_crawlable-catalog]] [cols="1,4",width="90%"] |=== 2+|*Requirements Class* -2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/crawlable-catalogue +2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/crawlable-catalog |Target type |Web API +|Dependency |<> |Dependency |<> -|Dependency |<> |=== diff --git a/core/standard/requirements/requirements_class_geojson.adoc b/core/standard/requirements/requirements_class_geojson.adoc deleted file mode 100644 index 15ac3c54..00000000 --- a/core/standard/requirements/requirements_class_geojson.adoc +++ /dev/null @@ -1,13 +0,0 @@ -[[rc_geojson]] -[cols="1,4",width="90%"] -|=== -2+|*Requirements Class* -2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/geojson -|Target type |Document encoding -|Dependency |<> -|Dependency |<> -|Dependency |<> -|Pre-conditions | -1) The API advertises conformance to the GeoJSON Conformance Class + -2) The client negotiates use of the GeoJSON encoding. -|=== diff --git a/core/standard/requirements/requirements_class_json.adoc b/core/standard/requirements/requirements_class_json.adoc new file mode 100644 index 00000000..8da713d8 --- /dev/null +++ b/core/standard/requirements/requirements_class_json.adoc @@ -0,0 +1,13 @@ +[[rc_json]] +[cols="1,4",width="90%"] +|=== +2+|*Requirements Class* +2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/json +|Target type |Document encoding +|Dependency |<> +|Dependency |<> +|Dependency |<> +|Pre-conditions | +1) The API advertises conformance to the JSON Conformance Class + +2) The client negotiates use of the JSON (catalog) or GeoJSON (record). +|=== diff --git a/core/standard/requirements/requirements_class_local-resources-catalog.adoc b/core/standard/requirements/requirements_class_local-resources-catalog.adoc new file mode 100644 index 00000000..954cd072 --- /dev/null +++ b/core/standard/requirements/requirements_class_local-resources-catalog.adoc @@ -0,0 +1,9 @@ +[[rc_local-resources-catalog]] +[cols="1,4",width="90%"] +|=== +2+|*Requirements Class* +2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog +|Target type |Web API +|Dependency |<> +|Dependency |<> +|=== diff --git a/core/standard/requirements/requirements_class_local-resources-catalog_filtering.adoc b/core/standard/requirements/requirements_class_local-resources-catalog_filtering.adoc new file mode 100644 index 00000000..827e5b75 --- /dev/null +++ b/core/standard/requirements/requirements_class_local-resources-catalog_filtering.adoc @@ -0,0 +1,9 @@ +[[rc_local-resources-catalog_filtering]] +[cols="1,4",width="90%"] +|=== +2+|*Requirements Class* +2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/filtering +|Target type |Web API +|Dependency |<> +|Dependency |<> +|=== diff --git a/core/standard/requirements/requirements_class_local-resources-catalog_sorting.adoc b/core/standard/requirements/requirements_class_local-resources-catalog_sorting.adoc new file mode 100644 index 00000000..54887489 --- /dev/null +++ b/core/standard/requirements/requirements_class_local-resources-catalog_sorting.adoc @@ -0,0 +1,9 @@ +[[rc_local-resources-catalog_sorting]] +[cols="1,4",width="90%"] +|=== +2+|*Requirements Class* +2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/sorting +|Target type |Web API +|Dependency |<> +|Dependency |<> +|=== diff --git a/core/standard/requirements/requirements_class_local-resources-catalogue.adoc b/core/standard/requirements/requirements_class_local-resources-catalogue.adoc deleted file mode 100644 index 43ab4545..00000000 --- a/core/standard/requirements/requirements_class_local-resources-catalogue.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[[rc_local-resources-catalogue]] -[cols="1,4",width="90%"] -|=== -2+|*Requirements Class* -2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalogue -|Target type |Web API -|Dependency |<> -|Dependency |<> -|=== diff --git a/core/standard/requirements/requirements_class_local-resources-catalogue_cql2-filter.adoc b/core/standard/requirements/requirements_class_local-resources-catalogue_cql2-filter.adoc deleted file mode 100644 index 3ad57165..00000000 --- a/core/standard/requirements/requirements_class_local-resources-catalogue_cql2-filter.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[[rc_local-resources-catalogue_cql2-filter]] -[cols="1,4",width="90%"] -|=== -2+|*Requirements Class* -2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalogue/cql2-filter -|Target type |Web API -|Dependency |<> -|Dependency |<> -|=== diff --git a/core/standard/requirements/requirements_class_local-resources-catalogue_sorting.adoc b/core/standard/requirements/requirements_class_local-resources-catalogue_sorting.adoc deleted file mode 100644 index b888368d..00000000 --- a/core/standard/requirements/requirements_class_local-resources-catalogue_sorting.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[rc_local-resources-catalogue_sorting]] -[cols="1,4",width="90%"] -|=== -2+|*Requirements Class* -2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalogue/sorting -|Target type |Web API -|=== diff --git a/core/standard/requirements/requirements_class_record-collection.adoc b/core/standard/requirements/requirements_class_record-collection.adoc index 016a5bd8..fd8d1292 100644 --- a/core/standard/requirements/requirements_class_record-collection.adoc +++ b/core/standard/requirements/requirements_class_record-collection.adoc @@ -1,4 +1,4 @@ -[[rc_record_collection]] +[[rc_record-collection]] [cols="1,4",width="90%"] |=== 2+|*Requirements Class* diff --git a/core/standard/requirements/requirements_class_record-core-query-parameters.adoc b/core/standard/requirements/requirements_class_record-core-query-parameters.adoc new file mode 100644 index 00000000..c34ef486 --- /dev/null +++ b/core/standard/requirements/requirements_class_record-core-query-parameters.adoc @@ -0,0 +1,8 @@ +[[rc_record-core-query-parameters]] +[cols="1,4",width="90%"] +|=== +2+|*Requirements Class* +2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters +|Target type |Web API +|Dependency | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core +|=== diff --git a/core/standard/requirements/requirements_class_record-core.adoc b/core/standard/requirements/requirements_class_record-core.adoc index e819c41c..a3eb21a3 100644 --- a/core/standard/requirements/requirements_class_record-core.adoc +++ b/core/standard/requirements/requirements_class_record-core.adoc @@ -1,4 +1,4 @@ -[[rc_record_core]] +[[rc_record-core]] [cols="1,4",width="90%"] |=== 2+|*Requirements Class* diff --git a/core/standard/requirements/requirements_class_record-filter.adoc b/core/standard/requirements/requirements_class_record-filter.adoc index a49d1639..358650ec 100644 --- a/core/standard/requirements/requirements_class_record-filter.adoc +++ b/core/standard/requirements/requirements_class_record-filter.adoc @@ -1,8 +1,8 @@ -[[rc_cql-filter]] +[[rc_filtering]] [cols="1,4",width="90%"] |=== 2+|*Requirements Class* -2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/cql-filter +2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/filtering |Target type |Web API |Dependency |<> |=== diff --git a/core/standard/requirements/requirements_class_records-api.adoc b/core/standard/requirements/requirements_class_records-api.adoc index 57071d80..d68e4a6a 100644 --- a/core/standard/requirements/requirements_class_records-api.adoc +++ b/core/standard/requirements/requirements_class_records-api.adoc @@ -1,4 +1,4 @@ -[[rc_records_api]] +[[rc_records-api]] [cols="1,4",width="90%"] |=== 2+|*Requirements Class* @@ -6,5 +6,5 @@ |Target type |Web API |Dependency |http://www.opengis.net/spec/ogcapi-features-1/1.0/req/core[OGC API - Features - Part 1: Core] |Dependency | <> -|Dependency | <> +|Dependency | <> |=== diff --git a/core/standard/requirements/requirements_class_searchable-catalogue.adoc b/core/standard/requirements/requirements_class_searchable-catalog.adoc similarity index 61% rename from core/standard/requirements/requirements_class_searchable-catalogue.adoc rename to core/standard/requirements/requirements_class_searchable-catalog.adoc index 71d32309..9ed88259 100644 --- a/core/standard/requirements/requirements_class_searchable-catalogue.adoc +++ b/core/standard/requirements/requirements_class_searchable-catalog.adoc @@ -1,14 +1,13 @@ -[[rc_searchable_catalogue]] +[[rc_searchable-catalog]] [cols="1,4",width="90%"] |=== 2+|*Requirements Class* -2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalogue +2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog |Target type |Web API +|Dependency |<> |Dependency |<> -|Dependency |<> +|Dependency |<> |Dependency |<> -|Dependency |<> -|Dependency |<> |Dependency |<> |Dependency |<> |=== diff --git a/core/standard/requirements/requirements_class_searchable-catalog_filtering.adoc b/core/standard/requirements/requirements_class_searchable-catalog_filtering.adoc new file mode 100644 index 00000000..9cdb68bb --- /dev/null +++ b/core/standard/requirements/requirements_class_searchable-catalog_filtering.adoc @@ -0,0 +1,9 @@ +[[rc_searchable-catalog_filtering]] +[cols="1,4",width="90%"] +|=== +2+|*Requirements Class* +2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/filtering +|Target type |Web API +|Dependency |<> +|Dependency |<> +|=== diff --git a/core/standard/requirements/requirements_class_searchable-catalogue_sorting.adoc b/core/standard/requirements/requirements_class_searchable-catalog_sorting.adoc similarity index 60% rename from core/standard/requirements/requirements_class_searchable-catalogue_sorting.adoc rename to core/standard/requirements/requirements_class_searchable-catalog_sorting.adoc index 738d6c1e..5ad648b2 100644 --- a/core/standard/requirements/requirements_class_searchable-catalogue_sorting.adoc +++ b/core/standard/requirements/requirements_class_searchable-catalog_sorting.adoc @@ -1,9 +1,9 @@ -[[rc_searchable-catalogue_sorting]] +[[rc_searchable-catalog_sorting]] [cols="1,4",width="90%"] |=== 2+|*Requirements Class* -2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalogue/sorting +2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalog/sorting |Target type |Web API -|Dependency |<> +|Dependency |<> |Dependency |<> |=== diff --git a/core/standard/requirements/requirements_class_searchable-catalogue_cql2-filter.adoc b/core/standard/requirements/requirements_class_searchable-catalogue_cql2-filter.adoc deleted file mode 100644 index 50fd54b8..00000000 --- a/core/standard/requirements/requirements_class_searchable-catalogue_cql2-filter.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[[rc_searchable_catalogue_cql-filter]] -[cols="1,4",width="90%"] -|=== -2+|*Requirements Class* -2+|http://www.opengis.net/spec/ogcapi-records-1/1.0/req/searchable-catalogue/cql-filter -|Target type |Web API -|Dependency |<> -|Dependency |<> -|=== diff --git a/core/standard/requirements/searchable-catalogue/REQ_core.adoc b/core/standard/requirements/searchable-catalog/REQ_core.adoc similarity index 63% rename from core/standard/requirements/searchable-catalogue/REQ_core.adoc rename to core/standard/requirements/searchable-catalog/REQ_core.adoc index 7b7da3a4..32ecd4b5 100644 --- a/core/standard/requirements/searchable-catalogue/REQ_core.adoc +++ b/core/standard/requirements/searchable-catalog/REQ_core.adoc @@ -1,9 +1,10 @@ -[[req_searchable-catalogue_core]] +[[req_searchable-catalog_core]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/searchable-catalogue/requirements* +^|*Requirement {counter:req-id}* |*/req/searchable-catalog/requirements* 2+|Implementations of this conformance class SHALL implement the following requirements: -^|A |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection -^|B |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core -^|C |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api +^|A |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core +^|B |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-collection +^|C |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/record-core-query-parameters +^|D |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/records-api |=== diff --git a/core/standard/requirements/searchable-catalog/REQ_mandatory-properties.adoc b/core/standard/requirements/searchable-catalog/REQ_mandatory-properties.adoc new file mode 100644 index 00000000..1ff1d85e --- /dev/null +++ b/core/standard/requirements/searchable-catalog/REQ_mandatory-properties.adoc @@ -0,0 +1,7 @@ +[[req_searchable-catalog_mandatory-properties]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/searchable-catalog/mandatory-properties* + +The list of record properties SHALL include all the mandatory properties listed in <> and <>. +|=== diff --git a/core/standard/requirements/searchable-catalogue_crs/REQ_crs.adoc b/core/standard/requirements/searchable-catalog_crs/REQ_crs.adoc similarity index 76% rename from core/standard/requirements/searchable-catalogue_crs/REQ_crs.adoc rename to core/standard/requirements/searchable-catalog_crs/REQ_crs.adoc index d12ef38c..b5016cd4 100644 --- a/core/standard/requirements/searchable-catalogue_crs/REQ_crs.adoc +++ b/core/standard/requirements/searchable-catalog_crs/REQ_crs.adoc @@ -1,7 +1,7 @@ -[[req_searchable-catalogue_crs]] +[[req_searchable-catalog_crs]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/searchable-catalogue/crs* +^|*Requirement {counter:req-id}* |*/req/searchable-catalog/crs* 2+|Implementations of this conformance class SHALL implement the following conformance class from http://docs.opengeospatial.org/is/18-058/18-058.html[OGC API - Feature - Part 2: Coordinate Reference Systems by Reference]: ^|A |http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs |=== diff --git a/core/standard/requirements/searchable-catalog_filtering/REQ_filtering.adoc b/core/standard/requirements/searchable-catalog_filtering/REQ_filtering.adoc new file mode 100644 index 00000000..96fe67de --- /dev/null +++ b/core/standard/requirements/searchable-catalog_filtering/REQ_filtering.adoc @@ -0,0 +1,7 @@ +[[req_searchable-catalog_filtering]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/searchable-catalog/filtering* +2+|Implementations that offer enhanced filtering SHALL implement the following requirements: +^|A |<> +|=== diff --git a/core/standard/requirements/searchable-catalog_filtering/REQ_mandatory-queryables.adoc b/core/standard/requirements/searchable-catalog_filtering/REQ_mandatory-queryables.adoc new file mode 100644 index 00000000..1cfbe9e7 --- /dev/null +++ b/core/standard/requirements/searchable-catalog_filtering/REQ_mandatory-queryables.adoc @@ -0,0 +1,6 @@ +[[req_searchable-catalog_mandatory-queryables]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/searchable-catalog/mandatory-queryables* +2+|The list of queryables SHALL include all the mandatory properties listed in <> and <>. +|=== diff --git a/core/standard/requirements/searchable-catalog_sorting/REQ_sorting.adoc b/core/standard/requirements/searchable-catalog_sorting/REQ_sorting.adoc new file mode 100644 index 00000000..0c78a463 --- /dev/null +++ b/core/standard/requirements/searchable-catalog_sorting/REQ_sorting.adoc @@ -0,0 +1,7 @@ +[[req_searchable-catalog_sorting]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/searchable-catalog/sorting* +2+|Implementations that offer sorting SHALL implement the following requirements: +^|A | <> +|=== diff --git a/core/standard/requirements/searchable-catalogue/REQ_mandatory-properties.adoc b/core/standard/requirements/searchable-catalogue/REQ_mandatory-properties.adoc deleted file mode 100644 index 0e56271a..00000000 --- a/core/standard/requirements/searchable-catalogue/REQ_mandatory-properties.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_searchable-catalogue_mandatory-properties]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/searchable-catalogue/mandatory-properties* - -The list of record properties SHALL include all the mandatory properties listed in <> and <>. -|=== diff --git a/core/standard/requirements/searchable-catalogue_cql2-filter/REQ_filtering.adoc b/core/standard/requirements/searchable-catalogue_cql2-filter/REQ_filtering.adoc deleted file mode 100644 index 353cf632..00000000 --- a/core/standard/requirements/searchable-catalogue_cql2-filter/REQ_filtering.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_searchable-catalogue_cql2-filtering]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/searchable-catalogue/cql2-filtering* -2+|Implementations that offer enhanced filtering SHALL implement the following requirements: -^|A |http://www.opengis.net/spec/ogcapi-records-1/1.0/req/cql-filter -|=== diff --git a/core/standard/requirements/searchable-catalogue_cql2-filter/REQ_mandatory-queryables.adoc b/core/standard/requirements/searchable-catalogue_cql2-filter/REQ_mandatory-queryables.adoc deleted file mode 100644 index aa195d9c..00000000 --- a/core/standard/requirements/searchable-catalogue_cql2-filter/REQ_mandatory-queryables.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[[req_searchable-catalogue_mandatory-queryables]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/searchable-catalogue/mandatory-queryables* -2+|The list of queryables SHALL include all the mandatory queryables listed in <> and <>. -|=== diff --git a/core/standard/requirements/searchable-catalogue_sorting/REQ_sorting.adoc b/core/standard/requirements/searchable-catalogue_sorting/REQ_sorting.adoc deleted file mode 100644 index f4811dbb..00000000 --- a/core/standard/requirements/searchable-catalogue_sorting/REQ_sorting.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[[req_searchable-catalogue_sorting]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/searchable-catalogue/sorting* -2+|Implementations that offer sorting SHALL implement the following requirements: -^|A | http://www.opengis.net/spec/ogcapi-records-1/1.0/req/sorting -|=== diff --git a/core/standard/requirements/sorting/REQ_defaultSortOrder-definition.adoc b/core/standard/requirements/sorting/REQ_defaultSortOrder-definition.adoc index 4cb75d11..a29b7f2b 100644 --- a/core/standard/requirements/sorting/REQ_defaultSortOrder-definition.adoc +++ b/core/standard/requirements/sorting/REQ_defaultSortOrder-definition.adoc @@ -3,7 +3,7 @@ |=== ^|*Requirement {counter:req-id}* |*/req/sorting/defaultSortOrder-definition* -^|A |The schema of a collections (collectionInfo.yaml) SHALL be extended with the addition of the `defaultSortOrder` member with the following characteristics (using an OpenAPI Sepcification 3.0 fragment): +^|A |The schema of a collection (collectionInfo.yaml) SHALL be extended with the addition of the `defaultSortOrder` member with the following characteristics (using an OpenAPI Sepcification 3.0 fragment): [source,YAML] ---- diff --git a/core/standard/requirements/sorting/REQ_sortby-definition.adoc b/core/standard/requirements/sorting/REQ_sortby-definition.adoc index a46b3aab..673e8a1f 100644 --- a/core/standard/requirements/sorting/REQ_sortby-definition.adoc +++ b/core/standard/requirements/sorting/REQ_sortby-definition.adoc @@ -3,7 +3,7 @@ |=== ^|*Requirement {counter:req-id}* |*/req/sorting/sortby-definition* -^|A |The operation SHALL support a parameter `sortby` with the following characteristics (using an OpenAPI Specification 3.0 fragment): +^|A |At the searchable catalog endpoint, the operation SHALL support a parameter `sortby` with the following characteristics (using an OpenAPI Specification 3.0 fragment): [source,YAML] ----