From 38e84de1952b37ae26dec3f50812259392284fa1 Mon Sep 17 00:00:00 2001 From: Clemens Portele Date: Fri, 30 Apr 2021 16:17:15 +0200 Subject: [PATCH] update all sections - updated requirements so that a Styles resource is not tied to the landing page and can also be, for example, associated with a feature collection resource (closes #1, starts to address #8) - use of Common Core instead of referencing Features Core - use of the general req classes Create/Replace/Delete and Update currently in Feature Part 4 as the basis for the req class `manage-styles` - use of `Prefer` header preference "handling" in the req class `style-validation` - editorial updates and clarifications - removed req classes for file resources, this is not really necessary and such a capability can be implemented in various ways without interoperability issues - removed req classes `queryables` (no longer needed - tiles and features have mechanisms to describe the schemas of attributes) and `style-info` (no longer needed) --- standard/20-009.adoc | 4 +- standard/annex-a.adoc | 5 + standard/annex-bibliography.adoc | 2 +- standard/annex-history.adoc | 1 + standard/clause_0_front_material.adoc | 44 +- standard/clause_1_scope.adoc | 3 - standard/clause_2_conformance.adoc | 23 +- standard/clause_3_references.adoc | 30 +- standard/clause_4_terms_and_definitions.adoc | 3 + standard/clause_5_conventions.adoc | 4 +- standard/clause_6_introduction.adoc | 58 +- standard/clause_7_styles-api.adoc | 574 +++++++++--------- .../requirements/requirements_class_core.adoc | 4 +- .../requirements_class_manage-styles.adoc | 6 +- .../requirements_class_mapbox-style.adoc | 4 +- .../requirements_class_sld-10.adoc | 6 +- .../requirements_class_sld-11.adoc | 6 +- .../requirements_class_style-validation.adoc | 3 +- 18 files changed, 398 insertions(+), 382 deletions(-) diff --git a/standard/20-009.adoc b/standard/20-009.adoc index 99af6fc..32fcdde 100644 --- 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 index 3a21f0e..545f9b1 100644 --- 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. |=== +//// \ No newline at end of file diff --git a/standard/annex-bibliography.adoc b/standard/annex-bibliography.adoc index 9944f4b..b82cdc7 100644 --- 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 index cafa5dc..312b1f5 100644 --- 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 index 51d6678..2b79675 100644 --- 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 |<> |Conformance declaration |`/conformance` |GET |<> -.3+|Styles .3+|`/styles` |GET |<> +.3+|Styles .3+|`{baseResource}/styles` |GET |<> .2+|POST |<> |<> -.4+|Style .4+|`/styles/{styleId}` |GET |<> +.4+|Style .4+|`{baseResource}/styles/{styleId}` |GET |<> .2+|PUT |<> |<> |DELETE |<> -.3+|Style metadata .3+|`/styles/{styleId}/metadata` |GET |<> +.3+|Style metadata .3+|`{baseResource}/styles/{styleId}/metadata` |GET |<> |PUT |<> |PATCH |<> +!=== + +//// |Resources |`/resources` |GET |<> -.3+|Resource .3+|`/resources/{resourceId}` |GET |<> +.3+|Resource .3+|`{baseResource}/resources/{resourceId}` |GET |<> |PUT |<> |DELETE |<> -!=== - -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 index c6c3ada..5c92e56 100644 --- 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 index c71b510..5c773f5 100644 --- 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 index d5996f9..ccdd604 100644 --- 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/ +//// \ No newline at end of file diff --git a/standard/clause_4_terms_and_definitions.adoc b/standard/clause_4_terms_and_definitions.adoc index e438505..f2a061e 100644 --- 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 index 0dc2566..f98664c 100644 --- 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. diff --git a/standard/clause_6_introduction.adoc b/standard/clause_6_introduction.adoc index b5182e3..513c222 100644 --- a/standard/clause_6_introduction.adoc +++ b/standard/clause_6_introduction.adoc @@ -3,7 +3,7 @@ [[Overview]] === Overview -This document specifies draft building blocks for Web APIs to manage and fetch styles supporting multiple style encodings and metadata to describe and discover styles. +This document specifies API building blocks for Web APIs to manage and fetch styles supporting multiple style encodings and metadata to describe and discover styles. The Styles API supports several types of consumers, mainly: @@ -13,23 +13,19 @@ The 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 remainder of this Clause illustrates use cases and workflows that a Styles API could support. -The remainder of this Clause illustrates use cases and workflows that the Styles API could support. - -Clause 7 specifies the Styles API. - -Clause 8 specifies extensions to OGC API - Features - Part 1: Core standard (or the emerging OGC API - Common specification) to support the use cases. +Clause 7 specifies the API building blocks. [[use-cases]] === Use cases -This section describes expectations of how clients will interact with the Styles API. +This section describes expectations of how clients will interact with a Styles API. The following use cases assume that: * Some feature dataset that is structured according to a data specification, such as the NGA Topographic Data Store 6.1 (TDS), is available via an API that implements the OGC API - Features - Part 1: Core and draft OGC API - Tiles specifications; -* Roads are included in the data in a collection `transportationgroundcrv` as features with a property f_code with a value of AP030; +* Roads are included in the data in a collection `TransportationGroundCrv` as features with a property f_code with a value of AP030; * The URI of the landing page is `http://example.org/data-api`; * A style repository is available via an API that implements the Styles API specification; * The URI of the landing page of the Styles API is `http://example.org/styles-api`. @@ -38,7 +34,7 @@ NOTE: The URIs in the use case descriptions are examples and use the domain `exa ==== A map client -A map client that wants to visualize data for features or tiled feature data for the collection `http://example.org/data-api/collections/transportationgroundcrv` will look for a `styles` member in the response. The client will probably select one of the styles from the list taking the media types of the supported stylesheets into account and provide a capability so that users can change the style. The stylesheet returned based on the `href` member of the link will be used to render the data. +A map client that wants to visualize data for features or tiled feature data for the collection `http://example.org/data-api/collections/TransportationGroundCrv` will look for a `styles` member in the response. The client will probably select one of the styles from the list taking the media types of the supported stylesheets into account and provide a capability so that users can change the style. The stylesheet returned based on the `href` member of the link will be used to render the data. In addition to feature data, the map client might also fetch a hillshade style to apply to an elevation coverage accessed from a Web API supporting OGC API Coverages. @@ -46,7 +42,7 @@ In addition to feature data, the map client might also fetch a hillshade style t A user wants to create a new style for TDS roads using a visual style editor. The user knows the dataset and the data access API. -A user creates the style in the visual style editor, selects the native stylesheet language for the style and identifies the `transportationgroundcrv` collection in the dataset as a sample data source. The visual style editor executes a request to the landing page (`http://example.org/data-api`) and the conformance declaration (`http://example.org/data-api/conformance`) of the data access API to determine the API capabilities. Note that alternatively the OpenAPI definition may be inspected, but for a client that supports the OGC API standards in general, using the API resources directly is often simpler and, therefore, used in this example. +A user creates the style in the visual style editor, selects the native stylesheet language for the style and identifies the `TransportationGroundCrv` collection in the dataset as a sample data source. The visual style editor executes a request to the landing page (`http://example.org/data-api`) and the conformance declaration (`http://example.org/data-api/conformance`) of the data access API to determine the API capabilities. Note that alternatively the OpenAPI definition may be inspected, but for a client that supports the OGC API standards in general, using the API resources directly is often simpler and, therefore, used in this example. If the visual style editor supports, for example, both the styling of GeoJSON features or Mapbox Vector Tile data, the editor would require support for at least one of the two following sets of conformance classes: @@ -54,16 +50,11 @@ If the visual style editor supports, for example, both the styling of GeoJSON fe or * `http://www.opengis.net/spec/ogcapi-tiles-1/1.0/conf/core` (with URI templates referencing tiles of media type `application/vnd.mapbox-vector-tile`). -The first option provides access to GeoJSON features via `http://example.org/data-api/collections/transportationgroundcrv/items`, the second one provides access to Mapbox Vector Tiles (MVT) encoded data via `http://example.org/data-api/collections/transportationgroundcrv/tiles`. - -In addition, the visual style editor will look for the following conformance classes: - -* `http://www.opengis.net/t15/opf-styles-1/1.0/conf/queryables`: If this conformance class is supported, the visual style editor can specify styling rules that make use of feature properties. Otherwise all styling rules will apply to all features in each collection. -* `http://www.opengis.net/t15/opf-styles-1/1.0/conf/style-info`: If this conformance class is supported, the visual style editor will be able to create a link from the collection to the newly created style. +The first option provides access to GeoJSON features via `http://example.org/data-api/collections/TransportationGroundCrv/items`, the second one provides access to Mapbox Vector Tiles (MVT) encoded data via `http://example.org/data-api/collections/TransportationGroundCrv/tiles`. -The editor will also request information about the features in the collection via a request to `http://example.org/data-api/collections/transportationgroundcrv`. +In addition, for feature data the visual style editor will look for the conformance class `http://www.opengis.net/spec/ogcapi-features-n/1.0/conf/tbd` to determine the properties of the features and their schema from `http://example.org/data-api/collections/TransportationGroundCrv/schema` in order to use feature attributes in styling rules. -If `http://www.opengis.net/t15/opf-styles-1/1.0/conf/queryables` is supported, the queryables are retrieved via a request to `http://example.org/data-api/collections/transportationgroundcrv/queryables`. +The editor will typically also request information about the features in the collection via a request to `http://example.org/data-api/collections/TransportationGroundCrv`. Based on this information, the visual style editor is able to configure its user interface and guide the user through the creation of the style for road features and visualize the draft style using the sample data. Once the user has finished the style, the style is published on a Style repository that supports the Styles API. @@ -71,38 +62,31 @@ If the user requests the use of a Style repository that the editor interacts wit At least the following conformance classes must be supported in order for sharing the new style via the repository. -* `http://www.opengis.net/t15/opf-styles-1/1.0/conf/core` -* `http://www.opengis.net/t15/opf-styles-1/1.0/conf/manage-styles` - -In addition, if the style includes symbols or sprites, the repository also has to support the following conformance classes: - -* `http://www.opengis.net/t15/opf-styles-1/1.0/conf/resources` -* `http://www.opengis.net/t15/opf-styles-1/1.0/conf/manage-resources` +* `http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/core` +* `http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/manage-styles` Finally, the repository has to support the native stylesheet language that the user has selected for the style definition, i.e. one of: -* `http://www.opengis.net/t15/opf-styles-1/1.0/conf/mapbox-styles` -* `http://www.opengis.net/t15/opf-styles-1/1.0/conf/sld-10` -* `http://www.opengis.net/t15/opf-styles-1/1.0/conf/sld-11` +* `http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/mapbox-styles` +* `http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/sld-10` +* `http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/sld-11` -The visual style editor will ask the user for her credentials (username and password) in the style repository and use the credentials in any of the following POST/PUT/PATCH requests. +The visual style editor will ask the user for her credentials in the style repository and use the credentials in any of the following POST/PUT/PATCH/DELETE requests. -If `http://www.opengis.net/t15/opf-styles-1/1.0/conf/style-validation` is supported, the visual style editor can also offer validation of the draft style any time during the drafting process using POST requests with the draft stylesheet to `http://example.org/styles-api/styles?validate=only`. +If `http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/style-validation` is supported, the visual style editor can also offer validation of the draft style any time during the drafting process using POST requests with the draft stylesheet to `http://example.org/styles-api/styles?dry-run=true` and a header `Prefer: handling=strict`. -To create the new style either a POST request with the stylesheet to `http://example.org/styles-api/styles` or a PUT request to `http://example.org/styles-api/styles/{styleId}` (where `{styleId}` is the identifier of the style specified by the user) is sent. `?validate=true` may also be added to the request URI to trigger validation in this step if the style validation conformance class is supported. If PUT is used, the visual style editor should check that no existing style `{styleId}` exists. +To create the new style the user sends a POST request with the stylesheet to `http://example.org/styles-api/styles`. `Prefer: handling=strict` may also be added to the request URI to trigger strict validation in this step, if the style validation conformance class is supported. After a successful creation of the style (in case of a POST request, the URI of the new style `http://example.org/styles-api/styles/{styleId}` is returned in an HTTP header `Location`), the visual style editor will update the style metadata using a PUT or PATCH request to `http://example.org/styles-api/styles/{styleId}/metadata`. -If the data access API supports the conformance class `http://www.opengis.net/t15/ogcapi-features-m/1.0/conf/style-links`, the visual style editor will add a link to the new style using a PATCH request to `http://example.org/data-api/collections/transportationgroundcrv`. - ==== A visual style editor updating an existing style The process is quite similar to the previous example with the following changes: * The user will start from an existing style, not with a new style. In other words, the user will open/load the style from the style repository and the editor will fetch a stylesheet of the style from `http://example.org/styles-api/styles/{styleId}` (in the style encoding of choice) and the styles metadata from `http://example.org/styles-api/styles/{styleId}/metadata`. -* If the style metadata includes links to sample data (e.g., `http://example.org/data-api/collections/transportationgroundcrv`), the editor may use that data for sample visualizations and perhaps to determine changes to queryables. The user may also select other data sources for these purposes. -* Since an existing style is updated, the style definition will always be updated with a PUT request to `http://example.org/styles-api/styles/{styleId}` (no POST request to `http://example.org/styles-api/styles`, which would create a new style). +* If the style metadata includes links to sample data (e.g., `http://example.org/data-api/collections/TransportationGroundCrv`), the editor may use that data for sample visualizations and perhaps to determine changes to queryables. The user may also select other data sources for these purposes. +* Since an existing style is replaced, the style definition will always be updated with a PUT request to `http://example.org/styles-api/styles/{styleId}` (no POST request to `http://example.org/styles-api/styles`, which would create a new style). ==== A Web API implementing OGC API - Maps -A Web API that implements the conformance class "Map tile" of the OGC API Maps specification returns geo-referenced bitmap images showing maps. The URI template for the map tiles is `/collections/{collectionId}/map/{styleId}/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}` and includes a query parameter `styleId`. If a client requests a map tile for the collection `transportationgroundcrv` the API will use the requested style to render the map. The stylesheet may be fetched from the same Web API or another Web API that supports the Styles API. +A Web API that implements the conformance class "Map tile" of the OGC API Maps specification returns geo-referenced bitmap images showing maps. The URI template for the map tiles is `/collections/{collectionId}/styles/{styleId}/map/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}`. If a client requests a map tile for the collection `TransportationGroundCrv` the API will use the style `{styleId}` to render the map. diff --git a/standard/clause_7_styles-api.adoc b/standard/clause_7_styles-api.adoc index c3dd931..614bfeb 100644 --- a/standard/clause_7_styles-api.adoc +++ b/standard/clause_7_styles-api.adoc @@ -3,42 +3,62 @@ TODO: move normative statements to separate files //// [[styles-api]] -== Styles API +== API building blocks for styles -Stylesheets often reference external resources, especially symbols and fonts to be used in the rendering process. Symbols are either managed as a single file for each symbol or they are organized in a sprite. In a sprite, all symbols are combined into a single bitmap image to reduce memory and the number of http requests. Single symbols and sprites are both supported by the Styles API. Further, they may be stored in the Styles API. For example, this approach would avoid issues with cross-origin requests. Of course, existing external symbol libraries may also be referenced from stylesheets. The Styles API currently does not support font resources. If external fonts / glyphs are used in a stylesheet, an existing font library has to be referenced. +=== Base resources -The API supports the resources and operations listed in the Table below with the associated conformance class and the link to the document section that specifies the requirements. +Styles can be associated with a variety of resources in an API, for example, a feature dataset, a feature collection, or a coverage. This standard does not restrict the resource types with which styles may be associated. + +This standard uses the term "base resource" for such resources. In the API, styles are sub-resources of a base resource. + +Typical base resources are: + +* The API landing page at path `/`. +** If the API provides distributions of a dataset, then the styles will be associated with the dataset. +** If the API does not provide access to data, it is a general purpose Styles API and the styles will typically be applicable to a range of data resources available elsewhere. +* A data collection at path `/collections/{collectionId}`. + +=== Resources referenced from styles + +Stylesheets often reference external resources, especially symbols and fonts to be used in the rendering process. Symbols are either managed as a single file for each symbol or they are organized in a sprite. In a sprite, all symbols are combined into a single bitmap image to reduce memory and the number of http requests. + +Since these resources are referenced from stylesheets using a URI of the resource, the details where and how the resources are hosted are not important and this specification does not specify API building blocks for publishing such resources. + +=== Overview + +The API building blocks support the resources and operations listed in the table below with the associated conformance class and the link to the document section that specifies the requirements. + +The `{baseResource}` is a path template for any API resource with which styles can be associated. [#tldr2,reftext='{table-caption} {counter:table-num}'] .Overview of resources and applicable HTTP methods [cols="15,24,8,18,25",options="header"] !=== |Resource |Path |HTTP method |Conformance class|Document reference -|Landing page |`/` |GET |core |<> |Conformance declaration |`/conformance` |GET |core |<> -.3+|Styles .3+|`/styles` |GET |core |<> +.3+|Styles .3+|`{baseResource}/styles` |GET |core |<> .2+|POST |manage-styles |<> |style-validation |<> -.4+|Style .4+|`/styles/{styleId}` |GET |core |<> -.2+|PUT |manage-styles |<> +.4+|Style .4+|`{baseResource}/styles/{styleId}` |GET |core |<> +.2+|PUT |manage-styles |<> |style-validation |<> |DELETE |manage-styles |<> -.3+|Style metadata .3+|`/styles/{styleId}/metadata` |GET |core |<> -|PUT |manage-styles |<> -|PATCH |manage-styles |<> +.3+|Style metadata .3+|`{baseResource}/styles/{styleId}/metadata` |GET |core |<> +|PUT |manage-styles |<> +|PATCH |manage-styles |<> +!=== + +//// +|Landing page |`/` |GET |core |<> |Resources |`/resources` |GET |resources |<> -.3+|Resource .3+|`/resources/{resourceId}` |GET |resources |<> +.3+|Resource .3+|``{baseResource}/resources/{resourceId}` |GET |resources |<> |PUT |manage-resources |<> |DELETE |manage-resources |<> -!=== - -The conceptual model and this draft specification support multiple style encodings (stylesheets) per style. For example, a Styles API may publish a "night" style in the style encodings OGC SLD 1.0, OGC SLD 1.1 and Mapbox Style. The client will select the stylesheet that fits best based on its capabilities and preferences. +//// -This version of the Styles API was written with the following assumptions: +This standard supports multiple style encodings (stylesheets) per style. For example, an API may publish a "night" style in the style encodings OGC SLD 1.0, OGC SLD 1.1 and Mapbox Style. The client will select the stylesheet that fits best based on its capabilities and preferences. -* When a new style is created using POST `/styles` or PUT `/styles/{styleId}`, the submitted stylesheet is the reference. -* A server may derive stylesheets in other style encodings from the reference stylesheet, but there is no requirement to support such a capability. If one or more stylesheets are derived, they will be automatically be added to the style metadata. -* When an existing style is updated using PUT `/styles/{styleId}`, the submitted stylesheet becomes the new reference and all other stylesheets for the style are removed. New stylesheets may be derived from the new reference stylesheet. The style metadata is updated. +This standard only specifies Style Metadata as a sub-resource to a Style resource. APIs and other specification may specify additional sub-resources. For example, a Map sub-resource could be provided that returns map representations of the base resource rendered using the style. [[rc_core]] === Requirements Class "Core" @@ -46,47 +66,25 @@ This version of the Styles API was written with the following assumptions: include::requirements/requirements_class_core.adoc[] [[ogcapi-common-core]] -[NOTE] -==== -An "OGC API - Common" specification is under development (October 1, 2019). The current draft of Common is based on the generic concepts of the <> standard. However, the work is in the earliest stages of the standardization process. In order to avoid duplicating content, this document does not copy the basic requirements, recommendations and permissions from OGC API Common/Features. If "OGC API - Common" is not available as a normative reference, the alternative would be to remove the dependency and to specify the following normative statements are part of this requirements class: - -* Landing page -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#req_core_root-op[Requirement /req/core/root-op] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#req_core_root-success[Requirement /req/core/root-success] -*** Change: No `data` link to `/collections` is required, but a `styles` link has to point to the `/styles` resource -* API definition -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#req_core_api-definition-op[Requirement /req/core/api-definition-op] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#per_core_api-definition-uri[Permission /per/core/api-definition-uri] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#req_core_api-definition-success[Requirement /req/core/api-definition-success] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rec_core_api-definition-oas[Recommendation /rec/core/api-definition-oas] -* Conformance declaration -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#req_core_conformance-op[Requirement /req/core/conformance-op] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#req_core_conformance-success[Requirement /req/core/conformance-success] -* Web API -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#req_core_http[Requirement /req/core/http] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rec_core_head[Recommendation /rec/core/head] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#per_core_additional-status-codes[Permission /per/core/additional-status-codes] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#req_core_query-param-unknown[Requirement /req/core/query-param-unknown] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#req_core_query-param-invalid[Requirement /req/core/query-param-invalid] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rec_core_etag[Recommendation /rec/core/etag] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rec_core_cross-origin[Recommendation /rec/core/cross-origin] -** link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rec_core_link-header[Recommendation /rec/core/link-header] - -The link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rec_core_cross-origin[recommendation /rec/core/cross-origin] is in particular relevant to support browser-based visual style editors. It is recommended to support CORS. It is important to declare all relevant headers in the response. For APIs that support the "manage-styles" conformance class especially the `Location` header needs to be declared (for example, "access-control-expose-headers: Location, Link") to allow clients access to the URI of a newly created style. - -The link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#rec_core_string-i18n[recommendation /rec/core/string-i18n] is mainly implemented by the Content-Language header in the response to requests, in particular to those returning a stylesheet or style metadata. - -The link:http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#req_core_crs84[requirement /req/core/crs84] is not applicable to the Styles API since no geometries are used in the API. -==== - -[[landing_page]] -==== API landing page - -The following is an example of the landing page of a Styles API. This implementation supports the "json" conformance class, but not the "html" conformance class. +==== OGC API - Common - Part 1: Core + +At the time of writing, <> is a candidate standard and not yet an approved standard. The requirements class "Core" has to be supported. This includes support for the API resources Landing Page, Conformance Declaration and API Definition. + +[[base-resource]] +==== Base resource + +[[req_core_base-resource-link]] +[width="90%",cols="2,6a"] +|=== +^|*Requirement {counter:req-id}* |*/req/core/base-resource-link* +^|A |The content of any base resource (at path `{baseResource}`) with which styles are associated in the API SHALL include a link to a Styles resource at path `{baseResource}/styles` (link relation type 'http://www.opengis.net/def/rel/OGC/1.0/styles'). +|=== [[example_lp]] .Landing page in JSON ================= +For a general purpose Styles API the base resource will be the Landing Page of the API. The following is an example of a landing page with a Styles sub-resource. This implementation supports the "json" conformance class, but not the "html" conformance class. + [source,JSON] ---- { @@ -111,13 +109,13 @@ The following is an example of the landing page of a Styles API. This implementa }, { "href": "https://example.org/api/v1/conformance", - "rel": "conformance", + "rel": "http://www.opengis.net/def/rel/OGC/1.0/conformance", "type": "application/json", "title": "list of conformance classes implemented by this API" }, { "href": "https://example.org/api/v1/styles", - "rel": "styles", + "rel": "http://www.opengis.net/def/rel/OGC/1.0/styles", "type": "application/json", "title": "the styles shared via this API" } @@ -129,7 +127,7 @@ The following is an example of the landing page of a Styles API. This implementa [[conformance_declaration]] ==== Declaration of conformance classes -The following is an example of the conformance declaration of a Styles API that implements all requirements classes except "html". +The following is an example of the conformance declaration of an API that implements all requirements classes of this standard and OGC API Common Core, except "html". [[example_cc]] .Conformance declaration in JSON @@ -138,15 +136,18 @@ The following is an example of the conformance declaration of a Styles API that ---- { "conformsTo": [ - "http://www.opengis.net/t15/opf-styles-1/1.0/conf/core", - "http://www.opengis.net/t15/opf-styles-1/1.0/conf/manage-styles", - "http://www.opengis.net/t15/opf-styles-1/1.0/conf/style-validation", - "http://www.opengis.net/t15/opf-styles-1/1.0/conf/resources", - "http://www.opengis.net/t15/opf-styles-1/1.0/conf/manage-resources", - "http://www.opengis.net/t15/opf-styles-1/1.0/conf/mapbox-styles", - "http://www.opengis.net/t15/opf-styles-1/1.0/conf/sld-10", - "http://www.opengis.net/t15/opf-styles-1/1.0/conf/sld-11" - ] + "http://www.opengis.net/spec/ogcapi-common-1/1.0/req/core", + "http://www.opengis.net/spec/ogcapi-common-1/1.0/req/json", + "http://www.opengis.net/spec/ogcapi-common-1/1.0/req/oas30", + "http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/core", + "http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/manage-styles", + "http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/style-validation", + "http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/resources", + "http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/manage-resources", + "http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/mapbox-styles", + "http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/sld-10", + "http://www.opengis.net/spec/ogcapi-styles-1/1.0/conf/sld-11" + ] } ---- ================= @@ -154,13 +155,13 @@ The following is an example of the conformance declaration of a Styles API that [[get_styles]] ==== Fetch styles -This operation returns a list of styles that are currently available. +This operation returns a list of styles that are currently available for the base resource. [[req_core_styles-op]] [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/core/styles-op* -^|A |The server SHALL support the HTTP GET operation at the path `/styles`. +^|A |The server SHALL support the HTTP GET operation at the path `{baseResource}/styles`. |=== [[req_core_styles-success]] @@ -178,43 +179,37 @@ required: properties: styles: type: array - nullable: true items: type: object - nullable: true required: - id - links properties: id: type: string - nullable: true title: type: string - nullable: true links: type: array - nullable: true minItems: 1 items: - $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/schemas/link' + $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml' ---- ^|C |The `styles` member SHALL include one item for each style currently on the server. ^|D |The `id` member of each style SHALL be unique. -^|E |Each style SHALL have at least one link to a style encoding supported for the style (link relation: `stylesheet`) with the `type` attribute stating the media type of the style encoding. -^|F |Each style SHALL have a link to the style metadata (link relation: `describedby`) with the `type` attribute stating the media type of the metadata encoding. +^|E |Each style SHALL have at least one link to a style encoding supported for the style (link relation type: `stylesheet`) with the `type` attribute stating the media type of the style encoding. +^|F |Each style SHALL have a link to the style metadata (link relation type: `describedby`) with the `type` attribute stating the media type of the metadata encoding. |=== -NOTE: Currently the links to the thumbnails of a style are available only as part of the style metadata (see <>). To display an overview of the styles with a thumbnail image, a client needs to send multiple requests, the first one for the list of styles and then a request for each style metadata to get the thumbnail links. Whether the preview should also be included for each style in the Styles resource should be discussed. +#TODO: Currently the links to the thumbnails of a style are available only as part of the style metadata (see <>). To display an overview of the styles with a thumbnail image, a client needs to send multiple requests, the first one for the list of styles and then a request for each style metadata to get the thumbnail links. Whether the preview should also be included for each style in the Styles resource should be discussed.# [[rec_core_style-title]] [width="90%",cols="2,6a"] |=== ^|*Recommendation {counter:rec-id}* |*/rec/core/style-title* -^|A |If a style has a title, it SHOULD be included in the `title` member of the style. +^|A |If a style has a title, it SHOULD be included in the `title` member of the style object. |=== - [[example_styles]] .JSON encoding of styles ================= @@ -278,7 +273,7 @@ This operation returns the stylesheet of a style. [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/core/style-op* -^|A |The server SHALL support the HTTP GET operation at the path `/style/{styleId}` for each style referenced from the Styles resource at `/styles`. +^|A |The server SHALL support the HTTP GET operation at the path `{baseResource}/style/{styleId}` for each style referenced from the Styles resource at `{baseResource}/styles`. |=== [[req_core_style-success]] @@ -290,7 +285,7 @@ This operation returns the stylesheet of a style. ^|C |The language used in linguistic text in the response SHALL be consistent with the language stated in the `Content-Language` header. |=== -NOTE: The `Content-Language` header in a HTTP response is used to describe the language(s) intended for the audience. If no Content-Language is specified, the default is that the content is intended for all language audiences. +The `Content-Language` header in a HTTP response is used to describe the language(s) intended for the audience. If no Content-Language is specified, the default is that the content is intended for all language audiences. [[get_style_metadata]] ==== Fetch style metadata @@ -301,7 +296,7 @@ This operation returns the metadata of a style. [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/core/style-md-op* -^|A |The server SHALL support the HTTP GET operation at the path `/style/{styleId}/metadata` for each style metadata referenced from the Styles resource at `/styles`. +^|A |The server SHALL support the HTTP GET operation at the path `{baseResource}/style/{styleId}/metadata` for each style metadata referenced from the Styles resource at `{baseResource}/styles`. |=== [[req_core_style-md-success]] @@ -321,21 +316,16 @@ properties: type: string title: type: string - nullable: true description: type: string - nullable: true keywords: type: array - nullable: true items: type: string pointOfContact: type: string - nullable: true accessConstraints: type: string - nullable: true enum: - unclassified - confidential @@ -344,71 +334,54 @@ properties: - topSecret dates: type: object - nullable: true properties: creation: type: string format: date-time - nullable: true publication: type: string format: date-time - nullable: true revision: type: string format: date-time - nullable: true validTill: type: string format: date-time - nullable: true receivedOn: type: string format: date-time - nullable: true scope: type: string - nullable: true example: style enum: - style version: type: string - nullable: true example: 1.0.0 stylesheets: type: array - nullable: true items: type: object - nullable: true required: - link properties: title: type: string - nullable: true version: type: string - nullable: true specification: type: string format: url - nullable: true native: type: boolean - nullable: true tilingScheme: type: string - nullable: true link: - $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/schemas/link' + $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml' layers: type: array - nullable: true items: type: object - nullable: true required: - id properties: @@ -416,10 +389,8 @@ properties: type: string description: type: string - nullable: true type: type: string - nullable: true enum: - point - line @@ -427,19 +398,20 @@ properties: - geometry - raster attributes: - $ref: 'https://api.swaggerhub.com/domains/cportele/ogcapi-draft-extensions/1.0.0#/components/schemas/queryables' + type: object + additionalProperties: + $ref: 'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v3.0/schema.json#/definitions/Schema' sampleData: - $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/schemas/link' + $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml' links: type: array - nullable: true items: - $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/ogcapi-features-1.yaml#/components/schemas/link' + $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml' ---- ^|C |The language used in linguistic text in the response SHALL be consistent with the language stated in the `Content-Language` header. |=== -The elements of the schema are defined in <>. +The elements of the schema are defined in <>, except for the items in the `attributes` object, where each member describes a JSON Schema for an attribute. [[rec_core_style-md-sample-data]] [width="90%",cols="2,6a"] @@ -450,10 +422,10 @@ The elements of the schema are defined in <>. This section specifies how those requirements apply to the API building blocks for styles. -Note that the metadata will be incomplete and should be updated by the client to keep the style metadata consistent with the style definition. +[[manage-styles_styles-endpoint]] +==== Resources endpoint -[[req_manage-styles_create-style-error]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/create-style-error* -^|A |If the request does not conform to the requirements (e.g., the stylesheet is invalid) a response with status code `400` SHALL be returned. -|=== +[[create_style]] +===== Create a new style -[[rec_manage-styles_id-exists]] +[[req_manage-styles_resources-endpoint]] [width="90%",cols="2,6a"] |=== -^|*Recommendation {counter:rec-id}* |*/rec/manage-styles/id-exists* -^|A |If the request is valid, but the server already has a style with the identifier stated in the stylesheet, a response with status code `409` SHOULD be returned. +^|*Requirement {counter:req-id}* |*/req/manage-styles/resources-endpoint* +^|A |For styles, the resources endpoints to create a new style SHALL be URIs specified by the URI template `{baseResource}/styles`. +^|B |When a new style is created, a minimal style metadata resource SHALL be created at `{baseResource}/styles/{styleId}/metadata`. |=== +The style metadata will be incomplete and should be updated by the client to keep the style metadata consistent with the style definition. [[example_style_location]] .New style response @@ -619,38 +564,37 @@ Location: https://example.org/api/v1/styles/night ---- ================= -[[update_style]] -==== Update or create a style - -This operation updates the style with the id `styleId`. If no such style exists, a new style with that id is added. - -For updated styles, the style metadata resource at `/styles/{styleId}/metadata` is not updated. For new styles a minimal style metadata resource is -created, too. Please update the metadata using a PUT request to keep the style metadata consistent with the style definition. - -[[req_manage-styles_update-style-op]] +[[rec_manage-styles_id-exists]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/update-style-op* -^|A |The server SHALL support the HTTP PUT operation at the path `/styles/{styleId}`. -^|B |The server SHALL accept a stylesheet in one of the style encodings supported by the API. +^|*Recommendation {counter:per-id}* |*/rec/manage-styles/id-exists* +^|A |If the request to create a new style is syntactically valid, but the server assigns new identifiers based on information in the stylesheet and the server already has a style with the identifier stated in the stylesheet, a response with status code `409` SHOULD be returned. |=== -[[req_manage-styles_update-style-success]] +[[manage-styles_style-endpoint]] +==== Resource endpoints + +[[req_manage-styles_resource_endpoint]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/update-style-success* -^|A |A successful execution of the operation SHALL be reported as a response with an HTTP status code `204`. -^|B |If a new style is created, a minimal style metadata resource SHALL be created at `/styles/{styleId}/metadata`. +^|*Requirement {counter:req-id}* |*/req/manage-styles/resource-endpoint* +^|A |For styles, the resource endpoints SHALL be URIs specified by the URI template `{baseResource}/styles/{styleId}`. +^|B |The parameter `styleId` SHALL be the `id` property of a style obtained by previously having queried the Styles resource (i.e., responses to GET requests to `{baseResource}/styles`). +^|C |Additional resource endpoints SHALL be URIs specified by the URI template `{baseResource}/styles/{styleId}/metadata` (style metadata). |=== -Note that the metadata should be updated by the client, too, to keep the style metadata consistent with the style definition. +[[replace_style]] +==== Replace a style -[[req_manage-styles_update-style-error]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/update-style-error* -^|A |If the request does not conform to the requirements (e.g., the stylesheet is invalid) a response with status code `400` SHALL be returned. -|=== +#TODO: There are two options how to handle PUT on `{baseResource}/styles/{styleId}`, depending on whether the server supports automated derivation of stylesheets in other style encodings.# + +#1. The PUT request removes all existing stylesheets of the style. The submitted stylesheet is accepted as the new style definition. If the server supports automatic derivation of stylesheets in other style encodings, it will derive other stylesheets from the new style definition and add them to the style metadata.# + +#2. The PUT request sets or replaces the current stylesheet for the media type specified in the `Content-Type` header, but leaves other stylesheets of the style untouched. That is, all stylesheets are managed separately by clients.# + +#Do we want to support one or both of the options?# + +The style metadata resource at `{baseResource}/styles/{styleId}/metadata` is not updated. If the changes affect the metadata, the style metadata needs to be updated to keep the style metadata consistent with the style definition. [[delete_style]] ==== Delete a style @@ -659,75 +603,167 @@ This operation deletes the style with the id `styleId`. If no such style exists, Deleting a style also deletes the subordinate resources, i.e., the style metadata. -[[req_manage-styles_delete-style-op]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/delete-style-op* -^|A |The server SHALL support the HTTP DELETE operation at the path `/styles/{styleId}`. -|=== - -[[req_manage-styles_delete-style-success]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/delete-style-success* -^|A |A successful execution of the operation SHALL be reported as a response with an HTTP status code `204`. -^|B |All subordinate resources including the style metadata at `/styles/{styleId}/metadata` SHALL be deleted, too. -|=== - -[[req_manage-styles_delete-style-error]] +[[req_manage-styles_styles-delete]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/delete-style-error* -^|A |If the style does not exist, a response with status code `404` SHALL be returned. +^|*Requirement {counter:req-id}* |*/req/manage-styles/styles-delete* +^|A |For requests to the style metadata (template `{baseResource}/styles/{styleId}/metadata`), the DELETE operation SHALL not be supported. +^|B |DELETE requests to a style (template `{baseResource}/styles/{styleId}`) SHALL delete the style metadata of that style, too. |=== -[[update_style_metadata]] +[[replace_style_metadata]] ==== Replace the metadata of a style -This operation replaces the metadata of the style with the id `styleId`. If no such style exists, an error is returned. - -[[req_manage-styles_update-style-md-op]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/update-style-md-op* -^|A |The server SHALL support the HTTP PUT operation at path `/styles/{styleId}/metadata`. -^|B |The server SHALL accept style metadata based on the schema <> in all encodings supported by the API. -|=== - -[[req_manage-styles_update-style-md-success]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/update-style-md-success* -^|A |A successful execution of the operation SHALL be reported as a response with an HTTP status code `204`. -^|B |The style metadata SHALL be replaced by the content submitted in the request. -|=== +The PUT operation on `{baseResource}/styles/{styleId}/metadata` replaces the metadata of the style with the id `styleId`. If no such style exists, an error is returned. -[[req_manage-styles_update-style-md-error]] +[[req_manage-styles_replace-style-md]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/update-style-md-error* -^|A |If the style does not exist, a response with status code `404` SHALL be returned. +^|*Requirement {counter:req-id}* |*/req/manage-styles/replace-style-md* +^|> |The server SHALL accept style metadata based on the schema <> in all encodings supported by the API. |=== -[[patch_style_metadata]] -==== Update parts of the metadata of a style +[[update_style_metadata]] +==== Update the metadata of a style -This operation updates the metadata of the style with the id `styleId`. If no such style exists, an error is returned. +The PATCH operation on `{baseResource}/styles/{styleId}/metadata` updates the metadata of the style with the id `styleId`. If no such style exists, an error is returned. -[[req_manage-styles_patch-style-md-op]] +[[req_features_representation-geojson-update]] [width="90%",cols="2,6a"] |=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/patch-style-md-op* -^|A |The server SHALL support the HTTP PATCH operation at path `/styles/{styleId}/metadata`. -^|B |The server SHALL accept style metadata based on the schema <> in all encodings supported by the API. -|=== +^|*Requirement {counter:req-id}* |*/req/features/representation-geojson-update* +^|Condition |Server implements <> +^|Condition |Server advertises support for media type `application/merge-patch+json` in the API definition for PATCH requests at `{baseResource}/styles/{styleId}/metadata` +^|A |The server SHALL process PATCH requests with a content type `application/merge-patch+json` to such a resource endpoint as specified by <>. +^|B |The content of the request SHALL be based upon the following OpenAPI 3.0 schema: -[[req_manage-styles_patch-style-md-success]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/patch-style-md-success* -^|A |A successful execution of the operation SHALL be reported as a response with an HTTP status code `204`. -^|B |The style metadata SHALL be updated by the content submitted in the request as specified by RFC 7396 (JSON Merge Patch). +[source,YAML] +---- +type: object +required: + - id +properties: + id: + type: string + title: + type: string + nullable: true + description: + type: string + nullable: true + keywords: + type: array + nullable: true + items: + type: string + pointOfContact: + type: string + nullable: true + accessConstraints: + type: string + nullable: true + enum: + - unclassified + - confidential + - restricted + - secret + - topSecret + dates: + type: object + nullable: true + properties: + creation: + type: string + format: date-time + nullable: true + publication: + type: string + format: date-time + nullable: true + revision: + type: string + format: date-time + nullable: true + validTill: + type: string + format: date-time + nullable: true + receivedOn: + type: string + format: date-time + nullable: true + scope: + type: string + nullable: true + example: style + enum: + - style + version: + type: string + nullable: true + example: 1.0.0 + stylesheets: + type: array + nullable: true + items: + type: object + nullable: true + required: + - link + properties: + title: + type: string + nullable: true + version: + type: string + nullable: true + specification: + type: string + format: url + nullable: true + native: + type: boolean + nullable: true + tilingScheme: + type: string + nullable: true + link: + $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml' + layers: + type: array + nullable: true + items: + type: object + nullable: true + required: + - id + properties: + id: + type: string + description: + type: string + nullable: true + type: + type: string + nullable: true + enum: + - point + - line + - polygon + - geometry + - raster + attributes: + type: object + additionalProperties: + $ref: 'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v3.0/schema.json#/definitions/Schema' + sampleData: + $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml' + links: + type: array + nullable: true + items: + $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml' +---- |=== [[rfc7396_quote]] @@ -749,9 +785,7 @@ merge patch are given special meaning to indicate the removal of existing values in the target. ____ -NOTE: A more flexible, but more complex option for JSON-based PATCH operations is specified by RFC 6902. JSON Merge Patch is used because of its simpler and more intuitive design. An XML-based PATCH operation is specified by RFC 5261. - -Some examples using JSON Merge Patch include: +Some examples using JSON Merge Patch: To add or update the point of contact, the access constraint and the revision date, just send: @@ -808,17 +842,6 @@ To remove the keywords, send: The same applies to `stylesheets`, `layers` and `links`. To update these members, the complete new array value has to be sent. -[[req_manage-styles_patch-style-md-error]] -[width="90%",cols="2,6a"] -|=== -^|*Requirement {counter:req-id}* |*/req/manage-styles/patch-style-md-error* -^|A |If the request does not conform to the requirements (e.g., the patch document is invalid) a response with status code `400` SHALL be returned. -^|B |If the style does not exist, a response with status code `404` SHALL be returned. -^|C |If the patch document appears to be valid, but the server is incapable of processing the request, a response with status code `422` SHALL -be returned. -^|D |If the media type of the patch document is not supported by the API, a response with status code `415` and an `Accept-Patch` header with the supported media types SHALL be returned. -|=== - [[rc_style-validation]] === Requirements Class "Validation of styles" @@ -831,7 +854,8 @@ include::requirements/requirements_class_style-validation.adoc[] [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/style-validation/input* -^|A |The server SHALL support a parameter with the name "validate" in POST requests to the path `/styles` and in PUT requests to the path `/styles/{styleId}` with the following schema: +^|A |The server SHALL support the `Prefer` header with the https://tools.ietf.org/html/rfc7240#section-4.4["handling=strict" and "handling=lenient" Preferences]. +^|B |The server SHALL support a parameter with the name "dry-run" in POST requests to the path `{baseResource}/styles` and in PUT requests to the path `{baseResource}/styles/{styleId}` with the following schema: [source,YAML] ---- @@ -841,12 +865,8 @@ required: false style: form explode: false schema: - type: string - enum: - - yes - - no - - only - default: no + type: boolean + default: false ---- |=== @@ -854,11 +874,14 @@ schema: [width="90%",cols="2,6a"] |=== ^|*Requirement {counter:req-id}* |*/req/style-validation/output* -^|A |If the `validate` parameter has been provided in the request with the value 'yes', the server SHALL validate the submitted stylesheet for conformance with the style encoding. If an error is identified, a response with status code `400` shall be returned. -^|A |If the `validate` parameter has been provided in the request with the value 'only', the server SHALL validate the submitted stylesheet for conformance with the style encoding. If an error is identified, a response with status code `400` SHALL be returned. If no error is identified, a response with status code `204` SHALL be returned and no style SHALL be created or updated. +^|A |If the `Prefer` header has been provided in the request with the "handling=strict" preference, the server SHALL validate the submitted stylesheet for conformance with the style encoding. If an error in the stylesheet is identified, a response with status code `400` SHALL be returned. +^|A |If the `dry-run` parameter has been provided in the request with the value 'true', the server SHALL execute the request except that no style SHALL be created or updated. If no error condition is identified a response with status code `204` SHALL be returned. |=== -If no parameter `validate` is provided or the parameter has the value 'no', the standard response is returned (for a POST on `/styles` a `201` response with the `Location` header pointing to the new Style resource, for a PUT request on `/styles/{styleId}` a `204` response). +If no parameter `dry-run` is provided or the parameter has the value 'false', the standard response for a Create or Replace operation is returned. + +//// +commented out for now [[rc_resources]] === Requirements Class "Resources" @@ -872,7 +895,7 @@ A GET request returns a list of resources that are currently available. The reso For each resource the id and a link to the resource is provided. -NOTE: OGC Testbed-15 required only support for a limited number of the resources. Therefore, the currently simple approach is sufficient, but in general the operation could support paging (using a parameter `limit` and links to the `next` page in responses). +#TODO: OGC Testbed-15 required only support for a limited number of the resources. Therefore, the currently simple approach is sufficient, but in general the operation could support paging (using a parameter `limit` and links to the `next` page in responses).# [[req_resources_resources-op]] [width="90%",cols="2,6a"] @@ -1025,6 +1048,10 @@ This operation deletes the resource with the id `resourceId`. If no such resourc ^|*Requirement {counter:req-id}* |*/req/manage-resources/delete-resource-error* ^|A |If the style does not exist, a response with status code `404` SHALL be returned. |=== +//// + +//// +commented out, HTML is already a requirements class in Common Core [[rc_html]] === Requirements Class "HTML" @@ -1049,6 +1076,7 @@ That is, all resources are expected to have a HTML representation except the sty * all information identified in the schemas of the link:https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#responseObject[Response Object] in the HTML ``, and * all links in HTML `` elements in the HTML ``. |=== +//// [[rc_sld-10]] === Requirements Class "OGC SLD 1.0" @@ -1071,8 +1099,8 @@ include::requirements/requirements_class_sld-10.adoc[] The list of operations in a server implementing all conformance classes of this draft specification is: -* POST `/styles` -* PUT `/styles/{styleId}` +* POST `{baseResource}/styles` +* PUT `{baseResource}/styles/{styleId}` [[rc_sld-11]] === Requirements Class "OGC SLD 1.1" @@ -1095,8 +1123,8 @@ include::requirements/requirements_class_sld-11.adoc[] The list of operations in a server implementing all conformance classes of this draft specification is: -* POST `/styles` -* PUT `/styles/{styleId}` +* POST `{baseResource}/styles` +* PUT `{baseResource}/styles/{styleId}` [[rc_mapbox-styles]] === Requirements Class "Mapbox Style" @@ -1119,5 +1147,5 @@ include::requirements/requirements_class_mapbox-style.adoc[] The list of operations in a server implementing all conformance classes of this draft specification is: -* POST `/styles` -* PUT `/styles/{styleId}` +* POST `{baseResource}/styles` +* PUT `{baseResource}/styles/{styleId}` diff --git a/standard/requirements/requirements_class_core.adoc b/standard/requirements/requirements_class_core.adoc index 793f51f..25ad0b2 100644 --- a/standard/requirements/requirements_class_core.adoc +++ b/standard/requirements/requirements_class_core.adoc @@ -1,9 +1,9 @@ [cols="1,4",width="90%"] |=== 2+|*Requirements Class* {set:cellbgcolor:#CACCCE} -2+|http://www.opengis.net/t15/opf-styles-1/{m_n}/req/core {set:cellbgcolor:#FFFFFF} +2+|http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/core {set:cellbgcolor:#FFFFFF} |Target type |Web API -|Dependency |OGC API - Common (Core) +|Dependency |<> |=== //// diff --git a/standard/requirements/requirements_class_manage-styles.adoc b/standard/requirements/requirements_class_manage-styles.adoc index 3597770..0750c26 100644 --- a/standard/requirements/requirements_class_manage-styles.adoc +++ b/standard/requirements/requirements_class_manage-styles.adoc @@ -1,8 +1,10 @@ [cols="1,4",width="90%"] |=== 2+|*Requirements Class* {set:cellbgcolor:#CACCCE} -2+|http://www.opengis.net/t15/opf-styles-1/{m_n}/req/manage-styles {set:cellbgcolor:#FFFFFF} +2+|http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/manage-styles {set:cellbgcolor:#FFFFFF} |Target type |Web API |Dependency |<> -|Dependency |link:https://tools.ietf.org/rfc/rfc7396.txt[RFC 7396 (JSON Merge Patch)] +|Dependency |<> +|Conditional Dependency |<> +|Conditional Dependency |<> |=== diff --git a/standard/requirements/requirements_class_mapbox-style.adoc b/standard/requirements/requirements_class_mapbox-style.adoc index e99acf8..e0c263c 100644 --- a/standard/requirements/requirements_class_mapbox-style.adoc +++ b/standard/requirements/requirements_class_mapbox-style.adoc @@ -1,8 +1,8 @@ [cols="1,4",width="90%"] |=== 2+|*Requirements Class* {set:cellbgcolor:#CACCCE} -2+|http://www.opengis.net/t15/opf-styles-1/{m_n}/req/mapbox-style {set:cellbgcolor:#FFFFFF} +2+|http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/mapbox-style {set:cellbgcolor:#FFFFFF} |Target type |Web API -|Dependency |<> +|Dependency |<> |Dependency |link:https://docs.mapbox.com/mapbox-gl-js/style-spec/[Mapbox Style Specification, Version 8] |=== diff --git a/standard/requirements/requirements_class_sld-10.adoc b/standard/requirements/requirements_class_sld-10.adoc index 7243313..61b88ed 100644 --- a/standard/requirements/requirements_class_sld-10.adoc +++ b/standard/requirements/requirements_class_sld-10.adoc @@ -1,8 +1,8 @@ [cols="1,4",width="90%"] |=== 2+|*Requirements Class* {set:cellbgcolor:#CACCCE} -2+|http://www.opengis.net/t15/opf-styles-1/{m_n}/req/sld-10 {set:cellbgcolor:#FFFFFF} +2+|http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/sld-10 {set:cellbgcolor:#FFFFFF} |Target type |Web API -|Dependency |<> -|Dependency |link:http://portal.opengeospatial.org/files/?artifact_id=1188[OGC 02-070, Styled Layer Descriptor, Version 1.0] +|Dependency |<> +|Dependency |<> |=== diff --git a/standard/requirements/requirements_class_sld-11.adoc b/standard/requirements/requirements_class_sld-11.adoc index f2ca10d..8edfa9f 100644 --- a/standard/requirements/requirements_class_sld-11.adoc +++ b/standard/requirements/requirements_class_sld-11.adoc @@ -1,8 +1,8 @@ [cols="1,4",width="90%"] |=== 2+|*Requirements Class* {set:cellbgcolor:#CACCCE} -2+|http://www.opengis.net/t15/opf-styles-1/{m_n}/req/sld-11 {set:cellbgcolor:#FFFFFF} +2+|http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/sld-11 {set:cellbgcolor:#FFFFFF} |Target type |Web API -|Dependency |<> -|Dependency |link:http://portal.opengeospatial.org/files/?artifact_id=22364[OGC 05-078r4, Styled Layer Descriptor, Version 1.1] +|Dependency |<> +|Dependency |<> |=== diff --git a/standard/requirements/requirements_class_style-validation.adoc b/standard/requirements/requirements_class_style-validation.adoc index 9b9915e..6e58ae0 100644 --- a/standard/requirements/requirements_class_style-validation.adoc +++ b/standard/requirements/requirements_class_style-validation.adoc @@ -1,7 +1,8 @@ [cols="1,4",width="90%"] |=== 2+|*Requirements Class* {set:cellbgcolor:#CACCCE} -2+|http://www.opengis.net/t15/opf-styles-1/{m_n}/req/style-validation {set:cellbgcolor:#FFFFFF} +2+|http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/style-validation {set:cellbgcolor:#FFFFFF} |Target type |Web API |Dependency |<> +|Dependency |<> |===