add facets extension

extensions/facets/README.md

@@ -0,0 +1,10 @@
+# OGC API - Records - Part 2: Facets
+
+This folder contains the content for the OGC API - Records - Part 1: Facets standard.
+
+The repo is organized as follows:
+
+* standard - the main standard document content
+  - organized in multiple sections and directories
+* openapi - normative OpenAPI components specified by the standard
+* examples - JSON and XML examples

extensions/facets/examples/README.md

@@ -0,0 +1,7 @@
+# Examples
+
+The sub-folders contain examples of responses of implementations of
+OGC API - Records - Part 2: Facets.
+
+* [JSON/GeoJSON examples](json)
+* [YAML examples](yaml)

extensions/facets/standard/HTML_Gen.bat

@@ -0,0 +1 @@
+asciidoctor --trace -o ../document.html document.adoc

extensions/facets/standard/Makefile

@@ -0,0 +1,3 @@
+
+html:
+	asciidoctor --verbose --trace -o document.html document.adoc

extensions/facets/standard/PDF_Gen.bat

@@ -0,0 +1 @@
+asciidoctor -r asciidoctor-pdf --trace -b pdf -o ../document.pdf document.adoc

extensions/facets/standard/README.md

@@ -0,0 +1,19 @@
+
+# OGC API - Records - Part 2: Facets Specification
+
+This directory contains the OGC API - Records - Part 2: Facets Specification. This specification, working with OGC API - Records - Part 1: Core, defines the mechanisms with which to apply faceting to an OGC API - Records endpoint.
+
+## Generating HTML and PDF
+
+The latest drafts of each standard in this repository are built daily (based on the configuration contained in the [asciidoctor.json](https://github.com/opengeospatial/ogcapi-records/blob/master/asciidoctor.json) file):
+
+* [Part 1: Core](https://docs.ogc.org/DRAFTS/20-004.html)
+
+To generate HTML and PDF representations of the standard yourself, asciidoctor is required.  To install:
+
+```bash
+gem install asciidoctor --pre
+gem install asciidoctor-pdf --pre
+```
+
+From here, run `HTML_gen.bat` and `PDF_gen.bat` accordingly.  Outputs are written to the parent directory.

extensions/facets/standard/abstract_tests/ATS_class_advanced.adoc

@@ -0,0 +1,12 @@
+[[ats_advanced]]
+[cols="1,4",width="90%"]
+|===
+2+|*Conformance Class*
+2+|http://www.opengis.net/spec/ogcapi-records-2/1.0/conf/advanced
+|Target type |Web API
+|Requirements class |<<rc_advanced,Requirements Class "Simple Facets">>
+|===
+
+==== Conformance
+
+include::advanced/ATS_conformance.adoc[]

extensions/facets/standard/abstract_tests/ATS_class_simple.adoc

@@ -0,0 +1,12 @@
+[[ats_simple]]
+[cols="1,4",width="90%"]
+|===
+2+|*Conformance Class*
+2+|http://www.opengis.net/spec/ogcapi-records-2/1.0/conf/simple
+|Target type |Web API
+|Requirements class |<<rc_simple,Requirements Class "Simple Facets">>
+|===
+
+==== Conformance
+
+include::simple/ATS_conformance.adoc[]

extensions/facets/standard/abstract_tests/README.md

@@ -0,0 +1,27 @@
+This folder contains the Abstract Test Suite.
+
+Each file describes a single test. The naming convention for these files is:
+
+"cc/TESTn.adoc" where "cc" corresponds to the identifier for the conformance class and "n" corresponds to the test number. Numbers should have preceding zeros appropriate for the total number of tests in the conformance class (e.g., the first test could be TEST001 if less than 1000 tests are anticipated).
+
+The test is expressed according to this pattern:
+
+````
+===== Test case title
+
+(( additional discussion, if needed ))
+
+====== a) Test Purpose:
+(( description ))
+
+====== b) Pre-conditions:
+* (( list all preconditions ))
+
+====== c) Test Method:
+* (( steps to execute and assertions to test ))
+
+====== d) References:
+* <<req_cc_req,Requirement /req/cc/req>>
+````
+
+NOTE: for each test, there must be one or more requirements in the "requirements" folder.

extensions/facets/standard/abstract_tests/advanced/ATS_conformance.adoc

@@ -0,0 +1,11 @@
+[[ats_advanced_conformance]]
+[width="90%",cols="2,6a"]
+|===
+^|*Abstract Test {counter:ats-id}* |*/conf/advanced/conformance*
+^|Test Purpose |Validate advanced identification.
+^|Requirement |<<req_advanced_conformance,/req/advanced/conformance>>
+^|Test Method |. Construct a path for a conformance page
+. Issue an HTTP GET request on the path
+. Check that the `+conformsTo+` array contains the value `+http://www.opengis.net/spec/ogcapi-records-2/1.0/conf/advanced+`.
+|===
+

extensions/facets/standard/abstract_tests/simple/ATS_conformance.adoc

@@ -0,0 +1,11 @@
+[[ats_simple_conformance]]
+[width="90%",cols="2,6a"]
+|===
+^|*Abstract Test {counter:ats-id}* |*/conf/simple/conformance*
+^|Test Purpose |Validate simple identification.
+^|Requirement |<<req_simple_conformance,/req/simple/conformance>>
+^|Test Method |. Construct a path for a conformance page
+. Issue an HTTP GET request on the path
+. Check that the `+conformsTo+` array contains the value `+http://www.opengis.net/spec/ogcapi-records-2/1.0/conf/simple+`.
+|===
+

extensions/facets/standard/annex_ats.adoc

@@ -0,0 +1,12 @@
+[appendix]
+:appendix-caption: Annex
+[[ats]]
+== Conformance Class Abstract Test Suite (Normative)
+
+=== Conformance Class: Simple Facets
+
+include::abstract_tests/ATS_class_simple.adoc[]
+
+=== Conformance Class: Advanced Facets
+
+include::abstract_tests/ATS_class_advanced.adoc[]

extensions/facets/standard/annex_bibliography.adoc

@@ -0,0 +1,9 @@
+[appendix]
+:appendix-caption: Annex
+[[Bibliography]]
+= Bibliography
+
+* [[Elasticsearch]] Elasticsearch aggregations, 30 May 2024, https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html
+* [[SOLR]] SOLR aggregations, 30 May 2024,  https://solr.apache.org/guide/8_8/json-facet-api.html
+* [[PostgreSQL]] PostgreSQL aggregations, 30 May 2024, https://akorotkov.github.io/blog/2016/06/17/faceted-search
+* [[Oracle]] Oracle aggreations, 30 May 2024, (https://blogs.oracle.com/apex/apex-192-faceted-search

extensions/facets/standard/annex_history.adoc

@@ -0,0 +1,9 @@
+[appendix]
+:appendix-caption: Annex
+== Revision History
+
+[cols="12,18,12,12,46",options="header"]
+|===
+|Date |Release |Editor | Primary clauses modified |Description
+|2024-05-29 |Template |T. Kralidis|all |initial template
+|===

extensions/facets/standard/clause_0_front_material.adoc

@@ -0,0 +1,49 @@
+[big]*i.     Abstract*
+
+The OGC API family of Standards is being developed to make it easy for anyone to provide geospatial data over the web. These Standards build upon the legacy of the OGC Web Service Standards (WMS, WFS, WCS, WPS, CSW, etc.), but define resource-centric APIs that take advantage of modern web development practices.
+
+This document defines the OGC API - Records - Part 2: Facets Standard.  In this document "Records API" refers to the OGC API - Records - Part 1: Core Standard.
+
+An implementation of a search API allows collections of records to be searched using logically connected spatial, temporal and scalar predicates.  As part of a given search response, additional information in the form of aggregations (facets) can provide enhanced navigation as well as valuable information about the spatio-temporal distribution of a given result set.
+
+This Standard uses the https://docs.ogc.org/DRAFTS/20-004.html[OGC API - Records - Part 1: Core] Standard for specifying requirements of Records search API faceting.
+
+[[keywords]]
+[big]*ii.    Keywords*
+
+The following are keywords to be used by search engines and document catalogs.
+
+ogcdoc, OGC document, OGC API, catalog, record, records, resource, metadata, discovery, CSW, API, GeoJSON, HTML, schema.org, JSON-LD, facet, facets, aggregration, aggregations
+
+[[preface]]
+[big]*iii.   Preface*
+
+*OGC Declaration*
+
+Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium Inc. shall not be held responsible for identifying any or all such patent rights.
+
+Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.
+
+[[submitting_organizations]]
+[big]*iv.    Submitting organizations*
+
+The following organizations submitted this Document to the Open Geospatial Consortium (OGC):
+
+* Meteorological Service of Canada
+* Camptocamp
+* Cubewerx Inc.
+* Open Source Geospatial Foundation
+* International Soil Reference and Information Centre
+
+[big]*v.     Submitters*
+
+All questions regarding this submission should be directed to the editor or the submitters:
+
+|===
+^|Name  ^|Affiliation
+| Tom Kralidis (editor) | Meteorological Service of Canada
+| Florent Gravin | Camptocamp
+| Paul van Genuchten | International Soil Reference and Information Centre
+| Panagiotis (Peter) A. Vretanos | Cubewerx Inc.
+| Angelos Tzotsos | Open Source Geospatial Foundation
+|===

extensions/facets/standard/clause_1_scope.adoc

@@ -0,0 +1,5 @@
+== Scope
+
+The OGC Records API Standard specifies requirements classes for a set of common components 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 Standard specifies the behaviour of representing facets.  A server implements one or more facets to selected properties of a record.  Facets can be based on terms, geometries, or time.

extensions/facets/standard/clause_2_conformance.adoc

@@ -0,0 +1,25 @@
+== Conformance
+
+This standard defines one requirements / conformance class:
+
+   *  <<rc_simple,Simple Facets>>
+   *  <<rc_advanced,Advanced Facets>>
+
+The standardization target is "Web APIs".
+
+The URIs of the associated conformance classes are: 
+
+[#conf_class_uris,reftext='{table-caption} {counter:table-num}']
+.Conformance class URIs
+[cols="25,75",options="header"]
+|===
+|Conformance class |URI
+|Simple Facets |http://www.opengis.net/spec/ogcapi-records-2/1.0/conf/simple
+|Advanced Facets |http://www.opengis.net/spec/ogcapi-records-2/1.0/conf/advanced
+|===
+
+Conformance with this standard shall be checked using all the relevant tests
+specified in <<ats,Annex A>> of this document. The framework, concepts, and
+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.

extensions/facets/standard/clause_3_references.adoc

@@ -0,0 +1,21 @@
+== References
+
+The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.
+
+* [[rfc2616]] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., Berners-Lee, T.: IETF RFC 2616, *HTTP/1.1*, https://tools.ietf.org/rfc/rfc2616.txt[RFC 2616]
+* [[rfc2818]] Rescorla, E.: IETF RFC 2818, *HTTP Over TLS*, https://tools.ietf.org/rfc/rfc2818.txt[RFC 2818]
+* [[rfc3339]] Klyne, G., Newman, C.: IETF RFC 3339, *Date and Time on the Internet: Timestamps*, https://tools.ietf.org/rfc/rfc3339.txt[RFC 3339]
+* [[rfc3986]] Berners-Lee, T., Fielding, R., Masinter, L.: IETF RFC 3986, *Uniform Resource Identifier (URI): Generic Syntax*, https://tools.ietf.org/html/rfc3986[RFC 3986]
+* [[rfc3987]] Duerst, M., Suignard, M.: IETF RFC 3987, *Internationalized Resource Identifiers (IRIs)*, https://tools.ietf.org/html/rfc3987[RFC 3987]
+* [[rfc6570]] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., Orchard, D.: IETF RFC 6570, *URI Template*, https://tools.ietf.org/html/rfc6570[RFC 6570]
+* [[rfc7159]] Bray, T.: IETF RFC 7159, *The JavaScript Object Notation (JSON) Data Interchange Format*, https://www.ietf.org/rfc/rfc7159.txt[RFC 7159]
+* [[GeoJSON]] Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., Schaub, T.: IETF RFC 7946: *The GeoJSON Format*, https://tools.ietf.org/rfc/rfc7946.txt[RFC 7946]
+* [[rfc8288]] Nottingham, M.: IETF RFC 8288, *Web Linking*, https://tools.ietf.org/rfc/rfc8288.txt[RFC 8288]
+* [[link-template]] Nottingham, M.: IETF, *The Link-Template HTTP Header Field*, https://ietf-wg-httpapi.github.io/link-template/draft-ietf-httpapi-link-template.html[draft-ietf-httpapi-link-template-latest]
+* [[OAFeat-1]] OGC 17-069r3: *OGC API - Features - Part 1: Core*, http://docs.opengeospatial.org/is/17-069r3/17-069r3.html 
+* [[OARec-1]] OGC 20-004: *OGC API - Records - Part 1: Core*, https://docs.ogc.org/DRAFTS/20-004.html
+* [[OAFeat-3]] OGC 19-079: *OGC API - Features - Part 3: Filtering*, https://docs.ogc.org/DRAFTS/19-079r1.html
+* [[CQL2]] OGC 21-065: *Common Query Language (CQL2)*, https://docs.ogc.org/DRAFTS/21-065.html
+* [[OpenAPI]] Open API Initiative: *OpenAPI Specification 3.0.3*, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md[OpenAPI]
+* [[schema.org]] *Schema.org*: https://schema.org/docs/schemas.html[Schema.org]
+* [[HTML5]] W3C: *HTML5*, W3C Recommendation, https://www.w3.org/TR/html5/[HTML5]

extensions/facets/standard/clause_4_terms_and_definitions.adoc

@@ -0,0 +1,10 @@
+== Terms and Definitions
+This document uses the terms defined in Sub-clause 5 of https://docs.ogc.org/DRAFTS/19-072.html[OGC API - Common Part 1] (OGC 19-072), which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word "shall" (not "must") is the verb form used to indicate a requirement to be strictly followed to conform to this Standard.
+
+For the purposes of this document, the following additional terms, definitions and abbreviated terms apply in addition to those defined in <<OARec-1,OGC API - Records - Part 1: Core>>.
+
+=== bucket
+A means to partition a domain of terms, ranges or queries into logical groups.
+
+=== facet
+A high-level piece of information that is computed over a set of records in a collection.

extensions/facets/standard/clause_5_conventions.adoc

@@ -0,0 +1,28 @@
+== Conventions and background
+
+=== General remarks
+
+See <<OARec-1,OGC API - Records - Part 1: Core>>, Clauses 5 and 6.
+
+=== Identifiers
+
+The normative provisions in this standard are denoted by the URI `http://www.opengis.net/spec/ogcapi-records-2/1.0`.
+
+All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.
+
+=== Sequence diagrams
+
+This document uses sequence diagrams to illustrate the flow of requests and responses 
+between client and server.
+
+The token `<resources endpoint>` is used for an endpoint that accesses
+resources from a collection. 
+
+EXAMPLE 1: For features, these endpoints are described by the 
+URI template `{landingPageUri}/collections/{collectionId}/items`. See <<OAFeat-1,OGC API - Features - Part 1: Core>>.
+
+The token `<resource endpoint>` is used for the endpoint that accesses a specific 
+resource from a collection.
+
+EXAMPLE 3: For features, these endpoints are described by the 
+URI template `{landingPageUri}/collections/{collectionId}/items/{featureId}`. See <<OAFeat-1,OGC API - Features - Part 1: Core>>.

extensions/facets/standard/clause_6_simple_facets.adoc

@@ -0,0 +1,8 @@
+[[simple_clause]] 
+== Requirements Class "Simple Facets"
+
+=== Overview
+
+include::requirements/requirements_class_simple.adoc[]
+
+include::requirements/simple/REQ_simple-conformance.adoc[]

extensions/facets/standard/clause_7_advanced_facets.adoc

@@ -0,0 +1,8 @@
+[[advanced_clause]] 
+== Requirements Class "Advanced Facets"
+
+=== Overview
+
+include::requirements/requirements_class_advanced.adoc[]
+
+include::requirements/advanced/REQ_advanced-conformance.adoc[]

extensions/facets/standard/clause_8_security.adoc

@@ -0,0 +1,4 @@
+[[security-section]]
+== Security Considerations
+
+See <<OARec-1,OGC API - Records - Part 1: Core>>, Clause 10.