Merge pull request #6 from opengeospatial/master

Merge from master branch.

.gitignore

@@ -1,2 +1,3 @@
 .DS_Store
 Thumbs.db
+*.code-workspace

extensions/cql/standard/19-079.adoc

@@ -34,7 +34,7 @@
 |Version: link:http://docs.opengeospatial.org/DRAFTS/19-079.html[1.0.0-SNAPSHOT (Editor's draft)]
 |Latest Published Draft: n/a
 |Category: OGC(R) Implementation Specification
-|Editors: TBD
+|Editors: Panagiotis (Peter) A. Vretanos, Clemens Portele
 |===
 
 [cols = "^", frame = "none"]
@@ -45,7 +45,7 @@
 [cols = "^", frame = "none", grid = "none"]
 |===
 |*Copyright notice*
-|Copyright (C) 2019 Open Geospatial Consortium
+|Copyright (C) 2020 Open Geospatial Consortium
 |To obtain additional rights of use, visit http://www.opengeospatial.org/legal/
 |===
 

extensions/cql/standard/annex_ats.adoc

@@ -3,4 +3,4 @@
 :appendix-caption: Annex
 == Abstract Test Suite (Normative)
 
-(( add test cases ))
+NOTE: Add conformance classes and test cases for all requirements classes and requirements once the requirements are final.

extensions/cql/standard/annex_bibliography.adoc

@@ -3,6 +3,10 @@
 [[Bibliography]]
 = Bibliography
 
-* [[OAFeat-Guide]] Heazel, Ch.: *Guide to OGC API - Features*, https://example.org/fixme
-* [[OpenAPI]] Open API Initiative: *OpenAPI Specification 3.0.2*,
-https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
+* [[BNF]] Internet Engineering Task Force (IETF). RFC 5234: **Augmented BNF for Syntax Specifications: ABNF** [online]. Edited by D. Crocker, P. Overell. 2008 [viewed 2020-11-22]. Available at https://tools.ietf.org/rfc/rfc5234.txt
+
+* [[JSONSCHEMA]] Internet Engineering Task Force (IETF). draft-handrews-json-schema-02: **JSON Schema: A Media Type for Describing JSON Documents** [online]. Edited by A. Wright, H. Andrews, B. Hutton, G. Dennis. 2019 [viewed 2020-11-22]. Available at https://tools.ietf.org/id/draft-handrews-json-schema-02.txt
+
+* [[JSONSCHEMAVALIDATION]] Internet Engineering Task Force (IETF). draft-handrews-json-schema-validation-02: **JSON Schema Validation: A Vocabulary for Structural Validation of JSON** [online]. Edited by A. Wright, H. Andrews, B. Hutton. 2019 [viewed 2020-11-22]. Available at https://tools.ietf.org/id/draft-handrews-json-schema-validation-02.txt
+
+* [[OpenAPI]] OpenAPI Initiative (OAI). **OpenAPI Specification 3.0** [online]. 2020 [viewed 2020-03-16]. The latest patch version at the time of publication of this standard was 3.0.3, available at http://spec.openapis.org/oas/v3.0.3

extensions/cql/standard/annex_bnf.adoc

@@ -2,6 +2,7 @@
 :appendix-caption: Annex
 
 [[cql-bnf]]
+[reftext="CQL BNF"]
 == CQL BNF (Normative)
 
 [source,abnf]

extensions/cql/standard/annex_js.adoc

@@ -1,16 +1,22 @@
 [appendix]
 :appendix-caption: Annex
 
-== JSON Schema for CQL (Normative)
+== JSON schemas for CQL (Normative)
 
-The following document specifies the JSON Schema for CQL according to the JSON Schema version '2019-09':
+[[cql-json-schema]]
+=== JSON Schema for CQL 
+
+The following document specifies the schema for CQL according to JSON Schema version '2019-09':
 
 [source,json]
 ----
 include::schema/cql.json[]
 ----
 
-The following document specifies the schema for CQL as an OpenAPI 3.0 schema:
+[[cql-openapi30-schema]]
+=== OpenAPI 3.0 schema for CQL 
+
+The following document specifies the schema for CQL as an OpenAPI 3.0 schema in YAML:
 
 [source,yaml]
 ----

extensions/cql/standard/clause_0_front_material.adoc

@@ -9,34 +9,39 @@ features on the Web. OGC API Features is comprised of multiple parts, each
 of them is a separate standard.
 
 A fundamental operation performed on a collection of resources is that of
-querying in order to obtain a subset of the data which contains resource
-instances that satisfy some filtering criteria.  This part, part 4, defines
-an encoding for specifying enhanced filtering criteria in a request to a server,
-beyond what is supported in the core called the  `Common Query Language`.
-
-The common query language defined in this document is used to specify how
-resource instances in a source collection should be filter to identify a
-result set.  Typically, CQL is used in query operations to identify the
+filtering in order to obtain a subset of the data which contains resource
+instances that satisfy some filtering criteria.  This part, part 3, defines
+
+* query parameters (`filter`, `filter-lang`, `filter-crs`) to specify filter
+criteria in a request to an API;
+* a filter grammar called Common Query Language (CQL) for specifying enhanced
+filtering criteria beyond what is supported in the Core;
+* two encodings for CQL - a text and a JSON encoding.
+
+The Common Query Language (CQL) defined in this document can be used to specify
+how resource instances in a source collection can be filtered to identify a
+result set. Typically, CQL is used in query operations to identify the
 subset of resources that should be included in a response document.
-However, CQL may also be used in other operations (e.g. updates) to
-identify the subset of resources that  should be affected by an operation.
+However, CQL can also be used in other operations (e.g. updates) to
+identify the subset of resources that should be affected by an operation.
 
-Each resource instance in the source collection is evaluated using a filtering
-expression encoded using the common query language.  The overall filter
-expression always evaluates to `true` or `false`.  If the expression evaluates
-to true, the resource instance satisfies the expression and is marked as being
-in the result set. If the overall filter expression evaluates to false, the data
-instance is not in the result set.  Thus, the net effect of evaluating a filter
-expression is a set of resources that satisfy the predicates in the expression.
+Each resource instance in the source collection is evaluated against a filtering
+expression. The filter expression always evaluates to `true` or `false`. If the
+expression evaluates to true, the resource instance satisfies the expression and
+is marked as being in the result set. If the overall filter expression evaluates
+to false, the data instance is not in the result set.  Thus, the net effect of
+evaluating a filter expression is a set of resources that satisfy the predicates
+in the expression.
 
-CAUTION: This is a DRAFT version of the nth part of the OGC API - Features standards. This draft is not complete and there are open issues that are still under discussion.
+CAUTION: This is a DRAFT version of the 3rd part of the OGC API - Features standards.
+This draft is not complete and there are open issues that are still under discussion.
 
 [big]*ii.    Keywords*
 
 The following are keywords to be used by search engines and document catalogues.
 
 common query language, filter, expression, query, SQL, CQL, where clause,
-selection clause, 
+selection clause, OGC API
 
 [big]*iii.   Preface*
 
@@ -50,15 +55,13 @@ The following organizations submitted this document to the Open Geospatial Conso
 
 * CubeWerx Inc.
 * interactive instruments GmbH
-* Heazeltech LLC
 
 [big]*v.     Submitters*
 
 All questions regarding this submission should be directed to the editors or the submitters:
 
 |===
 |*Name* |*Affiliation*
-|Panagiotis (Peter) A. Vretanos (editor)_ |CubeWerx Inc.
+|Panagiotis (Peter) A. Vretanos _(editor)_ |CubeWerx Inc.
 |Clemens Portele _(editor)_ |interactive instruments GmbH
-|Charles Heazel _(editor)_ |Heazeltech LLC
 |===

extensions/cql/standard/clause_10_encodings.adoc

@@ -3,18 +3,19 @@
 
 === Overview
 
-This clause specifies requirements for a text encoding and a JSON encoding of
-Simple CQL.
+This clause specifies requirements for a text encoding and a JSON encoding of CQL.
 
 [[cql-text]] 
 === Requirements Class "CQL Text"
 
 include::requirements/requirements_class_cql-text.adoc[]
 
-This requirements class defines a well know text encoding of CQL. Such an
-encoding would be suitable for use with the a GET query parameter such as
+This requirements class defines a well known text encoding of CQL. Such an
+encoding would be suitable for use with the a GET query parameter such as the
 <<rc_filter,`filter`>> parameter.
 
+include::requirements/cql-text/REQ_filter-lang.adoc[]
+
 include::requirements/cql-text/REQ_simple-cql.adoc[]
 
 include::requirements/cql-text/REQ_enhanced-spatial-operators.adoc[]
@@ -23,24 +24,41 @@ include::requirements/cql-text/REQ_enhanced-temporal-operators.adoc[]
 
 include::requirements/cql-text/REQ_functions.adoc[]
 
+The list of supported functions can be discovered via the Functions resource (i.e. path `/functions`).
+
 include::requirements/cql-text/REQ_arithmetic.adoc[]
 
+include::requirements/cql-text/REQ_arrays.adoc[]
+
 [[cql-json]]
 === Requirements Class "CQL JSON"
 
 include::requirements/requirements_class_cql-json.adoc[]
 
-This requirements class defines a JSON encoding of Simple CQL. Such an encoding
+This requirements class defines a JSON encoding of CQL. Such an encoding
 would be suitable as the body of an HTTP POST request.
 
+include::requirements/cql-json/REQ_filter-lang.adoc[]
+
 include::requirements/cql-json/REQ_simple-cql.adoc[]
 
-NOTE: Attention is drawn to the fact that there exists an alternative JSON encoding for CQL based on the use of arrays that can be found here: https://github.com/tschaub/ogcapi-features/tree/json-array-expression/extensions/cql/jfe.  The SWG will need to review both encodings and decide which one to adopt.
+NOTE: Attention is drawn to the fact that there exists an alternative JSON encoding for CQL based on the use of arrays that can be found here: https://github.com/tschaub/ogcapi-features/tree/json-array-expression/extensions/cql/jfe. The SWG will review both encodings and decide which one to adopt, feedback from implementations is welcome.
 
 include::requirements/cql-json/REQ_enhanced-spatial-operators.adoc[]
 
 include::requirements/cql-json/REQ_enhanced-temporal-operators.adoc[]
 
 include::requirements/cql-json/REQ_functions.adoc[]
 
+The list of supported functions can be discovered via the Functions resource (i.e. path `/functions`).
+
 include::requirements/cql-json/REQ_arithmetic.adoc[]
+
+include::requirements/cql-json/REQ_arrays.adoc[]
+
+[[cql-xml]]
+=== XML encoding 
+
+This specification does not specifically define an XML-encoding for CQL.
+However, it is recognized that XML is still in common use and so
+implementors are directed to review the http://docs.opengeospatial.org/is/09-026r2/09-026r2.html[OGC Filter Encoding 2.0] standard which defines a XML-encoding for filter expressions that closely matches most of the functionality of CQL.

extensions/cql/standard/clause_1_scope.adoc

@@ -6,13 +6,12 @@ enhanced filtering capabilities expressed using a common query language (CQL).
 
 Enhanced filtering capabilities in this case means that the server supports
 the ability to define selection clauses using predicates beyond those supported
-by the OGC API Common specification (i.e. bbox and datetime).
+by part 1 (i.e., `bbox` and `datetime`).
 
-This document defines a text encoding for a CQL filter suitable for use as a 
-query parameter in a URL.
+This document defines
 
-This document defines a JSON encoding for a CQL filter suitable for use in a 
-HTTP POST body.
-
-This document defines the schema for a JSON document that exposes the set of 
-properties or keys that may be used to construct CQL expressions.
+* query parameters for specifying a filter in a request to a Web API;
+* a text encoding for a CQL filter suitable for use as a query parameter in a URL;
+* a JSON encoding for a CQL filter suitable for use in a HTTP POST body;
+* how the set of properties or keys that can be used to construct CQL expressions
+("queryables") are published by a Web API.

extensions/cql/standard/clause_2_conformance.adoc

@@ -17,24 +17,27 @@ parameters that may be used to specify complex filter expressions on
 HTTP requests.  The specific set of parameters defined in this conformance
 class are:
 
-* filter
-* filter-lang
-* filter-crs
+* `filter` (the filter expression)
+* `filter-lang` (the language used in the filter expression)
+* `filter-crs` (the coordinate reference system used in the filter expression)
 
-This conformance class also defined the resources `/queryables` and
-`/collections/{collectionId}/queryables` that can be used to determine
-the list of property names and types that may be used to construct filter
-expressions.
+This conformance class also defines the Queryables resource (at paths
+`/queryables` and `/collections/{collectionId}/queryables`) that can be
+used to determine the list of property names and types that may be used
+to construct filter expressions.
 
 The <<rc_features-filter,Features Filter>> conformance class defines the
-binding between this the <<rc_filter,Filter>> conformance class the 
+binding between this the <<rc_filter,Filter>> conformance class the
 <<OAFeat-1,OGC API - Features - Part 1: Core>> standard.
 
-The <<rc_simple-cql,Simple CQL>> conformance class defines the Simple Common
-Query Language (CQL). Simple CQL is intended to be a minimal useful set of
+The <<rc_simple-cql,Simple CQL>> conformance class defines the minimal subset
+of the Common Query Language (CQL) that all implementations have to support
+("Simple CQL"). Simple CQL is intended to be a minimal useful set of
 predicates that support enhanced fine-grained read-access to collections of
-resources.  In this case `enhanced` means filtering capabilities beyond those
-supported by the core OGC API Common specification (i.e. bbox and datetime).
+resources.  In this case "enhanced" means filtering capabilities beyond those
+supported by the core OGC API Common specification (i.e., `bbox`, `datetime`
+and optionally collection-specific properties).
+
 The specific set of operators defined in this conformance class are:
 
 * Logical operators:
@@ -52,7 +55,7 @@ The specific set of operators defined in this conformance class are:
 ** between
 ** in
 * Spatial operators:
-** intersects.
+** intersects
 * Temporal operators:
 ** anyinteracts
 
@@ -73,8 +76,6 @@ additional spatial operators that must be supported is:
 * crosses
 * contains
 
-NOTE: Do we need to add DWITHIN and BEYOND?  I think no.
-
 The <<rc_enhanced-temporal-operators,Enhanced Temporal Operators>> conformance
 class specifies requirements for servers that support temporal operators in
 addition to the `anyinteracts` operator defined in the
@@ -97,23 +98,23 @@ additional temporal operators that must be supported is:
 * intersects
 
 The <<rc_functions,Functions>> conformance class specifies requirements for
-supporting function calls (e.g. min, max, etc.) in a CQL expression.  Function
-calls are the primary means of extending the language.  This conformance class
-also defined a resource `/functions` that may be used to discover the list of
-available functions.
+supporting function calls (e.g. min, max, etc.) in a CQL expression. Function
+calls are the primary means of extending the language. This conformance class
+also defined a Functions resource (at path `/functions`) that may be used to
+discover the list of available functions.
 
 The <<rc_arithmetic,Arithmetic operators>> conformance class specifies
 requirements for  supporting the standard set of arithmetic operators,
 latexmath:[+, -, *, /] in a CQL expression.
 
 The <<rc_cql-text,CQL Text encoding>> conformance class defines
-a text encoding for CQL.  Such an encoding is suitable for use with HTTP query
+a text encoding for CQL. Such an encoding is suitable for use with HTTP query
 parameters such as the `filter` parameter defined by the <<rc_filter,Filter>>
 conformance class.
 
 The <<rc_cql-json,CQL JSON encoding>> conformance class defines
-a JSON encoding for CQL.  Such as encoding is suitable for use with as the 
-body of an HTTP POST request. 
+a JSON encoding for CQL. Such as encoding is suitable for use with as the
+body of an HTTP POST request.
 
 Conformance with this standard shall be checked using all the relevant tests
 specified in <<ats,Annex A>> of this document. The framework, concepts, and
@@ -123,7 +124,7 @@ OGC Compliance Testing web site.
 
 == Roadmap
 
-The content of the clause is informative.  
+The content of the clause is informative.
 
 Because CQL is not exclusively useful for features, it is anticipated that the
 following conformance classes:
@@ -137,6 +138,6 @@ following conformance classes:
 * <<rc_cql-text,CQL Text encoding>>
 * <<rc_cql-json,CQL JSON encoding>>
 
-will eventually become parts of the `OGC API - Common` suite for standards thus
+will eventually become parts of the OGC API Common suite of standards thus
 leaving the <<rc_features-filter,Features Filter>> conformance class as part
-3 of the `OGC API - Features` specifications.
+3 of the OGC API Features specifications.

extensions/cql/standard/clause_3_references.adoc

@@ -1,15 +1,12 @@
 == 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.
 
-* [[OAFeat-1]] Portele, C., Vretanos, P.: OGC 17-069r2, *OGC API - Features - Part 1: Core*, http://example.com/fixme
+* [[OAFeat-1]] Open Geospatial Consortium (OGC). OGC 17-069r3: **OGC API - Features - Part 1: Core** [online]. Edited by C. Portele, P. Vretanos, C. Heazel. 2019 [viewed 2020-11-22]. Available at http://docs.opengeospatial.org/is/17-069r3/17-069r3.html
 
-* [[OGC16-071r3]] OGC 16-071r2, *Time Ontology in OWL*, https://www.w3.org/TR/owl-time
+* [[OAFeat-2]] Open Geospatial Consortium (OGC). OGC 18-058: **OGC API - Features - Part 2: Coordinate Reference Systems by Reference** [online]. Edited by C. Portele, P. Vretanos. 2020 [viewed 2020-12-03]. Available at http://docs.opengeospatial.org/is/18-058/18-058.html
 
-* [[ISO19125]] OGC 06-103r4, *OpenGIS® Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture*, http://portal.opengeospatial.org/files/?artifact_id=25355
+* [[ISO19125]] Open Geospatial Consortium (OGC). OGC 06-103r4: **OpenGIS® Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture** [online]. Edited by J. Herring. 2011 [viewed 2020-11-22]. Available at http://portal.opengeospatial.org/files/?artifact_id=25355
 
-* [[BNF]] Crocker, D.: RFC 5238, *Augmented BNF for Syntax Specifications: ABNF*
-
-* [[JSONSCHEMA]] Wright A., Andrews H., Hutton B., Dennis G.: draft-handrews-json-schema-02, *JSON Schema: A Media Type for Describing JSON Documents*
-
-* [[EGENHOFER]] Egenhofer, M.J., Herring, J.R., *A Mathematical Framework for the Definition of Topological Relationships*
+* [[OGC16-071r3]] Open Geospatial Consortium (OGC) / World Wide Web Consortium (W3C). OGC 16-071r3: **Time Ontology in OWL** [online]. Edited by S. Cox, C. Little. 2020 [viewed 2020-11-22]. Available at https://www.w3.org/TR/owl-time
 
+* [[EGENHOFER]] Egenhofer M.J., Herring J.R., **A Mathematical Framework for the Definition of Topological Relationships**, Fourth International Symposium on Spatial Data Handling, Zurich, Switzerland, July 1990

extensions/cql/standard/clause_4_terms_and_definitions.adoc

@@ -1,16 +1,18 @@
-== Terms and Definitions
+== Terms, Definitions and Symbols
+
+=== Terms and Definitions
 This document uses the terms defined in Sub-clause 5.3 of [OGC 06-121r9], 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 and definitions apply in addition to the terms defined
 in <<OAFeat-1,OGC API - Features - Part 1: Core>>.
 
-=== term 1
-definition [source]
+==== filter
+**predicate** encoded for transmission between systems
 
-=== term 2
-definition [source]
+==== predicate
+set of computational operations applied to a data instance which evaluate to true or false [Filter Encoding 2.0.2]
 
-== Symbols
+=== Symbols
 
 * **&#x2229;** intersection, operation on two or more sets
 * **&#x2227;** and, logical intersection