opengeospatial · cportele · May 4, 2021 · Apr 30, 2021
diff --git a/standard/20-009.adoc b/standard/20-009.adoc
@@ -18,7 +18,7 @@
 :source-highlighter: pygments
 :pygments-style: borland
 :pygments-linenums-mode: table
-:copyrightYear: 2020
+:copyrightYear: 2021
 
 :category: OGC(R) Implementation Standard
 :doc-type: IS
@@ -109,7 +109,9 @@ include::clause_6_introduction.adoc[]
 
 include::clause_7_styles-api.adoc[]
 
+////
 include::clause_8_collection-extensions.adoc[]
+////
 
 include::clause_9_media_types.adoc[]
 

diff --git a/standard/annex-a.adoc b/standard/annex-a.adoc
@@ -2,6 +2,10 @@
 :appendix-caption: Annex
 == Conformance Class Abstract Test Suite (Normative)
 
+#TODO: The ATS needs to be updated and has been commented out until the changes to the requirements classes are under discussion.#
+
+////
+
 === Conformance Class "Core"
 
 ==== Test Case 1
@@ -316,3 +320,4 @@ Otherwise skip the test.
 3. Validate the contents of the returned document against the schema in /req/queryables/success, item B, if the `itemType` is `feature`.
 4. Verify that each queryable id `#/queryables/{i}/id` (where `{i}` is the index of the queryable in the array) is unique.
 |===
+////
diff --git a/standard/annex-bibliography.adoc b/standard/annex-bibliography.adoc
@@ -4,5 +4,5 @@
 = Bibliography
 
 1. [[geojson]] link:https://tools.ietf.org/html/rfc7946[IETF: RFC 7946 - The GeoJSON Format]
-2. [[t15_d011]] link:http://docs.opengeospatial.org/per/19-023r1.html[OGC: OGC Testbed-15: Encoding and Metadata Conceptual Model for Styles Engineering Report. OGC 19-023, Open Geospatial Consortium (2019)]
+2. [[t15_d011]] link:https://docs.ogc.org/per/19-023r1.html[OGC: OGC Testbed-15: Encoding and Metadata Conceptual Model for Styles Engineering Report. OGC 19-023, Open Geospatial Consortium (2019)]
 3. [[mbstyle]] link:https://docs.mapbox.com/mapbox-gl-js/style-spec/[Mapbox: Mapbox Style Specification, Version 8]
diff --git a/standard/annex-history.adoc b/standard/annex-history.adoc
@@ -6,4 +6,5 @@
 |===
 |Date |Editor |Release |Primary clauses modified |Description
 |February 19, 2020 |C. Portele | 1.0.0-SNAPSHOT |all |initial version, derived from the [OGC Testbed-15: Styles API Engineering Report](http://docs.opengeospatial.org/per/19-010r2.html)
+|April 30, 2021 |C. Portele | 1.0.0-SNAPSHOT |all |major update based on discussions in SWG meeting on April 20, 2021 
 |===
diff --git a/standard/clause_0_front_material.adoc b/standard/clause_0_front_material.adoc
@@ -1,10 +1,12 @@
 [big]*i.     Abstract*
 
-This document is the draft OGC API - Styles specification that defines a Web API that enables map servers and clients as well as visual style editors to manage and fetch styles.
+This document is the first part of the candidate standard OGC API - Styles that defines API building blocks for Web APIs to enable map servers and clients as well as visual style editors to manage and fetch styles.
 
 Web APIs are software interfaces that use an architectural style that is founded on the technologies of the Web.
 Styles consist of symbolizing instructions that are applied by a rendering engine on features and/or coverages.
 
+This document uses "Styles API" to refer to a Web API that implements API building blocks specified in this candidate standard.
+
 A Styles API supports several types of consumers, mainly:
 
 * Visual style editors that create, update and delete styles for datasets that are shared by other Web APIs implementing the OGC API - Features - Part 1: Core standard or the draft OGC API - Coverages or draft OGC API - Tiles specifications;
@@ -13,9 +15,7 @@ A Styles API supports several types of consumers, mainly:
 
 Feature data is either accessed directly or organized into spatial partitions such as a tiled data store (aka "vector tiles").
 
-The Styles API is consistent with the emerging OGC API family of standards.
-
-The Styles API implements the conceptual model for style encodings and style metadata as documented
+The API building blocks implement the conceptual model for styles, style encodings and style metadata as documented
 in link:http://docs.opengeospatial.org/per/19-023r1.html#Metadata[chapter 6] of the "OGC Testbed-15: Encoding and Metadata Conceptual Model for Styles Engineering Report".
 
 The model defines three main concepts:
@@ -29,8 +29,12 @@ and their preferences.
 information about the style, structural information (e.g., layers and attributes),
 and so forth to allow users to discover and select existing styles for their data.
 
-This model directly maps to the resources and documents in the Styles API,
+This model directly maps to the resources and documents in a Styles API,
 which supports the resources and operations listed in the Table below.
+The `baseResource` is any API resource with which styles can be associated.
+For a general purpose Styles API this will typically be the Landing Page.
+For styles associated with a feature collection published via an API implementing
+OGC API Features, the base resource would be the Collection (path `/collections/{collectionId}`).
 
 [#tldr1,reftext='{table-caption} {counter:table-num}']
 .Styles API - overview of resources and applicable HTTP methods
@@ -39,34 +43,24 @@ which supports the resources and operations listed in the Table below.
 |Resource |Path |HTTP method |Document reference
 |Landing page |`/` |GET |<<landing_page>>
 |Conformance declaration |`/conformance` |GET |<<conformance_declaration>>
-.3+|Styles .3+|`/styles` |GET |<<get_styles>>
+.3+|Styles .3+|`{baseResource}/styles` |GET |<<get_styles>>
 .2+|POST |<<create_style>>
 |<<style_validate>>
-.4+|Style .4+|`/styles/{styleId}` |GET |<<get_style>>
+.4+|Style .4+|`{baseResource}/styles/{styleId}` |GET |<<get_style>>
 .2+|PUT |<<update_style>>
 |<<style_validate>>
 |DELETE |<<delete_style>>
-.3+|Style metadata .3+|`/styles/{styleId}/metadata` |GET |<<get_style_metadata>>
+.3+|Style metadata .3+|`{baseResource}/styles/{styleId}/metadata` |GET |<<get_style_metadata>>
 |PUT |<<update_style_metadata>>
 |PATCH |<<patch_style_metadata>>
+!===
+
+////
 |Resources |`/resources` |GET |<<get_resources>>
-.3+|Resource .3+|`/resources/{resourceId}` |GET |<<get_resource>>
+.3+|Resource .3+|`{baseResource}/resources/{resourceId}` |GET |<<get_resource>>
 |PUT |<<update_resource>>
 |DELETE |<<delete_resource>>
-!===
-
-In order to support styles, data APIs (for example, supporting OGC API Features
-and/or the draft OGC API Tiles) require additional capabilities, too. These are:
-
-* List and manage the applicable styles per feature collection
-(path `/collections/{collectionId}`).
-* Add a `queryables` resource (path `/collections/{collectionId}/queryables`)
-to support clients such as visual style editors to construct expressions for
-selection criteria in queries on features in the collection. "Queryable" means
-that the property may be used in styling rules or other filter expressions.
-
-To support styling of coverage data, other additional capabilities in the
-data API may be required, but have not been investigated by Testbed 15.
+////
 
 This document uses link:http://spec.openapis.org/oas/v3.0.2[OpenAPI 3.0]
 to specify the building blocks of the API.
@@ -83,12 +77,10 @@ ____
 
 The following are keywords to be used by search engines and document catalogues.
 
-ogcdoc, OGC document, OpenAPI, OGC API, style, style encoding, style metadata, Styles API
+ogcdoc, OGC document, OpenAPI, OGC API, style, style encoding, stylesheet, style metadata, Styles API
 
 [big]*iii.   Preface*
 
-OGC is currently missing a robust conceptual model and APIs capable of supporting styles with multiple style encodings (for example OGC SLD and Mapbox Style). This document specifies building blocks for Web APIs consistent with the OGC API series to manage and fetch styles.
-
 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 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 draft specification set forth in this document, and to provide supporting documentation.

diff --git a/standard/clause_1_scope.adoc b/standard/clause_1_scope.adoc
@@ -5,6 +5,3 @@ OGC API Styles specifies building blocks for Web APIs that enables map servers a
 The API is part of the emerging OGC API family of standards. The API complements the current and emerging OGC API specifications for features, maps and tiles and builds on the conceptual model for the encoding of styles and their metadata developed in OGC Testbed-15.
 
 The building blocks of the API are specified using OpenAPI 3.0.
-
-CAUTION: TODO +
-We need to decide and clarify the terminology. Currently, "Styles API" is used for all building blocks under `/styles` and `/resources` (Clause 7), while Clause 8 specifies additional building blocks for data resources under `/collections`. Note that the queryables (`/collections/{collectionId}/queryables`) are a general concept and should be moved to OGC API Common or OGC API Features.
diff --git a/standard/clause_2_conformance.adoc b/standard/clause_2_conformance.adoc
@@ -1,24 +1,21 @@
 == Conformance
-This draft specification defines five requirements/conformance classes for the Styles API:
+This draft specification defines five requirements/conformance classes for the Styles API building blocks:
 
-* "core" provides access to styles and their metadata. JSON is a mandatory encoding in requests and responses where JSON schemas have been specified for the Styles API.
-* "manage-styles" adds the capabilities for creating, updating and deleting styles and their metadata.
-* "style-validation" adds the capability to validate a stylesheet.
-* "resources" add the capabilities to provide access to resources referenced from stylesheets (symbols, sprites) or style metadata (thumbnails).
-* "manage-resources" add the capabilities for creating, updating and deleting resources.
+* "core" provides access to styles and their metadata. JSON is a mandatory encoding in requests and responses where JSON schemas have been specified for the Styles API.
+* "manage-styles" adds the capabilities for creating, updating and deleting styles and their metadata.
+* "style-validation" adds the capability to validate a stylesheet.
 
-In addition, there are four requirements/conformance classes for additional encodings supported by resources of the API:
+////
+* "resources" add the capabilities to provide access to resources referenced from stylesheets (symbols, sprites) or style metadata (thumbnails).
+* "manage-resources" add the capabilities for creating, updating and deleting resources.
+////
+
+In addition, there are three requirements/conformance classes for style encodings supported by resources of the API:
 
-* "html" supports HTML in responses to GET requests for all requests to the Styles API.
 * "mapbox-styles" supports Mapbox Styles as a style encoding.
 * "sld-10" supports OGC SLD 1.0 as a style encoding.
 * "sld-11" supports OGC SLD 1.1 as a style encoding.
 
-Finally, there are two requirements/conformance classes extending the information about Collection resources specified in OGC API - Features - Part 1: Core:
-
-* "style-info" adds information about available styles for each collection.
-* "queryables" adds information about the feature properties that may be used in styling rules.
-
 The standardization target for all classes is: Web API.
 
 Conformance with this draft specification shall be checked using all the relevant tests specified in Annex A (normative) 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.

diff --git a/standard/clause_3_references.adoc b/standard/clause_3_references.adoc
@@ -1,22 +1,24 @@
 == 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.
 
-[[rfc7396]]
-link:https://tools.ietf.org/rfc/rfc7396.txt[IETF: RFC 7396, JSON Merge Patch (2014)]
+* [[rfc7240]] Internet Engineering Task Force (IETF). RFC 7240: **Prefer Header for HTTP** [online]. Edited by J. Snell. 2014 [viewed 2021-04-13]. Available at http://tools.ietf.org/rfc/rfc7240.txt
 
-[[sld10]]
-link:http://portal.opengeospatial.org/files/?artifact_id=1188[OGC: OGC 02-070, Styled Layer Descriptor, Version 1.0 (2002)]
+* [[rfc7396]] Internet Engineering Task Force (IETF). RFC 7396: **JSON Merge Patch** [online]. Edited by P. Hoffman, J. Snell. 2014 [viewed 2021-01-25]. Available at http://tools.ietf.org/rfc/rfc7396.txt
 
-[[sld11]]
-link:http://portal.opengeospatial.org/files/?artifact_id=22364[OGC: OGC 05-078r4, Styled Layer Descriptor, Version 1.1 (2007)]
+* [[sld10]] Open Geospatial Consortium (OGC). OGC 02-070: **Styled Layer Descriptor, Version 1.0** [online]. Edited by W. Lalonde. 2021 [viewed 2021-04-28]. Available at http://portal.opengeospatial.org/files/?artifact_id=1188
 
-[[oapif-1]]
-link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html[OGC: OGC 17-069r3, OGC API - Features - Part 1: Core (2019)]
+* [[sld11]] Open Geospatial Consortium (OGC). OGC 05-078r4: **Styled Layer Descriptor profile of the Web Map Service Implementation Specification, Version 1.1** [online]. Edited by M. Lupp. 2021 [viewed 2021-04-28]. Available at http://portal.opengeospatial.org/files/?artifact_id=22364
 
-[NOTE]
-====
-If "OGC API - Common" would be available and consistent with "OGC API - Features - Part 1: Core", "OGC API - Common" would be a normative reference instead of "OGC API - Features - Part 1: Core".
-====
+* [[CommonCore]] Open Geospatial Consortium (OGC). OGC 19-072: **OGC API - Common - Part 1: Core (DRAFT)** [online]. Edited by Ch. Heazel. 2021 [viewed 2020-03-16]. Available at https://portal.ogc.org/files/?artifact_id=97330
 
-[[html]]
-link:https://html.spec.whatwg.org/[WhatWG: HTML (Living Standard)]
+////
+* [[OAFeat-1]] Open Geospatial Consortium (OGC). **OGC API - Features - Part 1: Core 1.0** [online]. Edited by C. Portele, P. Vretanos, C. Heazel. 2019 [viewed 2020-05-24]. Available at http://www.opengis.net/doc/IS/ogcapi-features-1/1.0
+////
+
+* [[OAFeat-4]] Open Geospatial Consortium (OGC). **OGC API - Features - Part 4: Create, Replace, Update and Delete (DRAFT)** [online]. Edited by C. Portele, P. Vretanos. 2021 [viewed 2021-04-29]. Available at https://docs.ogc.org/DRAFTS/20-002.html
+
+* [[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
+
+////
+* [[HTML5]] WHATWG. *HTML*, Living Standard [online, viewed 2020-03-16]. Available at https://html.spec.whatwg.org/
+////
diff --git a/standard/clause_4_terms_and_definitions.adoc b/standard/clause_4_terms_and_definitions.adoc
@@ -23,6 +23,9 @@ representation of a style in a style encoding
 === style metadata
 essential information about a style in order to support users in discovering and selecting styles for rendering their data and for visual style editors to create user interfaces for editing a style
 
+=== Styles API
+Web API conforming to OGC API - Styles - Part 1: Core
+
 === Web API
 API using an architectural style that is founded on the technologies of the Web [source: OGC API - Features - Part 1: Core]
 

diff --git a/standard/clause_5_conventions.adoc b/standard/clause_5_conventions.adoc
@@ -1,10 +1,12 @@
 == Conventions
 This section provides details and examples for any conventions used in the document. Examples of conventions are symbols, abbreviations, use of XML schema, or special notes regarding how to read the document.
 
+#TODO: add information about the use of OpenAPI 3.0, link relation types, etc.#
+
 === Identifiers
 The normative provisions in this draft specification are denoted by the URI
 
-http://www.opengis.net/t15/opf-styles-1/{m_n}
+http://www.opengis.net/spec/ogcpapi-styles-1/1.0
 
 All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.