Open Geospatial Consortium

Submission Date: yyyy-mm-dd

Approval Date:   yyyy-mm-dd

Publication Date:   yyyy-mm-dd

External identifier of this OGC® document: http://www.opengis.net/doc/IS/ogcapi-styles/1.0

Internal reference number of this OGC® document: 20-009

Version: 1.0.0-SNAPSHOT (Editor’s draft)

Category: OGC® Implementation Standard

Editor: Clemens Portele

OGC API - Styles

Copyright notice

Copyright © 2021 Open Geospatial Consortium

To obtain additional rights of use, visit http://www.opengeospatial.org/legal/

Warning

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

Document type:    OGC® Implementation Standard

Document subtype:    Interface

Document stage:    Draft

Document language:  English

License Agreement

Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.

If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.

THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD.

THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.

This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.

Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications. This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.

Table of Contents

i. Abstract

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;

  • Web APIs implementing the draft OGC API - Maps specification fetch styles and render spatial data (features or coverages) on the server;

  • Map clients that fetch styles and render spatial data (features or coverages) on the client.

Feature data is either accessed directly or organized into spatial partitions such as a tiled data store (aka "vector tiles").

The API building blocks implement the conceptual model for styles, style encodings and style metadata as documented in chapter 6 of the "OGC Testbed-15: Encoding and Metadata Conceptual Model for Styles Engineering Report".

The model defines three main concepts:

  1. The style is the main resource.

  2. Each style is available in one or more stylesheets - the representation of a style in an encoding like OGC SLD 1.0 or Mapbox Style. Clients will use the stylesheet of a style that fits best based on the capabilities of available tools and their preferences.

  3. For each style there is style metadata available, with general descriptive 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 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}).

Table 1. Styles API - overview of resources and applicable HTTP methods
Resource Path HTTP method Document reference

Base resource

{baseResource}

GET

Base resource

Conformance declaration

/conformance

GET

Declaration of conformance classes

Styles

{baseResource}/styles

GET

Fetch styles

POST

Create a new style

Validate a style

Style

{baseResource}/styles/{styleId}

GET

Fetch style

PUT

Replace a style

Validate a style

DELETE

Delete a style

Style metadata

{baseResource}/styles/{styleId}/metadata

GET

Fetch style metadata

PUT

Replace the metadata of a style

PATCH

Update the metadata of a style

This document uses OpenAPI 3.0 to specify the building blocks of the API.

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

— OpenAPI Specification
Introduction

ii. Keywords

The following are keywords to be used by search engines and document catalogues.

ogcdoc, OGC document, OpenAPI, OGC API, style, style encoding, stylesheet, style metadata, Styles API

iii. Preface

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.

iv. Submitting organizations

Caution
 TODO
This is the list of submitters is from the Testbed-15 Engineering Report. Eventually we need to confirm the list after the specification has changed in the standardization process.

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

  • CubeWerx Inc. (MariaDB)

  • Ecere Corporation

  • GeoSolutions

  • interactive instruments GmbH

  • Leidos

  • Reinventing Geospatial, Inc.

  • US Army Geospatial Center (AGC)

v. Submitters

All questions regarding this submission should be directed to the editor or the submitters:

Name Affiliation

Clemens Portele (editor)

interactive instruments GmbH

Andrea Aime

GeoSolutions

Jeff Harrison

US Army Geospatial Center (AGC)

Jérôme Jacovella-St-Louis

Ecere Corporation

Richard Kim

Reinventing Geospatial, Inc.

Panagiotis (Peter) A. Vretanos

Cubewerx Inc. (MariaDB)

1. Scope

OGC API Styles specifies building blocks for Web APIs that enables map servers and clients as well as visual style editors to manage and fetch styles.

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.

2. Conformance

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.

In addition, there are three requirements/conformance classes for style encodings supported by resources of the 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.

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.

In order to conform to this draft specification, a software implementation has to implement "core".

3. 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.

4. Terms and Definitions

This document uses the terms defined in Sub-clause 5.3 of [OGC 06-121r8], which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this draft specification.

For the purposes of this document, the following additional terms and definitions apply.

4.1. queryable

a property that can be queried

4.2. <portrayal> sprite

an image containing a collection of uniformly-sized symbols as sub-images

4.3. style

a sequence of rules of symbolizing instructions to be applied by a rendering engine on one or more features and/or coverages

4.4. style encoding

specification to express a style as one or more files

EXAMPLE: OGC SLD versions 1.0 and 1.1, Mapbox Styles.

4.5. stylesheet

representation of a style in a style encoding

4.6. 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

4.7. Styles API

Web API conforming to OGC API - Styles - Part 1: Core

4.8. Web API

API using an architectural style that is founded on the technologies of the Web [source: OGC API - Features - Part 1: Core]

Note
 See Best Practice 24: Use Web Standards as the foundation of APIs (W3C Data on the Web Best Practices) for more detail.

5. Conventions

5.1. Identifiers

The normative provisions in this draft specification are denoted by the URI

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.

5.2. Link relations

To express relationships between resources, RFC 8288 (Web Linking) is used.

The following link relation types registered with IANA are used in this document:

  • alternate: Refers to a substitute for this context.

  • collection: The target IRI points to a resource which represents the collection resource for the context IRI.

  • describedby: Refers to a resource providing information about the link’s context.

  • enclosure: Identifies a related resource that is potentially large and might require special handling.

  • preview: Refers to a resource that provides a preview of the link’s context.

  • self: Conveys an identifier for the link’s context.

  • service-desc: Identifies service description for the context that is primarily intended for consumption by machines.

  • service-doc: Identifies service documentation for the context that is primarily intended for human consumption.

  • start: Refers to the first resource in a collection of resources.

  • stylesheet: Refers to a stylesheet.

The following link relation types registered with the OGC Naming Authority are used in this document:

  • http://www.opengis.net/def/rel/ogc/1.0/conformance: Refers to resource that identifies the specifications that the link’s context conforms to.

  • http://www.opengis.net/def/rel/ogc/1.0/tilesets-vector: The target IRI points to a resource that describes how to provide tile sets of the context resource in vector format.

  • http://www.opengis.net/def/rel/ogc/1.0/tileset-coverage: The target IRI points to a resource that describes how to provide tile sets of the context resource in coverage format.

The following link relation types will be registered with the OGC Naming Authority, if the document is approved:

  • http://www.opengis.net/def/rel/ogc/1.0/schema: Refers to a schema that data has to conform to to be suitable for use with the link’s context.

  • http://www.opengis.net/def/rel/ogc/1.0/styles: Refers to a collection of styles.

Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by the API.

5.3. Use of HTTPS

For simplicity, this document in general only refers to the HTTP protocol. This is not meant to exclude the use of HTTPS and simply is a shorthand notation for "HTTP or HTTPS." In fact, most servers are expected to use HTTPS, not HTTP.

5.4. References to OpenAPI components in normative statements

This document uses OpenAPI 3.0 fragments as examples and to formally state requirements. However, using OpenAPI 3.0 is not required for implementing a server.

In this document, fragments of OpenAPI definitions are shown in YAML (YAML Ain’t Markup Language) since YAML is easier to read than JSON and is typically used in OpenAPI editors. YAML is described by its authors as a human friendly data serialization standard for all programming languages.

Some normative statements (requirements, recommendations and permissions) use a phrase that a component in the API definition of the server must be "based upon" a schema or parameter component in the OGC schema repository.

In the case above, the following changes to the pre-defined OpenAPI component are permitted.

  • The range of values of a parameter or property may be extended (additional values) or constrained (if a subset of all possible values are applicable to the server). An example for a constrained range of values is to explicitly specify the supported values of a string parameter or property using an enum.

  • The default value of a parameter may be changed or added unless a requirement explicitly prohibits this.

  • Additional properties may be added to the schema definition of a Response Object.

  • Informative text may be changed or added, like comments or description properties.

  • If the server supports an XML encoding, xml properties may be added to the relevant OpenAPI schema components.

For API definitions that do not conform to the OpenAPI Specification 3.0, the normative statement should be interpreted in the context of the API definition language used.

5.5. Abbreviated terms

API

Application Programming Interface

NGA

US National Geospatial Intelligence Agency

OGC

Open Geospatial Consortium

SLD

OGC Styled Layer Descriptor

TDS

Topographic Data Store (an NGA specification)

6. Introduction

6.1. Overview

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:

  • 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;

  • Web APIs implementing the draft OGC API - Maps specification fetch styles and render spatial data (features or coverages) on the server;

  • Map clients that fetch styles and render spatial data (features or coverages) on the client.

Feature data is either accessed directly or organized into spatial partitions such as a tiled data store (aka "vector tiles").

The remainder of this Clause illustrates use cases and workflows that a Styles API could support.

Clause 7 specifies the API building blocks.

6.2. Use cases

This section describes expectations of how clients will interact with a Styles API.

The following use cases assume that:

Note
 The URIs in the use case descriptions are examples and use the domain example.org, a reserved domain maintained by IANA for illustrative examples in documents without prior coordination with IANA.

6.2.1. 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.

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.

6.2.2. A visual style editor creating a new style

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.

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:

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, 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.

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.

If the user requests the use of a Style repository that the editor interacts with for the first time, the editor will again inspect the capabilities of the repository by fetching the conformance declaration at http://example.org/styles-api/conformance.

At least the following conformance classes must be supported in order for sharing the new style via the repository.

Finally, the repository has to support the native stylesheet language that the user has selected for the style definition, i.e. one of:

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/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 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.

6.2.3. A visual style editor updating an existing style

The process is quite similar to the previous example with the following changes:

6.2.4. 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}/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.

7. API building blocks for styles

7.1. Base resources

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}.

7.2. 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.

7.3. 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.

Table 2. Overview of resources and applicable HTTP methods
Resource Path HTTP method Conformance class Document reference

Base resource

{baseResource}

GET

core

Base resource

Conformance declaration

/conformance

GET

core

Declaration of conformance classes

Styles

{baseResource}/styles

GET

core

Fetch styles

POST

manage-styles

Create a new style

style-validation

Validate a style

Style

{baseResource}/styles/{styleId}

GET

core

Fetch style

PUT

manage-styles

Replace a style

style-validation

Validate a style

DELETE

manage-styles

Delete a style

Style metadata

{baseResource}/styles/{styleId}/metadata

GET

core

Fetch style metadata

PUT

manage-styles

Replace the metadata of a style

PATCH

manage-styles

Update the metadata of a style

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.

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.

7.4. Requirements Class "Core"

Requirements Class

http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/core

Target type

Web API

Dependency

OGC API - Common - Part 1: Core, Requirements Classes "Core"

7.4.1. OGC API - Common - Part 1: Core

At the time of writing, OGC API - Common - Part 1: Core 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.

7.4.2. Base resource

Example 1. 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.

{
  "links": [
    {
      "href": "https://example.org/api/v1",
      "rel": "self",
      "type": "application/json",
      "title": "this document"
    },
    {
      "href": "https://example.org/api/v1/api",
      "rel": "service-desc",
      "type": "application/vnd.oai.openapi+json;version=3.0",
      "title": "the API definition in OpenAPI JSON"
    },
    {
      "href": "https://example.org/api/v1/api.html",
      "rel": "service-doc",
      "type": "text/html",
      "title": "the API documentation in HTML"
    },
    {
      "href": "https://example.org/api/v1/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": "http://www.opengis.net/def/rel/ogc/1.0/styles",
      "type": "application/json",
      "title": "the styles shared via this API"
    }
  ]
}

7.4.3. Declaration of conformance classes

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 2. Conformance declaration in JSON
{
  "conformsTo": [
    "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"
  ]
}

7.4.4. Fetch styles

This operation returns a list of styles that are currently available for the base resource.

Requirement 2

/req/core/styles-op

A

The server SHALL support the HTTP GET operation at the path {baseResource}/styles.

Requirement 3

/req/core/styles-success

A

A successful execution of the operation SHALL be reported as a response with an HTTP status code 200.

B

The content of that response SHALL be based upon the following OpenAPI 3.0 schema:

type: object
required:
  - styles
properties:
  styles:
    type: array
    items:
      type: object
      required:
        - id
        - links
      properties:
        id:
          type: string
        title:
          type: string
        links:
          type: array
          minItems: 1
          items:
            $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml'
  default:
    type: string

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 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.

G

The default member SHALL, if provided, be the id of one of the styles in the styles array.

H

If a http://www.opengis.net/def/rel/ogc/1.0/schema link to a URI for the schema of the data is available for a style in the style metadata (see recommendation /rec/core/style-md-schema), a link with the same link relation type SHALL also be provided in the Styles resource.

I

If a thumbnail is available for a style in the style metadata (see recommendation /rec/core/style-md-preview), a link with the link relation type preview SHALL also be provided in the Styles resource.

The http://www.opengis.net/def/rel/ogc/1.0/schema and preview links are also part of the style metadata. If available, they have to be included for a style in the Styles resource, too, so that clients have access to this information without the need to send requests for all style metadata resources.

Recommendation 1

/rec/core/style-title

A

If a style has a title, it SHOULD be included in the title member of the style object.
Example 3. JSON encoding of styles
{
  "default": "topographic",
  "styles": [
    {
      "id": "night",
      "title": "Topographic night style",
      "links": [
        {
          "href": "https://example.com/api/v1/styles/night?f=mapbox",
          "type": "application/vnd.mapbox.style+json",
          "rel": "stylesheet"
        },
        {
          "href": "https://example.com/api/v1/styles/night?f=sld10",
          "type": "application/vnd.ogc.sld+xml;version=1.0",
          "rel": "stylesheet"
        },
        {
          "href": "https://example.com/api/v1/styles/night/metadata?f=json",
          "type": "application/json",
          "rel": "describedby"
        },
        {
          "href": "https://registry.example.com/data/schemas/tds/6.1",
          "type": "application/json",
          "rel": "http://www.opengis.net/def/rel/ogc/1.0/schema"
        },
        {
          "href": "https://example.com/api/v1/resources/night-thumbnail.png",
          "type": "image/png",
          "rel": "preview"
        }
      ]
    },
    {
      "id": "topographic",
      "title": "Regular topographic style",
      "links": [
        {
          "href": "https://example.com/api/v1/styles/topographic?f=mapbox",
          "type": "application/vnd.mapbox.style+json",
          "rel": "stylesheet"
        },
        {
          "href": "https://example.com/api/v1/styles/topographic?f=sld10",
          "type": "application/vnd.ogc.sld+xml;version=1.0",
          "rel": "stylesheet"
        },
        {
          "href": "https://example.com/api/v1/styles/topographic/metadata?f=json",
          "type": "application/json",
          "rel": "describedby"
        },
        {
          "href": "https://registry.example.com/data/schemas/tds/6.1",
          "type": "application/json",
          "rel": "http://www.opengis.net/def/rel/ogc/1.0/schema"
        },
        {
          "href": "https://example.com/api/v1/resources/topographic-thumbnail.png",
          "type": "image/png",
          "rel": "preview"
        }
      ]
    }
  ]
}

7.4.5. Fetch style

This operation returns the stylesheet of a style.

Requirement 4

/req/core/style-op

A

The server SHALL support the HTTP GET operation at the path {baseResource}/styles/{styleId} for each style referenced from the Styles resource at {baseResource}/styles.

Requirement 5

/req/core/style-success

A

A successful execution of the operation SHALL be reported as a response with an HTTP status code 200.

B

The content of that response SHALL conform to the media type stated in the Content-Type header.

C

The language used in linguistic text in the response SHALL be consistent with the language stated in the Content-Language header.

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.

7.4.6. Fetch style metadata

This operation returns the metadata of a style.

Requirement 6

/req/core/style-md-op

A

The server SHALL support the HTTP GET operation at the path {baseResource}/styles/{styleId}/metadata for each style metadata referenced from the Styles resource at {baseResource}/styles.

Requirement 7

/req/core/style-md-success

A

A successful execution of the operation SHALL be reported as a response with an HTTP status code 200.

B

The content of that response SHALL be based upon the following OpenAPI 3.0 schema:

type: object
required:
  - id
properties:
  id:
    type: string
    title: Style Identifier
    description: the identifier of the style
  title:
    type: string
    title: Title
    description: a title for the style, suitable for indicating the style usage in a style listing.
  description:
    type: string
    title: Description
    description: a longer description of the style, including all information needed to facilitate understanding, such as applicability, classification methods, reference to norms and whatever other information the user should be aware of before using the style
  keywords:
    type: array
    title: Keywords
    description: a list of well-known keywords that would help locating the style in a catalog
    items:
      type: string
  pointOfContact:
    type: string
    title: Point of Contact
    description: information that can be used to contact the authors or custodians for the style (free form, can be anything from an e-mail address to physical address and phone numbers)
  license:
    type: string
    title: License
    description: the license under which the style is made available
  created:
    type: string
    format: date-time
    title: Created
    description: the timestamp when the style was first produced
  updated:
    type: string
    format: date-time
    title: Updated
    description: the timestamp of the last style change/revision
  scope:
    type: string
    title: Scope
    description: the scope of this metadata record, fixed to "style"
    enum:
      - style
  version:
    type: string
    title: Version
    description: the version number for the current stylesheets of the style
  stylesheets:
    type: array
    title: Stylesheets
    description: the documents in different style encodings in which the style is available
    items:
      type: object
      required:
        - link
      properties:
        title:
          type: string
          title: Title
          description: the title of the encoding language, e.g. Mapbox Style, SLD, GeoCSS or CMSS
        version:
          type: string
          title: Version
          description: the version of the encoding language used, e.g., 1.0
        specification:
          type: string
          format: url
          title: Specification
          description: a link to the style encoding specification, e.g. https://docs.mapbox.com/mapbox-gl-js/style-spec/
        native:
          type: boolean
          title: Native
          description: true or false, indicating if this is the native encoding of the style, possibly hand prepared, or an on-the-fly conversion, with potential loss of details in the process
        link:
          $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml'
  layers:
    type: array
    title: Data Layers
    description: the layers involved in the symbolization (which might be just one), and the attributes used by the style for each layer (could be none); while part of this information could be retrieved from the stylesheets themselves, this is a succinct representation enumerating the minimum set of data the style needs in order to actually symbolize data
    items:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          title: Identifier
          description: a layer id, typically the same identifier used in the style to refer to the layer
        description:
          type: string
          title: Description
          description: a layer description, which can be used to understand the role of the layer in the style
        dataType:
          type: string
          title: Data Type
          description: the type of data represented in the layer
          examples:
            - vector
            - map
            - coverage
            - model
            - pointCloud
            - mesh
        geometryDimension:
          type: integer
          title: Geometry Dimension
          description: 'the dimension of the geometries of the features shown in this layer, if dataType is "vector"; values are (0: points, 1: curves, 2: surfaces, 3: solids); the property will be absent, if the geometries have a mixed dimension or the dimension is unknown'
          enum:
            - 0
            - 1
            - 2
            - 3
        propertiesSchema:
          type: object
          title: Attributes
          description: the properties that the style needs in order to perform filtering, classification, symbolization
          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
    title: Links
    description: links of the style metadata, including the "self" and "alternate" links
    items:
      $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.

Recommendation 2

/rec/core/style-md-sample-data

A

Sample data that can be used to illustrate the style SHOULD be represented as links with the following link relation types:

  • enclosure for links to sample data that may be downloaded (e.g. a GeoPackage);

  • collection for links to a Collection resource according to OGC API Common (e.g. /collections/{collectionId}; the collection may be available as features (tiled or not) or as gridded data);

  • start for links to a Features resource according to OGC API Features (e.g. /collections/{collectionId}/items; the response may contain a next link to additional features);

  • http://www.opengis.net/def/rel/ogc/1.0/tilesets-vector for a link to a Tile Sets resource (e.g. /collections/{collectionId}/tiles) with vector tiles.

  • http://www.opengis.net/def/rel/ogc/1.0/tilesets-coverage for a link to a Tile Sets resource (e.g. /collections/{collectionId}/tiles) with coverage tiles.

TODO: Add guidance for links to coverage data?

Recommendation 3

/rec/core/style-md-schema

A

If a style can be used to style multiple geospatial datasets that implement a common schema and where a canonical URI exists for the schema, a link with the link relation type http://www.opengis.net/def/rel/ogc/1.0/schema SHOULD be provided.

The schema links indicate to clients that the style is suitable for styling any dataset distribution that conforms to the schema identified by the target URI.

Clients that are familiar with the schema that is identified in a schema link will in general have no need for the information in the layers member, because they already "know" the layers in the schema and their properties.

Note
 It has been proposed to register URIs for commonly used schemas in the OGC Definition Server. The target URIs, if dereferenced, should provide the content of the "layer" member as defined in the style metadata schema.

Recommendation 4

/rec/core/style-md-preview

A

A link to a thumbnail SHOULD be included with link relation preview (specified by RFC 6903) and the appropriate media type in the type parameter.

The thumbnail may be an image that is published as a resource in the API. The thumbnail can reference an appropriate raster tile, a map request, etc.

Example 4. Style metadata in JSON
{
  "id": "night",
  "title": "Topographic night style",
  "description": "This topographic basemap style is designed to be used in situations with low ambient light. The style supports datasets based on the TDS 6.1 specification.",
  "keywords": [
    "basemap",
    "TDS",
    "TDS 6.1",
    "OGC API"
  ],
  "pointOfContact": "John Doe",
  "accessConstraints": "unclassified",
  "dates": {
    "creation": "2019-01-01T10:05:00Z",
    "publication": "2019-01-01T11:05:00Z",
    "revision": "2019-02-01T11:05:00Z",
    "validTill": "2019-02-01T11:05:00Z",
    "receivedOn": "2019-02-01T11:05:00Z"
  },
  "scope": "style",
  "version": "1.0.0",
  "stylesheets": [
    {
      "title": "Mapbox Style",
      "version": "8",
      "specification": "https://docs.mapbox.com/mapbox-gl-js/style-spec/",
      "native": true,
      "tilingScheme": "GoogleMapsCompatible",
      "link": {
        "href": "https://example.org/api/v1/styles/night?f=mapbox",
        "rel": "stylesheet",
        "type": "application/vnd.mapbox.style+json"
      }
    },
    {
      "title": "OGC SLD",
      "version": "1.0",
      "native": false,
      "link": {
        "href": "https://example.org/api/v1/styles/night?f=sld10",
        "rel": "stylesheet",
        "type": "application/vnd.ogc.sld+xml;version=1.0"
      }
    }
  ],
  "layers": [
    {
      "id": "VegetationSrf",
      "type": "polygon",
      "sampleData": {
        "href": "https://demo.ldproxy.net/daraa/collections/VegetationSrf/items?f=json&limit=100",
        "rel": "start",
        "type": "application/geo+json"
      },
      "attributes": {
        "F_CODE": {
          "type": "string"
        }
      }
    },
    {
      "id": "HydrographyCrv",
      "type": "line",
      "sampleData": {
        "href": "https://demo.ldproxy.net/daraa/collections/HydrographyCrv/items?f=json&limit=100",
        "rel": "start",
        "type": "application/geo+json"
      },
      "attributes": {
        "F_CODE": {
          "type": "string"
        }
      }
    }
  ],
  "links": [
    {
      "href": "https://example.org/api/v1/resources/night-thumbnail.png",
      "rel": "preview",
      "type": "image/png",
      "title": "thumbnail of the night style applied to OSM data from Daraa, Syria"
    },
    {
      "href": "https://registry.example.com/data/schemas/tds/6.1",
      "type": "application/json",
      "rel": "http://www.opengis.net/def/rel/ogc/1.0/schema"
    }
  ]
}

7.5. Requirements Class "Manage styles"

Requirements Class

http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/manage-styles

Target type

Web API

Dependency

Requirements Class "Core"

Dependency

OGC API - Features - Part 4: Create, Replace, Update and Delete, Requirements Class "Create/Replace/Delete"

Conditional Dependency

OGC API - Features - Part 4: Create, Replace, Update and Delete, Requirements Class "Update"

Conditional Dependency

RFC 7396 (JSON Merge Patch)

This section defines requirements for the case when the resources that are created, replaced, updated and deleted are styles. The general rules for Create/Replace/Delete/Update operations are specified in OGC API - Common - Part 4: Create, Replace, Update and Delete; Requirements Classes "Create/Replace/Delete" and "Update". This section specifies how those requirements apply to the API building blocks for styles.

7.5.1. Resources endpoint

Create a new style

Requirement 8

/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 5. New style response

The URI of the new style is https://example.org/api/v1/styles/night.

HTTP/1.1 201 Created
Date: Sun, 28 Jul 2019 12:32:34 GMT
Location: https://example.org/api/v1/styles/night

Recommendation 1

/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.
Update the default style

The PATCH operation on {baseResource}/styles updates the default style of the style collection.

Requirement 9

/req/manage-styles/default-style-update

Condition

Server implements OGC API - Features - Part 4: Create, Replace, Update and Delete, Requirements Class "Update"

Condition

Server advertises support for media type application/merge-patch+json in the API definition for PATCH requests at {baseResource}/styles

A

The server SHALL process PATCH requests with a content type application/merge-patch+json to such a resource endpoint as specified by RFC 7396 (JSON Merge Patch).

B

The content of the request SHALL be based upon the following OpenAPI 3.0 schema:

type: object
properties:
  default:
    type: string
    nullable: true

A value null will remove the default member, i.e., there is no default style in the style collection. A value that is a valid style identifier in the collection will set that style as the default style. Otherwise an error will be returned.

7.5.2. Resource endpoints

Requirement 10

/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).

7.5.3. Replace a style

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.

7.5.4. Delete a style

This operation deletes the style with the id styleId. If no such style exists, an error is returned.

Deleting a style also deletes the subordinate resources, i.e., the style metadata.

Requirement 11

/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.

7.5.5. Replace the metadata of a style

Servers can support the PUT operation on {baseResource}/styles/{styleId}/metadata to replace the metadata of the style with the id styleId. If no such style exists, an error is returned.

Permission 2

/per/manage-styles/replace-style-md

A

The server MAY accept style metadata based on the schema requirement /req/core/style-md-success, item B in all encodings supported by the API.

B

The server MAY ignore parts of the submitted metadata, in particular information that is managed by the server.

For example, links of the link relation types self and alternate or the stylesheets array are in general automatically set by the server.

7.5.6. Update the metadata of a style

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.

Requirement 12

/req/manage-styles/metadata-update

Condition

Server implements OGC API - Features - Part 4: Create, Replace, Update and Delete, Requirements Class "Update"

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 RFC 7396 (JSON Merge Patch).

B

The content of the request SHALL be based upon the OpenAPI 3.0 schema specified in requirement /req/core/style-md-success, but with all properties set to nullable: true (so that they can be deleted).

From the RFC 7396 (JSON Merge Patch) specification:

A JSON merge patch document describes changes to be made to a target JSON document using a syntax that closely mimics the document being modified. Recipients of a merge patch document determine the exact set of changes being requested by comparing the content of the provided patch against the current content of the target document. If the provided merge patch contains members that do not appear within the target, those members are added. If the target does contain the member, the value is replaced. Null values in the merge patch are given special meaning to indicate the removal of existing values in the target.

Some examples using JSON Merge Patch:

To add or update the point of contact, the access constraint and the revision date, just send:

{
  "pointOfContact": "Jane Doe",
  "accessConstraints": "restricted",
  "dates": {
    "revision": "2019-05-17T11:46:12Z"
  }
}

To remove the point of contact, the access constraint and the revision date, send:

{
  "pointOfContact": null,
  "accessConstraints": null,
  "dates": {
    "revision": null
  }
}

For arrays the complete array needs to be sent. To add a keyword to the example style metadata object, send:

{
  "keywords": [ "basemap", "TDS", "TDS 6.1", "OGC API", "new keyword" ]
}

To remove the "TDS" keyword, send:

{
  "keywords": [ "basemap", "TDS 6.1", "OGC API", "new keyword" ]
}

To remove the keywords, send:

{
  "keywords": null
}

The same applies to stylesheets, layers and links. To update these members, the complete new array value has to be sent.

7.5.7. Changes to a style with multiple occurrences in an API

An OGC Web API can include multiple style resources with the same style identifier.

Example: An API can provide a style with identifier "night" for a dataset (path /styles/night) and for each collection (path template /collections/{collectionId}/styles/night). Typically, the style for a collection will not include rendering rules for the data in the other collections in the dataset.

The behavior of an API how a change to one of style resources affects the style resources in the API with the same identier is not specified by this requirements class. Options include:

  • APIs may reject update or replace operations on selected style resources. For example, if the stylesheets for the collections are derived from the stylesheet for the dataset, the API can support only changes to the dataset style and provide the collection styles as derived, read-only styles.

  • An API can implement create, update or replace operations for the collection styles so that the changes have the effect of adding, replacing or deleting the definition of the specified style as it pertains to the specified collection. E.g., after a DELETE of /collections/foo/styles/night, a future GET of /collections/foo/styles/night would return a 404 (Not Found) response, whereas a future GET of /styles/night would return a style definition that lacks any mention of collection foo.

  • An API can implement create, update or replace operations for the collection styles so that all changes to one style resource have no effect on other style resources including those with the same idetifier.

Permission 3

/per/manage-styles/styles-with-same-id

A

Changes to a style MAY or MAY NOT change other style resources in the API with the same style identifier.

Recommendation 5

/rec/manage-styles/doc-styles-with-same-id

A

If the API includes multiple style resources with the same style identifier, the API documentation SHOULD specify how changes to one of the style resource will affect the other style resources with the same identifier.

7.6. Requirements Class "Validation of styles"

Requirements Class

http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/style-validation

Target type

Web API

Dependency

Requirements Class "Manage styles"

Dependency

RFC 7240 "Prefer Header for HTTP"

7.6.1. Validate a style

Requirement 13

/req/style-validation/input

A

The server SHALL support the Prefer header with the handling=strict.

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:

name: validate
in: query
required: false
style: form
explode: false
schema:
  type: boolean
  default: false

Requirement 14

/req/style-validation/output

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 dry-run is provided or the parameter has the value 'false', the standard response for a Create or Replace operation is returned.

7.7. Requirements Class "OGC SLD 1.0"

Requirements Class

http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/sld-10

Target type

Web API

Dependency

Requirements Class "Manage styles"

Dependency

Styled Layer Descriptor, Version 1.0

Requirement 15

/req/sld-10/media-type

A

Every POST or PUT operation of the server that accepts a stylesheet document as content SHALL support the media type application/vnd.ogc.sld+xml;version=1.0.

Requirement 16

/req/sld-10/valid

A

Every POST or PUT operation of the server that accepts a stylesheet document as content SHALL accept valid OGC SLD 1.0 documents without errors.

The list of operations in a server implementing all conformance classes of this draft specification is:

  • POST {baseResource}/styles

  • PUT {baseResource}/styles/{styleId}

7.7.1. Expected content in an SLD 1.0 document

Requirement 17

/req/sld10/root

A

In accordance with the SLD 1.0 standard, the root element of every SLD 1.0 stylesheet SHALL be a StyledLayerDescriptor element.

The content of a stylesheet document will typically depend on the {baseResource}:

Requirement 18

/req/sld10/content

A

The document SHALL contain one or more NamedLayer or UserLayer elements, each with at least one UserStyle.

B

If {baseResource} is a Collection or Landing Page of an API that publishes a dataset (i.e., it includes a Collections resource at /collections), names corresponding to collection ids SHALL be specified as the FeatureTypeName of a FeatureTypeStyle (for a feature collection) or as the CoverageName of a CoverageStyle (for a coverage), and/or as the Name of a NamedLayer (for compatibility with this alternate approach to associate styles with collections).

Recommendation 6

/rec/sld10/style-names

A

If a UserStyle has a name, it SHOULD correspond to the style id. The name is not relevant for the processing of the style, but may be assigned as the style id when posting a new style.

B

The UserStyle SHOULD contain a FeatureTypeStyle element with a FeatureTypeName, or CoverageStyle element with a CoverageName corresponding to the collection id.

In the case of a NamedLayer with both a Name and a FeatureTypeStyle with a FeatureTypeName (or a CoverageStyle with a CoverageName), clients should be prepared to understand either of them, with the more specific FeatureTypeName or CoverageName taking priority (as in some cases the Name of the NamedLayer may refer to a particular symbolization, e.g. casing or center line).

If there are multiple UserStyle elements in a layer, clients should use the style with a name that matches the style id, if there is one. Otherwise they should pick any of the styles.

7.8. Requirements Class "OGC SLD 1.1"

Requirements Class

http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/sld-11

Target type

Web API

Dependency

Requirements Class "Manage styles"

Dependency

Styled Layer Descriptor profile of the Web Map Service Implementation Specification, Version 1.1

Requirement 19

/req/sld-11/media-type

A

Every POST or PUT operation of the server that accepts a stylesheet document as content SHALL support the media type application/vnd.ogc.sld+xml;version=1.1.

Requirement 20

/req/sld-11/valid

A

Every POST or PUT operation of the server that accepts a stylesheet document as content SHALL accept valid OGC SLD 1.1 documents without errors.

The list of operations in a server implementing all conformance classes of this draft specification is:

  • POST {baseResource}/styles

  • PUT {baseResource}/styles/{styleId}

7.8.1. Expected content in an SLD 1.1 document

The same rules apply like for SLD 1.0 documents.

7.9. Requirements Class "Mapbox Style"

Requirements Class

http://www.opengis.net/spec/ogcapi-styles-1/1.0/req/mapbox-style

Target type

Web API

Dependency

Requirements Class "Manage styles"

Dependency

Mapbox Style Specification, Version 8

Requirement 21

/req/mapbox-style/media-type

A

Every POST or PUT operation of the server that accepts a stylesheet document as content SHALL support the media type application/vnd.mapbox.style+json.

Requirement 22

/req/mapbox-style/content

A

Every POST or PUT operation of the server that accepts a stylesheet document as content SHALL accept valid Mapbox Style documents (version 8) without errors.

The list of operations in a server implementing all conformance classes of this draft specification is:

  • POST {baseResource}/styles

  • PUT {baseResource}/styles/{styleId}

8. Media Types

application/json is the JSON media type used for all content except the stylesheets and the symbol resources.

text/html is the HTML media type for all "web pages" provided by the API.

No media types have been formally registered with IANA for the style encodings (Mapbox Styles and OGC SLD). Temporary media types in the vnd-branch as specified below are used for now.

8.1. application/vnd.mapbox.style+json

  • Type name: application

  • Subtype name: vnd.mapbox.style+json

  • Required parameters: n/a

  • Optional parameters: n/a

  • Encoding considerations: See RFC 8259, The JavaScript Object Notation (JSON) Data Interchange Format

  • Security considerations: See Section 12 of RFC 8259

  • Interoperability considerations: n/a

  • Published specification: Mapbox Style Specification, Version 8

  • Applications that use this media type: Geographic information systems (GIS)

  • Additional information:

    • Deprecated alias names for this type: n/a

    • Magic number(s): n/a

    • File extension(s): .json

    • Macintosh file type code(s): n/a

  • Person to contact for further information: n/a

  • Intended usage: COMMON

  • Restrictions on usage: none

  • Author: n/a

  • Change controller: Mapbox

8.2. application/vnd.ogc.sld+xml

  • Type name: application

  • Subtype name: vnd.ogc.sld+xml

  • Required parameters: n/a

  • Optional parameters:

    • "charset": See Section 3 of RFC 7303.

    • "version": If provided, this parameter indicates the major and the first minor version number of the SLD version used in the document, e.g. "1.1".

      • Syntax: version = 1*DIGIT "." 1*DIGIT. The first group of digits is the major version number, the second group is the minor version number.

      • The parameter can be used to provide protocol-specific operations, such as version-based content negotiation in HTTP. The parameter is a hint, if used in HTTP content negotiation. I.e., client implementations should be prepared to receive content in a different version than requested and server implementations should honor the version parameter during content negotiation, if possible.

  • Encoding considerations: Same as application/xml - see section 9.1 of RFC 7303.

  • Security considerations: OGC SLD is a generic XML grammar, but application designers must not assume that it provides generic protection against security threats. RFC 7303, Section 10, discusses security concerns for generic XML, which are also applicable to SLD. Xlink references inSLD documents may cause arbitrary URIs to be dereferenced. In this case, the security issues of RFC 3986, section 7, should be considered. SLD documents do not contain active or executable content.

  • Interoperability considerations: n/a

  • Published specification: OGC: OGC 02-070, Styled Layer Descriptor, Version 1.0 (2002) and OGC: OGC 05-078r4, Styled Layer Descriptor, Version 1.1 (2007)

  • Applications that use this media type: Geographic information systems (GIS)

  • Additional information:

    • Deprecated alias names for this type: n/a

    • Magic number(s): n/a

    • File extension(s): .sld, .xml

    • Macintosh file type code(s): n/a

  • Person to contact for further information: n/a

  • Intended usage: COMMON

  • Restrictions on usage: none

  • Author: n/a

  • Change controller: OGC

Annex A: Conformance Class Abstract Test Suite (Normative)

TODO: The ATS needs to be updated and has been commented out until the requirements classes are stable.

Annex B: Revision History

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)

May 19, 2021

C. Portele

1.0.0-draft.1

all

version for OGC May 2021 Code Sprint

Annex C: Bibliography

  1. IETF: RFC 7946 - The GeoJSON Format

  2. OGC: OGC Testbed-15: Encoding and Metadata Conceptual Model for Styles Engineering Report. OGC 19-023, Open Geospatial Consortium (2019)

  3. Mapbox: Mapbox Style Specification, Version 8