OGC API - Styles SWG
Harrison, Jeffrey (US Army Geospatial Center)
Vretanos, Panagiotis (Peter) A. (CubeWerx)
Harrison, Jeff (US Army Geospatial Center)
Sorenson, Matt (Strategic Alliance Consulting Inc.)
1. Purpose of the OGC API – Styles Standards Working Group
The purpose of this Standards Working Group is to:
- Develop and maintain an OGC API - Styles core standard.
- Develop and maintain extensions of the OGC API - Styles standard as identified in section 4 (Scope).
The formal proposed name of the new standard is "OGC API - Styles - Part 1: Core". The short name “Styles API” may also be used to refer to this effort in the charter and work products
2. Business Value Proposition
In order to be able to portray geospatial resources (e.g., feature collections, coverages, etc.), end-users must be able to apply styles. As noted in the OGC online glossary of terms, a style provides the mapping from feature types and feature properties and constraints to parameterized symbols used in map drawing and other portrayals. The Testbed 14 Symbology Conceptual Model Engineering Report (ER) and Vector Tile Pilot Summary ER added that a style organizes the rules of symbolizing instructions to be applied by a rendering engine on one or more geographic features and/or coverages.
Currently, styles are often developed in close relationship to the geographic resources to be portrayed and the GIS platform or computing environment in which the style will be applied. As such, sharing of styles has been very limited. As the ability to map symbology and portrayal rules to multiple datasets, data schema and encodings has become more widespread, the desire to share and reuse styles for different schema and encodings has increased. At the same time, OpenAPI frameworks have made defining a common API interface to support style sharing more attainable. The ability to share common styles for use by many users improves visualization of a common operational picture and improved interoperability.
The proposed API provides the methods and apparatus to support:
- Discovery of style resources and metadata;
- Execute basic commands to GET, PUT, PATCH, POST, and DELETE style resources and their metadata; and
- Interface with other web resources using OGC API capabilities and OGC web services.
For providers of styles, the API provides a uniform means to publish and offer those styles as resources for use by other systems.
For developers building infrastructures to host, harvest and/or manage collections of geospatial resources, the Styles API standard will define the core requirements needed to describe and leverage existing styles and publish new or edited styles.
Finally, users of geospatial resources are often in a position of having to construct specialized styles or develop a unique style. The Styles API will allow for discovery, access, and application of multiple style resources offered through the API.
3. Scope of Work
OpenAPI frameworks have helped make describing and sharing API definitions more suitable for interoperability standardization. The concept of a Styles API was demonstrated in the OGC Vector Tile Pilot and in OGC Testbed 15.
The OGC API - Styles SWG will build on those preliminary efforts to more fully develop and document a Styles API candidate standard that will provide a modernized, common, and consistent interface to services that aligns with the current architecture of the Web and the Spatial Data on the Web Best Practices (https://www.w3.org/TR/sdw-bp/).
The OGC API - Styles SWG will develop a Styles API candidate standard which is informed by emerging OGC API best practices and prior API standards examples (e.g., OGC API - Features) to define core API functions of GET, PUT, PATCH, POST, DELETE applied to styles as resources. The Styles API will also document metadata requirements for styles to enhance discovery and exchange of styles.
The OGC API – Styles standard will specify an implementation specification aligned with prior work in OGC for symbology and Web APIs. The proposed standard will define API building blocks for styles in Web API. OGC API - Styles will be consistent with HTTP and HTTPS.
The first version of the Styles API will support JSON and HTML as encodings of the resources in the API. No encoding will be mandatory and other encodings may be used as well. The HTTP focus is designed to support the use of multiple formats and defines rules about how servers can return the encoding that the client can best handle (“content negotiation”). The SWG will consider requirements and conformance classes for supporting style resources in multiple style encodings (e.g., SLD, CSS, Mapbox Styles) in the design of the Styles API.
- Basic information model:
The Styles API standard will conform to OpenAPI models and OGC API best practices. Additionally, the API will align with the emerging portrayal abstract specification and conceptual model efforts in the Styled Layer Descriptor and Symbology Encoding (SLD/SE) SWG and Portrayal DWG. The abstract specification and conceptual models will consider recommendations from OGC Testbed 14 and 15 portrayal engineering reports.
The use of unique Styles API resources or components will be minimized and, where available, existing industry-standards or patterns that are commonly used by developers will be used instead. The most important example for this is the use of an OpenAPI definition instead of OGC-specific "Capabilities" documents and the use of OGC API - Common components to the maximum extent practicable.
OGC API - Styles - Part 1: Core will define a basic set of capabilities organized in multiple conformance classes building on each other. The minimal conformance class will specify a simple interface to access metadata from style resources that is sufficient for interfaces to exchange and perform basic web functions with the style resources. Additional conformance classes will define additional capabilities based on the requirements and requirements classes defined in the core to meet the needs of use cases that require such capabilities.
Identified extensions to be worked within the initial scope of the SWG charter include extensions for managing and validating styles (to include styles for features, coverages, and 3D data), accessing and managing style resources like symbols, or extensions for data resources (links to applicable styles, identification of “queryables”). Other extensions may be proposed and addressed in revisions to this charter. The primary goal of the Styles API SWG is to develop the core of "OGC API - Styles" as quickly as possible and work on extensions after that, driven by community interest. An important aspect is to ensure that implementing the standard will lead to efficient implementations, happy developers of both server and client components, and satisfied users of such components.
Before finalizing parts of the future versions of the "OGC API - Styles", completion of goals should be verified:
- Working implementations of all capabilities must be available and tested; and
- Implementation feedback must be taken into account.
A consequence of this verification is that the period between the availability of what is considered a mature draft and the finalization of the candidate standard may be longer than in the past, depending on the availability of evidence about the suitability of the candidate standard based on implementations. Developers should be encouraged as early as possible to implement the draft API specification and provide feedback. An aspect of this is public access to drafts from the beginning. To this end, the SWG intends to use GitHub in the development of this standard as this is the environment many developers are familiar with and use on a daily basis.
3.1 Statement of relationship of planned work to the current OGC standards baseline
This proposed standard is intended to be a major component of the OGC API framework. The proposed standard will take advantage of Web API patterns identified in OGC API standards (e.g., OGC API – Features) and ongoing API efforts (e.g. OGC API Common development in OWS Common SWG) to better align with current and emerging IT practices. The Styles API complements the OGC Symbology Encoding Conceptual Model: Core Part (SymCore) and provides a means for sharing styles developed under OGC and other style encodings.
3.2 What is Out of Scope?
Standards are important for interoperability. At the same time, it is important that standards only state requirements that are important for a significantly large group of users. Proposals for new parts of OGC API - Styles or change requests to existing parts must identify the user group that will benefit from the proposal and for each proposed conformance class; otherwise the proposal will be considered out-of-scope.
OGC API - Styles is envisioned to be a modular, multi-part standard. Extensions and profiles not identified as in scope in the previous section will require a revision to the SWG charter prior to commencement of work. If a community has a need to develop a profile, the profile should be specified and governed by that community.
Styles are the basic resource described in OGC API - Styles. The Styles API describes the interface and exchange of styles. The construction of symbology components of styles is addressed in OGC Symbol Encoding Conceptual Model: Core Part and multiple OGC and other style encoding standards. The development of an overarching portrayal abstract specification will be done in the Portrayal DWG.
3.3 Specific Contribution of Existing Work as a Starting Point
The starting point for the work will be the OGC 19-010: OGC Testbed 15: Styles API (draft specification) Engineering Report. SWG work will commence on approval of this charter and approval of the Testbed 15 ER. The work shall also be informed by the following specifications and by recommendations found in:
- OGC/W3C Spatial Data Working Group on the Web Best Practices (https://www.w3.org/TR/sdw- bp/);
- OGC Geospatial API White Paper [OGC 16-019r4];
- OGC API - Features - Part 1: Core standard, [OGC 17-069r3]; and
- OGC Symbol Encoding Conceptual Model: Core Part candidate standard [OGC 18-067r2].
Each of these documents recommends an emphasis on resource-oriented APIs in future OGC standards development including use of tools such as OpenAPI.