Publication Date: YYYY-MM-DD

Approval Date: YYYY-MM-DD

Submission Date: YYYY-MM-DD

Reference number of this document: OGC 19-010

Reference URL for this document: http://www.opengis.net/doc/PER/t15-D012

Category: OGC Public Engineering Report

Editor: Clemens Portele

Title: OGC Testbed-15: Styles API Engineering Report

OGC Public Engineering Report

COPYRIGHT

Copyright © 2019 Open Geospatial Consortium. To obtain additional rights of use, visit http://www.opengeospatial.org/

WARNING

This document is not an OGC Standard. This document is an OGC Public Engineering Report created as a deliverable in an OGC Interoperability Initiative and is not an official position of the OGC membership. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an OGC Standard. Further, any OGC Public Engineering Report should not be referenced as required or mandatory technology in procurements. However, the discussions in this document could very well lead to the definition of an OGC Standard.

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.

None of the Intellectual Property or underlying information or technology may be downloaded or otherwise exported or reexported in violation of U.S. export laws and regulations. In addition, you are responsible for complying with any local laws in your jurisdiction which may impact your right to import, export or use the Intellectual Property, and you represent that you have complied with any regulations or registration procedures required by applicable law to make this license enforceable.

Table of Contents

1. Subject

The Styles API is a Web API that enables map servers and clients as well as visual style editors to manage and fetch styles. The API is consistent with the emerging OGC API family of standards. The API complements the Features, Maps and Tiles APIs and builds on the conceptual model for styles developed in OGC Testbed-15. This report specifies the API using OpenAPI, specifies how the same styles should be represented in a GeoPackage and documents the lessons learnt during the implementation.

2. Executive Summary

Note
 TODO
This clause will eventually contain the key findings, results, an overview of recommendations, and a business value statement. A more detailed description of the findings will be in the body of the report. This section should be between 1-3 pages.

OGC is missing a robust conceptual model and APIs capable of supporting multiple style encodings and the style encodings themselves. The Open Portrayal Framework (OPF) task in Testbed-15 is addressing this issue, building on recent portrayal activities in OGC. This report is focussing on the building blocks for Web APIs to manage and fetch styles.

The APIs have several types of consumers. The main consumers in Testbed-15 are:

  • Visual style editors create, update and delete styles for datasets that are shared by other Web APIs implementing OGC API Features, OGC API Coverages or OGC API Tiles;

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

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

Feature data is either accessed directly or organized in spatial partitions ("vector tiles").

The Styles API is consistent with the emerging OGC API family of standards and could be a starting point for an "OGC API - Styles" standard.

The Styles API implements the conceptual model for styles as documented in chapter 6 of the "OGC Testbed-15: Concept Model for Style Encoding & Metadata Model Engineering Report".

The model defines three main concepts:

The style is the main resource.

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 tool capabilities and preferences.

For each style there is style metadata available, with general descriptive information about the style, structural information (e.g., layers and attributes), etc. 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, which supports the resources and operations listed in the Table below.

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

Landing page

/

GET

API landing page

Conformance declaration

/conformance

GET

Declaration of conformance classes

Styles

/styles

GET

Fetch styles

POST

Create a new style

Validate a style

Style

/styles/{styleId}

GET

Fetch style

PUT

Update or create a style

Validate a style

DELETE

Delete a style

Style metadata

/styles/{styleId}/metadata

GET

Fetch style metadata

PUT

Replace the metadata of a style

PATCH

Update parts of the metadata of a style

Resources

/resources

GET

Fetch resources

Resource

/resources/{resourceId}

GET

Fetch resource

PUT

Create or replace a resource

DELETE

Delete a resource

In order to support styles, data APIs (for example, supporting OGC API Features and/or OGC API Tiles) need 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 like visual style editors to construct expressions for selection criteria in queries on features in the collection.

Note
 TODO
Add GeoPackage and conclusions summary.

2.1. Document contributor contact points

All questions regarding this document should be directed to the editor or the contributors:

Contacts

Name Organization Role

Clemens Portele

interactive instruments GmbH

Editor

…​

…​

Contributor

2.2. Foreword

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 standard set forth in this document, and to provide supporting documentation.

3. References

The following documents are normatively referenced in this document.

4. Terms and definitions

For the purposes of this report, the definitions specified in Clause 4 of the OWS Common Implementation Standard OGC 06-121r9 shall apply. In addition, the following terms and definitions apply.

style

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

style encoding

specification to express a style as one or more files

Note
 In Testbed-15 Mapbox Styles, OGC SLD versions 1.0 and 1.1 are used.
stylesheet

representation of a style in a style encoding

style metadata

essential information about a style in order to support users to discover and select styles for rendering their data and for visual style editors to create user interfaces for editing a style

Web API

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

Note
 Best Practice 24: Use Web Standards as the foundation of APIs in the W3C Data on the Web Best Practices provides more detail.

4.1. Abbreviated terms

API

Application Programming Interface

OGC

Open Geospatial Consortium

SLD

OGC Styled Layer Descriptor

5. Overview

OGC is missing a robust conceptual model and APIs capable of supporting multiple style encodings and the style encodings themselves. The Open Portrayal Framework (OPF) task in Testbed-15 is addressing this issue, building on recent portrayal activities in OGC. This report focusses on the building blocks for Web APIs to manage and fetch styles.

The APIs have several types of consumers. The main consumers in Testbed-15 are:

  • Visual style editors create, update and delete styles for datasets that are shared by other Web APIs implementing OGC API Features, OGC API Coverages or OGC API Tiles;

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

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

Feature data is either accessed directly or organized in spatial partitions ("vector tiles").

The Styles API is consistent with the emerging OGC API family of standards and could be a starting point for an "OGC API - Styles" standard.

Sections 6 to 8 describe how styles according to the "Concept Model for Style Encoding & Metadata Model Engineering Report" could be implemented in OGC API family of standards. Section 6 starts by looking at how clients interact with the Styles API. Section 7 then specifies the Styles API and section 8 specifies extensions to the core conformance class of OGC API Features / Common.

Section 9 complements this by specifying how the same style concepts could be represented in a GeoPackage.

Section 10 presents the implementations in Testbed 15.

Section 11 provides a summary of the main findings.

6. Use cases

This clause describes expectations how clients will interact with the Styles API.

Let’s assume that a dataset with topographic data according to the TDS 6.1 specification of NGA is available via an API that implements the OGC API Features and Tiles specification. The dataset covers the region of Daraa, Syria. The URI of the landing page is used as {data} in the descriptions below.

In addition, a style repository is available via an API that implements the Styles API. The URI of the landing page is used as {styles} in the descriptions below.

Roads are included in the data in the collection transportationgroundcrv as features with a property f_code with a value of AP030.

6.1. A visual style editor creating a new style

A user wants to create a new style for TDS roads using her visual style editor. She knows the Daraa dataset and the data access API.

After creating a new style, selecting the native stylesheet language for the style and identifying the transportationgroundcrv collection in the Daraa dataset as a sample data source, the visual style editor executes a request to {data}/conformance of the data access API to determine the API capabilities. Note that alternatively also the API definition may be inspected, but for a client that supports the OGC API standards in general, using the conformance declaration is simpler and, therefore, used in this example.

If the editor supports both styling of GeoJSON features or Mapbox Vector Tile data, the editor requires support for at least one of the two following sets of conformance classes:

The first one provides access to GeoJSON features via {data}/collections/transportationgroundcrv/items, the second one provides access to MVT tiles via {data}/collections/transportationgroundcrv/tiles.

Note
 For conformance classes that have not yet been specified hypothetical URIs with "t15" instead of "spec" are used.

In addition, the visual style editor will look for the following conformance classes:

The editor will also request information about the features in the collection via a request to {data}/collections/transportationgroundcrv.

If http://www.opengis.net/t15/ogcapi-features-n/1.0/conf/queryables is supported the queryables are retrieved via a request to {data}/collections/transportationgroundcrv/queryables.

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 Daraa data. Once she has finished the style, the style will be published on a Style repository that supports the Styles API.

If the user request 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 {styles}/conformance.

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

In addition, if the style includes symbols or sprites, the repository also has to support the following conformance classes:

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 (username and password) in the style repository and use the credentials in any of the following POST/PUT/PATCH 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 {styles}/styles?validate=only.

To create the new style either a POST request with the stylesheet to {styles}/styles or a PUT request to {styles}/styles/{stylename} (where {stylename} is the name of the style specified by the user) is sent. ?validate=true may be added to the request URI to trigger validation in this step, too, if the style validation conformance class is supported. If PUT is used, the visual style editor should check that no existing style {stylename} exists.

After a succesful creation of the style (in case of a POST request, the URI of the new style {styles}/styles/{stylename} is returned in a HTTP header Location), the visual style editor will update the style metadata using a PUT or PATCH request to {styles}/styles/{stylename}/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 {data}/collections/transportationgroundcrv.

6.2. 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. I.e., the user will open/load the style from the style repository and the editor will fetch it from {styles}/styles/{stylename} (using the stylesheet language of choice) and its metadata from {styles}/styles/{stylename}/metadata.

  • If the style metadata includes links to sample data (e.g., {data}/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 {styles}/styles/{stylename} (no POST request to {styles}/styles, which would create a new style).

6.3. A map client

A map client that wants to visualize data for features or vector tiles for the collection {data}/collections/transportationgroundcrv will look for a styles member in the response. It 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.

7. Styles API

7.1. Scope

The Styles API

  • is a Web API that enables map servers and clients as well as visual style editors to manage and fetch styles;

  • is consistent with the emerging OGC API family of standards and complements the Features, Maps and Tiles APIs;

  • builds on the conceptual model for styles developed in OGC Testbed-15.

The API is specified using OpenAPI 3.0.

7.2. Conformance

There are five requirements/conformance classes for the Web API:

  • "core": All implementations have to implement this class that 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": This class adds the capabilities to create, update and delete styles and their metadata.

  • "style-validation": This class adds the capability to validate a stylesheet.

  • "resources": This class adds the capabilities to provide access to resources referenced from stylesheets (symbols, sprites).

  • "manage-resources": This class adds the capabilities to create, update and delete resources.

In addition, there are also four requirements/conformance classes for the encodings supported by the resources of the API:

  • "html": This class supports HTML in responses to GET requests to all requests to the Styles API.

  • "mapbox-styles": This class supports Mapbox Styles as a style encoding.

  • "sld-10": This class supports OGC SLD 1.0 as a style encoding.

  • "sld-11": This class supports OGC SLD 1.1 as a style encoding.

Note
 Currently no media types have been registered for Mapbox Styles or OGC SLD. Temporary media types in the vnd-branch are used for now.

7.3. Overview

This clause specifies the Styles API as designed and implemented in the Open Portrayal Framework task of OGC Testbed 15.

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 - all symbols combined in a single bitmap image to reduce memory and the number of http requests. Single symbols and sprites are supported by this API and they may be stored on this server, for example, to avoid issues with cross-origin requests. Of course, existing external symbol libraries may also be referenced from stylesheets.

This API currently does not support font resources and an existing font library has to referenced, if external fonts / glyphs are used in a stylesheet.

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.

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

Landing page

/

GET

core

API landing page

Conformance declaration

/conformance

GET

core

Declaration of conformance classes

Styles

/styles

GET

core

Fetch styles

POST

manage-styles

Create a new style

style-validation

Validate a style

Style

/styles/{styleId}

GET

core

Fetch style

PUT

manage-styles

Update or create a style

style-validation

Validate a style

DELETE

manage-styles

Delete a style

Style metadata

/styles/{styleId}/metadata

GET

core

Fetch style metadata

PUT

manage-styles

Replace the metadata of a style

PATCH

manage-styles

Update parts of the metadata of a style

Resources

/resources

GET

resources

Fetch resources

Resource

/resources/{resourceId}

GET

resources

Fetch resource

PUT

manage-resources

Create or replace a resource

DELETE

manage-resources

Delete a resource

The conceptual model and this specification support multiple style encodings (stylesheets) per style. For example, a Styles API may publish a "night" style as 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 has been written with the following assumptions:

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

7.4. Requirements Class "Core"

Requirements Class

http://www.opengis.net/t15/opf-styles-1/1.0/req/core

Target type

Web API

Dependency

OGC API Common (Core)

7.4.1. OGC API Common (Core)

At the time of writing, the "OGC API Common" standard is not yet available. A draft is in development based on the generic concepts of the OGC API - Features - Part 1: Core" candidate standard, but it is in an early stage 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. The following normative statements are by reference part of this requirements class:

The 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 requirement /req/core/crs84 is not applicable to the Styles API since no geometries are used in the API.

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

Example 1. Landing page in JSON
{
  "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": "conformance",
      "type": "application/json",
      "title": "list of conformance classes implemented by this API"
    },
    {
      "href": "https://example.org/api/v1/styles",
      "rel": "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 a Styles API that implements all requirements classes except "html".

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

7.4.4. Fetch styles

This operation returns a list of styles that are currently available.

Requirement 1

/req/core/styles-op

A

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

Requirement 2

/req/core/styles-success

A

A successful execution of the operation SHALL be reported as a response with a 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
    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: 'https://api.swaggerhub.com/domains/cportele/ogcapi-features-1/1.0.0-draft.2#/components/schemas/link'

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

If a style has a title, it SHALL be included in the title member of the style.

F

Each style SHALL have a link for each style encoding supported for the style (link relation: stylesheet) with the type attribute stating the media type of the style encoding.

G

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.
Example 3. JSON encoding of styles
{
  "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"
        }
      ]
    },
    {
      "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"
        }
      ]
    }
  ]
}

7.4.5. Fetch style

This operation returns the stylesheet of a style.

Requirement 3

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

Requirement 4

/req/core/style-success

A

A successful execution of the operation SHALL be reported as a response with a 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.

7.4.6. Fetch style metadata

This operation returns the metadata of a style.

Requirement 5

/req/core/style-md-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.

Requirement 6

/req/core/style-md-success

A

A successful execution of the operation SHALL be reported as a response with a 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:
    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: 'https://api.swaggerhub.com/domains/cportele/ogcapi-features-1/1.0.0-draft.2#/components/schemas/link'
  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:
          $ref: 'https://api.swaggerhub.com/domains/cportele/ogcapi-draft-extensions/1.0.0#/components/schemas/queryables'
        sampleData:
          $ref: 'https://api.swaggerhub.com/domains/cportele/ogcapi-features-1/1.0.0-draft.2#/components/schemas/link'
  links:
    type: array
    nullable: true
    items:
      $ref: 'https://api.swaggerhub.com/domains/cportele/ogcapi-features-1/1.0.0-draft.2#/components/schemas/link'

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 "OGC Testbed-15: Conceptual Model for Style Encoding & Metadata Model Engineering Report".

Recommendation 1

/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, it may 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://services.interactive-instruments.de/vtp/daraa/collections/vegetationsrf/items?f=json&limit=100",
        "rel": "data",
        "type": "application/geo+json"
      }
    },
    {
      "id": "hydrographycrv",
      "type": "line",
      "sampleData": {
        "href": "https://services.interactive-instruments.de/vtp/daraa/collections/hydrographycrv/items?f=json&limit=100",
        "rel": "data",
        "type": "application/geo+json"
      },
      "attributes": [
        {
          "id": "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"
    }
  ]
}

7.5. Requirements Class "Manage styles"

Requirements Class

http://www.opengis.net/t15/opf-styles-1/1.0/req/manage-styles

Target type

Web API

Dependency

Requirements Class "Core"

Dependency

JSON Merge Patch

7.5.1. Create a new style

This operation creates a new style. The payload of the request is a stylesheet of the style in one of the supported style encodings.

If the style submitted in the request body includes an identifier (this depends on the style encoding), that identifier will be used. If a style with that identifier already exists, an error is returned.

For Mapbox Styles use the value of the name member and for OGC SLD use the value of the Name child element, if these are provided. Note that these elements are in general not meant as identifiers, so using POST to /styles may result in URIs that include encoded characters. To avoid this, use PUT /styles/{styleId} instead and specify the desired styleId.

If no identifier can be determined from the submitted style, the server will assign a new identifier to the style.

The URI of the new style is returned in the header Location.

Requirement 7

/req/manage-styles/create-style-op

A

The server SHALL support the HTTP POST operation at the path /styles.

B

The server SHALL accept a stylesheet in one of the style encodings supported by the API.

Requirement 8

/req/manage-styles/create-style-success

A

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

B

The response SHALL include a header Location with the URI of the new style.

C

A minimal style metadata resource SHALL be created at /styles/{styleId}/metadata.

Note that the metadata will be incomplete and should be updated by the client to keep the style metadata consistent with the style definition.

Requirement 9

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

B

If the request is valid, but the server already has a style with the identifier stated in the spreadsheet, a response with status code 409 SHALL be returned.
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

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

Requirement 10

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

Requirement 11

/req/manage-styles/update-style-success

A

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

B

If a new style is created, a minimal style metadata resource SHALL be created at /styles/{styleId}/metadata.

Note that the metadata should be updated by the client, too, to keep the style metadata consistent with the style definition.

Requirement 12

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

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

/req/manage-styles/delete-style-op

A

The server SHALL support the HTTP DELETE operation at the path /styles/{styleId}.

Requirement 14

/req/manage-styles/delete-style-success

A

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

B

All subordinate resources including the style metadata at /styles/{styleId}/metadata SHALL be deleted, too.

Requirement 15

/req/manage-styles/delete-style-error

A

If the style does not exist, a response with status code 404 SHALL be returned.

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

Requirement 16

/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 requirement /req/core/style-md-success, item B in all encodings supported by the API.

Requirement 17

/req/manage-styles/update-style-md-success

A

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

B

The style metadata SHALL be replaced by the content submitted in the request.

Requirement 18

/req/manage-styles/update-style-md-error

A

If the style does not exist, a response with status code 404 SHALL be returned.

7.5.5. Update parts of 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.

Requirement 19

/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 requirement /req/core/style-md-success, item B in all encodings supported by the API.

Requirement 20

/req/manage-styles/patch-style-md-success

A

A successful execution of the operation SHALL be reported as a response with a 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).

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:

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.

Requirement 21

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

7.6. Requirements Class "Validation of styles"

Requirements Class

http://www.opengis.net/t15/opf-styles-1/1.0/req/style-validation

Target type

Web API

Dependency

Requirements Class "Manage styles"

7.6.1. Validate a style

Requirement 22

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

name: validate
in: query
required: false
style: form
explode: false
schema:
  type: string
  enum:
    - yes
    - no
    - only
  default: no

Requirement 23

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

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

7.7. Requirements Class "Resources"

Requirements Class

http://www.opengis.net/t15/opf-styles-1/1.0/req/resources

Target type

Web API

Dependency

Requirements Class "Core"

7.7.1. Fetch resources

This operation returns a list of resources that are currently available and that may be used by reference in stylesheets. Resources in the Styles API are symbols, sprites and thumbnails.

For each resource the id and a link to the resource is provided.

Note
 Testbed-15 only requires support for a limited number of the resources. Therefore, the currently simple approach is sufficient, but in general the operation should support paging (using a parameter limit and links to the next page in responses).

Requirement 24

/req/resources/resources-op

A

The server SHALL support the HTTP GET operation at the path /resources.

Requirement 25

/req/resources/resources-success

A

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

B

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

type: object
required:
  - resources
properties:
  resources:
    type: array
    items:
      type: object
      required:
        - id
      properties:
        id:
          type: string
        link:
          $ref: 'https://api.swaggerhub.com/domains/cportele/ogcapi-features-1/1.0.0-draft.2#/components/schemas/link'

C

The resources member SHALL include one item for each resource currently on the server.

D

The id member of each resource SHALL be unique.

E

Each resource SHALL have a link to the resource (link relation: item) with the type attribute stating the media type of the resource.
Example 6. JSON encoding of resources
{
  "resources": [
    {
      "id": "sprite.json",
      "link": {
        "href": "https://example.com/api/v1/resources/sprite.json",
        "type": "application/json",
        "rel": "item"
      }
    },
    {
      "id": "sprite.png",
      "link": {
        "href": "https://example.com/api/v1/resources/sprite.png",
        "type": "image/png",
        "rel": "item"
      }
    },
    {
      "id": "sprite.@2x.png",
      "link": {
        "href": "https://example.com/api/v1/resources/sprite.@2x.png",
        "type": "image/png",
        "rel": "item"
      }
    },
    {
      "id": "mosque.svg",
      "link": {
        "href": "https://example.com/api/v1/resources/mosque.svg",
        "type": "image/svg+xml",
        "rel": "item"
      }
    }
  ]
}

7.7.2. Fetch resource

This operation returns a resource.

Requirement 26

/req/resources/resource-op

A

The server SHALL support the HTTP GET operation at the path /resources/{resourceId} for each resource referenced from /resources.

Requirement 27

/req/resources/resource-success

A

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

B

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

7.8. Requirements Class "Manage resources"

Requirements Class

http://www.opengis.net/t15/opf-styles-1/1.0/req/manage-resources

Target type

Web API

Dependency

Requirements Class "Resources"

Dependency

JSON Merge Patch

7.8.1. Create or replace a resource

This operation creates or replaces the resource with id resourceId.

Requirement 28

/req/manage-resources/update-resource-op

A

The server SHALL support the HTTP PUT operation at path /resources/{resourceId}.

Requirement 29

/req/manage-resources/update-resource-success

A

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

B

The resource SHALL be the content submitted in the request.

7.8.2. Delete a resource

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

Requirement 30

/req/manage-resources/delete-resource-op

A

The server SHALL support the HTTP DELETE operation at the path /resources/{resourceId}.

Requirement 31

/req/manage-resources/delete-resource-success

A

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

Requirement 32

/req/manage-resources/delete-resource-error

A

If the style does not exist, a response with status code 404 SHALL be returned.

7.9. Requirements Class "HTML"

Requirements Class

http://www.opengis.net/t15/opf-styles-1/1.0/req/html

Target type

Web API

Dependency

Requirements Class "Core"

Dependency

HTML 5

Requirement 33

/req/html/get

A

Every 200-response of a GET operation of the server SHALL support the media type text/html.

Requirement 34

/req/html/content

A

Every 200-response of the server with the media type text/html SHALL be a HTML 5 document that includes the following information in the HTML body:

  • all information identified in the schemas of the Response Object in the HTML <body>, and

  • all links in HTML <a> elements in the HTML <body>.

7.10. Requirements Class "Mapbox Styles"

Requirements Class

http://www.opengis.net/t15/opf-styles-1/1.0/req/mapbox-styles

Target type

Web API

Dependency

Requirements Class "Core"

Dependency

Mapbox Style Specification, Version 8

Requirement 35

/req/mapbox-styles/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.

B

Every GET operation of the server that returns a stylesheet document SHALL support the media type application/vnd.mapbox.style+json.

Requirement 36

/req/mapbox-styles/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.

B

Every GET operation of the server that returns a stylesheet document SHALL return a valid Mapbox Style document (version 8), if the media type application/vnd.mapbox.style+json is requested.

The list of operations in a server implementing all current conformance classes is:

  • POST /styles

  • PUT /styles/{styleId}

  • GET /styles/{styleId}

7.11. Requirements Class "OGC SLD 1.0"

Requirements Class

http://www.opengis.net/t15/opf-styles-1/1.0/req/sld-10

Target type

Web API

Dependency

Requirements Class "Core"

Dependency

OGC Styled Layer Descriptor, version 1.0

Requirement 37

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

B

Every GET operation of the server that returns a stylesheet document SHALL support the media type application/vnd.ogc.sld+xml;version=1.0.

Requirement 38

/req/sld-10/content

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.

B

Every GET operation of the server that returns a stylesheet document SHALL return a valid OGC SLD 1.0 document, if the media type application/vnd.ogc.sld+xml;version=1.0 is requested.

See the Mapbox Styles requirements class for the list of operations.

7.12. Requirements Class "OGC SLD 1.1"

Requirements Class

http://www.opengis.net/t15/opf-styles-1/1.0/req/sld-11

Target type

Web API

Dependency

Requirements Class "Core"

Dependency

OGC Styled Layer Descriptor, version 1.1

Requirement 39

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

B

Every GET operation of the server that returns a stylesheet document SHALL support the media type application/vnd.ogc.sld+xml;version=1.1.

Requirement 40

/req/sld-11/content

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.

B

Every GET operation of the server that returns a stylesheet document SHALL return a valid OGC SLD 1.1 document, if the media type application/vnd.ogc.sld+xml;version=1.1 is requested.

See the Mapbox Styles requirements class for the list of operations.

8. Extensions to OGC API Features / Common

The previous chapter specified the Styles API. In order to support styles, data APIs (supporting OGC API Features and/or Tiles) need additional capabilities to support styling in an Open Portrayal Framework, too. These are specified in this chapter as additional requirements/conformance classes to OGC API Features.

Note
 In the future, these classes could extend an OGC API Common requirements/conformance class that supports feature collections, but as no mature draft for this exists, we extend OGC API Features.

The extensions are the following:

  • The feature collection (path /collections/{collectionId}) is extended by the set of applicable styles (member styles, same value as in /styles in the Styles API) and a default style (member defaultStyle, the style id).

  • The PATCH operation on the same resource (path /collections/{collectionId}) is added. Only styles and defaultStyle may be updated.

  • The queryables resource (path /collections/{collectionId}/queryables) has been added to support clients like visual style editors to construct expressions for selection criteria in queries on features in the collection.

This resulting Features API has the resources listed in the Table below.

Table 3. Overview of resources, applicable HTTP methods
Resource Path HTTP method Changes

Landing page

/

GET

unchanged

Conformance declaration

/conformance

GET

unchanged, except for returning additional conformance classes

Feature collections

/collections

GET

unchanged

Feature collection

/collections/{collectionId}

GET

include links to styles in the response, see Fetch styles associated with a collection

PATCH

new, see Update styles associated with a collection

Queryables

/collections/{collectionId}/queryables

GET

new, see Fetch the queryable properties of the features in a collection

Features

/collections/{collectionId}/items

GET

unchanged

Feature

/collections/{collectionId}/items/{featureId}

GET

unchanged

The following is an example of the conformance declaration of a Styles API that implements all requirements classes except "html".

Example 7. Updated conformance declaration
{
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/html",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson",
    "http://www.opengis.net/t15/ogcapi-features-n/1.0/conf/style-info",
    "http://www.opengis.net/t15/ogcapi-features-n/1.0/conf/queryables"
  ]
}

8.1. Requirements Class "Style information"

Requirements Class

http://www.opengis.net/t15/ogcapi-features-n/1.0/req/style-info

Target type

Web API

Dependency

OGC API - Features - Part 1: Core, conformance class "Core"

Dependency

JSON Merge Patch

8.1.1. Fetch styles associated with a collection

The description of the collection includes additional information related to styles:

  • The styles array lists styles that can be used to render features in this collection.

  • The defaultStyle is the id of a recommended style to use for this collection.

Requirement 41

/req/style-info/success

A

A successful execution of the operation GET on /collections/{collectionId} SHALL include two members (with name styles and defaultStyle), if style information is available for the collection (for example, if is has been set using a PATCH operation).

B

The styles member SHALL be based on the following OpenAPI 3.0 schema:

type: array
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: 'https://api.swaggerhub.com/domains/cportele/ogcapi-features-1/1.0.0-draft.2#/components/schemas/link'

C

Each style SHALL have a link for each style encoding supported for the style (link relation: stylesheet) with the type attribute stating the media type of the style encoding.

D

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

The defaultStyle member SHALL be based on the following OpenAPI 3.0 schema:

type: string

F

The value of the defaultStyle member SHALL be an id included in the styles array.
Example 8. JSON encoding of style information

This example links to two styles ("night" and "topographic"), each available in two style encodings. The "topographic" style is the recommended default style.

{
  "id": "address",
  "title": "address",
  ...
  },
  "itemType": "feature",
  "styles": [
    {
      "id": "night",
      "title": "Topographic night style",
      "links": [
        {
          "href": "https://example.com/api/1.0/styles/night?f=mapbox",
          "type": "application/vnd.mapbox.style+json",
          "rel": "stylesheet"
        },
        {
          "href": "https://example.com/api/1.0/styles/night?f=sld10",
          "type": "application/vnd.ogc.sld+xml;version=1.0",
          "rel": "stylesheet"
        },
        {
          "href": "https://example.com/api/1.0/styles/night/metadata?f=json",
          "type": "application/json",
          "rel": "describedBy"
        }
      ]
    },
    {
      "id": "topographic",
      "title": "Regular topographic style",
      "links": [
        {
          "href": "https://example.com/api/1.0/styles/topographic?f=mapbox",
          "type": "application/vnd.mapbox.style+json",
          "rel": "stylesheet"
        },
        {
          "href": "https://example.com/api/1.0/styles/topographic?f=sld10",
          "type": "application/vnd.ogc.sld+xml;version=1.0",
          "rel": "stylesheet"
        },
        {
          "href": "https://example.com/api/1.0/styles/topographic/metadata?f=json",
          "type": "application/json",
          "rel": "describedBy"
        }
      ]
    }
  ],
  "defaultStyle": "topographic"
}

8.1.2. Update styles associated with a collection

In the previous section the additional style information for each feature collection is described. This operation can be used to update the style information.

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

Requirement 42

/req/style-info/patch-style-info-op

A

The server SHALL support the HTTP PATCH operation at path /collection/{collectionId}.

B

The server SHALL accept content based on the following OpenAPI 3.0 schema:

type: object
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: 'https://api.swaggerhub.com/domains/cportele/ogcapi-features-1/1.0.0-draft.2#/components/schemas/link'
  defaultStyle:
    type: string
    nullable: true

The only members that may be updated at this time are styles and defaultStyle. This specification does not specify how servers have to respond to additional content in the request content.

Requirement 43

/req/style-info/patch-style-info-success

A

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

B

The style information SHALL be updated by the content submitted in the request as specified by RFC 7396 (JSON Merge Patch).

I.e., a GET request to /collections/{collectionId} after the PATCH operation has to reflect the updated style information.

See the Styles API for more information about RFC 7396.

Some examples:

To add or update the default style, just send

{
  "defaultStyle": "night"
}

To remove the default style, send

{
  "defaultStyle": null
}

For arrays the complete array needs to be sent. I.e., to update the list of styles, send the complete new array value.

To remove all styles, send

{
  "styles": null
}

Requirement 44

/req/style-info/patch-style-info-error

A

If the request does not conform to the requirements (e.g., the patch document is invalid or includes additional members) a response with status code 400 SHALL be returned.

B

If the collection 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.

8.2. Requirements Class "Queryables"

Requirements Class

http://www.opengis.net/t15/ogcapi-features-n/1.0/req/queryables

Target type

Web API

Dependency

OGC API - Features - Part 1: Core, conformance class "Core"

8.2.1. Fetch the queryable properties of the features in a collection

This operation returns the list of queryable properties to filter features in a collection and supports clients to construct expressions for selection criteria in queries on features in the collection.

The response is an object with a member queryables, which contains an array with a description of the queryable properties of the feature collection. "Queryable" means that the property may be used in query expressions, for example, in a CQL query expression or as part of a selection criteria in a SLD/SE or Mapbox styling rule.

Often the list will be a subset of all available properties in the features and be restricted to those properties that are, for example, indexed in the backend datastore to support performant queries.

For each queryable property the following information is or may be provided:

  • id (required) - the property name for use in expressions

  • type (required) - the data type of the property, one of

    • string

    • uri

    • enum

    • number

    • integer

    • date

    • dateTime

    • boolean

  • description (optional) - a description of the property

  • required (optional) - indicator whether the property is always present in features

  • mediaTypes (optional) - in general, the representation of the queryables is meant to be independent of the feature encoding; however, this is not always the case; for example, length restrictions or namespace prefixes may result in different property identifiers for the same property; to support this, the definition of a queryable may be restricted to one or more feature encodings (media types).

  • pattern (optional, only for "string" and "uri") - a regular expression to validate the values of the property

  • values (required, only for "enum") - an array of valid values of the property

  • range (optional, only for "number", "integer", "date" and "dateTime") - the range of valid values expressed as an array with two items; open ranges can be expressed using null for the minimum or maximum value

Note that this is separate from providing a complete schema for the features in the collection. A schema provides a complete syntactic definition of a specific feature encoding, typically for validation purposes. Schema languages like XML Schema or JSON Schema are much richer and support more complex syntactic rules, but are also more complex to parse.

Requirement 45

/req/queryables/op

A

The server SHALL support the HTTP GET operation at the path /collection/{collectionId}/queryables for each collection.

Requirement 46

/req/queryables/success

A

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

B

The content of that response SHALL be based upon the OpenAPI 3.0 schema component "queryables", if the itemType of the collection is feature:

queryables
type: object
required:
  - queryables
properties:
  queryables:
    type: array
    nullable: true
    items:
      oneOf:
        - $ref: 'queryable-string'
        - $ref: 'queryable-enum'
        - $ref: 'queryable-number'
        - $ref: 'queryable-boolean'
        - $ref: 'queryable-date'
        - $ref: 'queryable-dateTime'
queryable
type: object
nullable: true
required:
  - id
  - type
properties:
  id:
    type: string
    nullable: true
    description: |-
      the property name for use in expressions
  title:
    type: string
    nullable: true
    description: |-
      the title of the property for presentation to a
      human user
  description:
    type: string
    nullable: true
    description: |-
      a description of the property
  required:
    type: boolean
    nullable: true
    default: false
    description: |-
      indicator whether the property is always present
      in features
  mediaTypes:
    type: array
    nullable: true
    description: |-
      In cases where a property is available only in a
      subset of the supported feature encodings, the
      list of the media types of the encodings can be
      specified.

      This capabilitiy is also needed for cases where
      the names of properties may differ between
      feature encodings. For example, identifiers in an
      XML/GML encoding may include a namespace,
      in GeoJSON or MVT this is not the case.

      There are other reasons, too. For example, the
      property identifier in a Shapefile may be different
      because of length restrictions.
    items:
      type: string
  type:
    type: string
    nullable: true
    description: |-
      the data type of the property
    enum:
      - string
      - uri
      - enum
      - number
      - integer
      - date
      - dateTime
      - boolean
discriminator:
  propertyName: type
  mapping:
    string: queryable-string
    enum: queryable-enum
    uri: queryable-string
    number: queryable-number
    integer: queryable-number
    date: queryable-date
    dateTime: queryable-dateTie
    boolean: queryable-boolean
queryable-string
allOf:
- $ref: 'queryable'
- type: object
  nullable: true
  properties:
    pattern:
      type: string
      nullable: true
      description: |-
        a regular expression to validate the values
        of the property
queryable-enum
allOf:
- $ref: 'queryable'
- type: object
  nullable: true
  required:
    - values
  properties:
    values:
      type: array
      nullable: true
      description: |-
        the list of values of the property
      items:
        type: string
queryable-number
allOf:
- $ref: 'queryable'
- type: object
  nullable: true
  properties:
    range:
      type: array
      nullable: true
      minItems: 2
      maxItems: 2
      items:
        type: number
        nullable: true
      description: |-
        a range of valid values; open range can be
        expressed using `null`
queryable-boolean
allOf:
- $ref: '#/components/schemas/queryable'
queryable-date
allOf:
- $ref: 'queryable'
- type: object
  nullable: true
  properties:
    range:
      type: array
      nullable: true
      minItems: 2
      maxItems: 2
      items:
        type: string
        format: date
        nullable: true
      description: |-
        a range of valid values; open range can be
        expressed using `null`
queryable-dateTime
queryable-dateTime:
  allOf:
  - $ref: 'queryable'
  - type: object
    nullable: true
    properties:
      range:
        type: array
        nullable: true
        minItems: 2
        maxItems: 2
        items:
          type: string
          format: date-time
          nullable: true
        description: |-
          a range of valid values; open range can be
          expressed using `null`

C

The id member of each queryable SHALL be unique.

Note that this specification does not specify any requirements on collections that are not feature collections.

Example 9. JSON encoding of queryables
{
  "queryables": [
    {
      "id": "name",
      "description": "the name of the vegetation area",
      "required": true,
      "type": "string",
      "example": "[A-Z0-9]{5}"
    },
    {
      "id": "type",
      "description": "the dominant characteristic of the vegetation area",
      "type": "enum",
      "values": [
        "grassland",
        "forest",
        "farmland"
      ]
    },
    {
      "id": "count",
      "description": "the number of cattle",
      "type": "integer",
      "range": [
        0,
        null
      ]
    },
    {
      "id": "fenced",
      "description": "indicator whether the area is walled or fenced",
      "type": "boolean"
    },
    {
      "id": "inspectionDate",
      "description": "the date of the last inspection",
      "type": "date",
      "range": [
        "2010-01-01",
        null
      ]
    },
    {
      "id": "lastUpdate",
      "description": "the date of the last update of the feature",
      "type": "dateTime",
      "range": [
        "2018-01-01T00:00:00Z",
        null
      ]
    }
  ]
}

9. Styles in GeoPackage

The previous chapters have described how styles according to the "Concept Model for Style Encoding & Metadata Model Engineering Report" could be implemented in OGC API family of standards.

The specification how the same concepts are implemented in GeoPackage is part of the draft OGC Discussion Paper "Proposed OGC GeoPackage Enhancements" (19-047).

Note
 TODO
To be discussed, which content should be included in this ER.

10. Implementations

Note
 TODO
Add relevant information about implementations of the specifications in this document (APIs and GeoPackage) and lessons learnt from the TIEs (September/October 2019).

11. Conclusion and recommendations

Note
 TODO
This chapter will added last, after the implementation experiences have been documented (October 2019).

Appendix A: Revision History

Table 4. Revision History
Date Editor Release Primary clauses modified Descriptions

April 11, 2019

C. Portele

0.1

all

initial version

July 28, 2019

C. Portele

0.2

all

transfer content from SwaggerHub to ER

August 6, 2019

C. Portele

0.3

all

transfer content from SwaggerHub to ER, part 2

August 28, 2019

C. Portele

0.4

all

added link to GeoPackage content, update summary

Appendix B: Bibliography