13-hierarchy: Initial draft of hierarchical collections

- Describes latest proposal agreed to in the SWG on 2024-05-16 in ( fixes opengeospatial#11 and opengeospatial#298 )
- TODO: Still need to add OpenAPI definitions
- 11-sorting, 12-filtering, 14-schemas: set up requirement class tables

collections/clause_11_sortable_collections.adoc

@@ -2,4 +2,4 @@
 == Requirements Class "Sortable Collections"
 :sectnums:
 
-// TODO: include::requirements/requirements_class_sortable_collections.adoc[]
+include::requirements/requirements_class_sorting.adoc[]

collections/clause_12_filterable_collections.adoc

@@ -2,4 +2,4 @@
 == Requirements Class "Filtering Collections with CQL2"
 :sectnums:
 
-// TODO: include::requirements/requirements_class_filterable_collections.adoc[]
+include::requirements/requirements_class_filtering.adoc[]

collections/clause_14_schemas.adoc

@@ -2,5 +2,4 @@
 == Requirements Class "Schemas"
 :sectnums:
 
-// TODO: include::requirements/requirements_class_schemas.adoc[]
-
+include::requirements/requirements_class_schemas.adoc[]

collections/recommendations/hierarchy/PER_collection_children.adoc

@@ -0,0 +1,6 @@
+[[per_hierarchy_collection_children]]
+[width="90%",cols="2,6a"]
+|===
+^|*Permission {counter:per-id}* |*/per/hierarchy/parent_default_html*
+^|A |For representations not intended primarily for consumption by machines, such as an HTML representation, an implementation MAY include clickable links to the immediate children collections to facilitate browsing through the hierarchy.
+|===

collections/recommendations/hierarchy/PER_parent_default_html.adoc

@@ -0,0 +1,6 @@
+[[per_hierarchy_parent_default_html]]
+[width="90%",cols="2,6a"]
+|===
+^|*Permission {counter:per-id}* |*/per/hierarchy/parent_default_html*
+^|A |For representations not intended primarily for consumption by machines, such as an HTML representation, an implementation MAY assume a default value of `none` for the `parent` query parameter, so as to present the collections in a hierarchical manner and avoid an unnecessarily large response when a large number of collections are available.
+|===

collections/recommendations/hierarchy/REC_parent_convention.adoc

@@ -0,0 +1,7 @@
+[[rec_hierarchy_parent-convention]]
+[width="90%",cols="2,6a"]
+|===
+^|*Recommendation {counter:rec-id}* |*/rec/hierarchy/parent-convention*
+^|A |The identifiers for children collections SHOULD follow the pattern `{parentCollectionId}{separator}{distinctivePart}`. For example, the collection with identifier `can:qc:mtl` whose parent collection has the identifier `can:qc` follows this pattern.
+^|B |The same single separator character (for example, a colon `:`) SHOULD be used for all collections throughout a Web API deployment.
+|===

collections/requirements/hierarchy/REQ_ancestor_parameter.adoc

@@ -0,0 +1,7 @@
+[[req_hierarchy_ancestor-parameter]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/hierarchy/ancestor-parameter*
+^|A |The implementation SHALL support an `ancestor` parameter for listing collections at the resource `/collections` whose string value represents a specified ancestor collection identifier.
+^|B |The response for listing collections when this parameter is used SHALL only include collections whose immediate parent, or any ancestor from that parent up to the root of the hierarchy, corresponds to the specified collection identifier.
+|===

collections/requirements/hierarchy/REQ_parent_parameter.adoc

@@ -0,0 +1,8 @@
+[[req_hierarchy_parent-parameter]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/hierarchy/parent-parameter*
+^|A |The implementation SHALL support a `parent` query parameter for listing collections at the resource `/collections` whose string value represents a specified parent collection identifier.
+^|B |The response for listing collections when this parameter is used SHALL only include collections whose immediate parent corresponds to the specified collection identifier.
+^|C |When the special value of `none` is used for the `parent` parameter, only top-level collections without a parent SHALL be returned.
+|===

collections/requirements/hierarchy/REQ_parent_property.adoc

@@ -0,0 +1,8 @@
+[[req_hierarchy_parent-property]]
+[width="90%",cols="2,6a"]
+|===
+^|*Requirement {counter:req-id}* |*/req/hierarchy/parent-property*
+^|A |For collections organized into a hierarchy which are not top-level collections, the collection object response for both listing collections (`/collections`) and for individual collection description (`/collections/{collectionId}`) SHALL include a `parent` property set to the collection identifier of the parent collection.
+^|B |The `parent` property in collection objects for top-level collections SHALL be omitted or set to a null value.
+^|C |Collection identifiers SHALL NOT use the reserved value of `none`.
+|===

collections/requirements/requirements_class_filtering.adoc

@@ -0,0 +1,10 @@
+[[rc_filtering]]
+[cols="1,4",width="90%"]
+|===
+2+|*Requirements Class*
+2+|http://www.opengis.net/spec/ogcapi-common-2/1.0/req/filtering
+|Target type |Web API
+|Dependency |<<rc_collections,Collections Requirements Class>>
+|Dependency |https://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/filtering
+|Dependency |https://www.opengis.net/spec/cql2/1.0/req/basic-cql2
+|===

collections/requirements/requirements_class_hierarchy.adoc

@@ -0,0 +1,8 @@
+[[rc_hierarchy]]
+[cols="1,4",width="90%"]
+|===
+2+|*Requirements Class*
+2+|http://www.opengis.net/spec/ogcapi-common-2/1.0/req/hierarchy
+|Target type |Web API
+|Dependency |<<rc_collections,Collections Requirements Class>>
+|===

collections/requirements/requirements_class_schemas.adoc

@@ -0,0 +1,8 @@
+[[rc_schemas]]
+[cols="1,4",width="90%"]
+|===
+2+|*Requirements Class*
+2+|http://www.opengis.net/spec/ogcapi-common-2/1.0/req/schemas
+|Target type |Web API
+|Dependency |<<rc_collections,Collections Requirements Class>>
+|===

collections/requirements/requirements_class_searchable_collections.adoc

@@ -6,4 +6,5 @@
 |Target type |Web API
 |Dependency |<<rc_collections,Collections Requirements Class>>
 |Dependency |<<rfc3339,RFC 3339 (Date and Time on the Internet: Timestamps)>>
+|Dependency |https://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/query-parameters
 |===

collections/requirements/requirements_class_sorting.adoc

@@ -0,0 +1,9 @@
+[[rc_sorting]]
+[cols="1,4",width="90%"]
+|===
+2+|*Requirements Class*
+2+|http://www.opengis.net/spec/ogcapi-common-2/1.0/req/sorting
+|Target type |Web API
+|Dependency |<<rc_collections,Collections Requirements Class>>
+|Dependency |https://www.opengis.net/spec/ogcapi-records-1/1.0/req/local-resources-catalog/sorting
+|===