formulation of an OGC API style in SLD

[pomakis]

As early as Testbed 14, it was clear that expressing an OGC API style as an SLD is pretty awkward. That's because they're fundamentally different things. An OGC API style exists independently of feature sets and layers, and internally describes how to render various feature sets. It doesn't define layers, since there's no such thing as an addressable layer per se in the OGC API.

In contrast, an SLD (Styled-Layer Descriptor) does exactly that. It defines one or more layers, where each layer is defined by one or more styles, where each style indicates which feature set(s) to render and how to render them. That is, a style isn't a top-level object in the SLD world; it exists only in the context of the layer that it's defined in. Two or more layers may have a style of the same name, but there's no conceptual relationship between those two styles.

We managed to reconcile these differences in Testbed 14 and Testbed 15, but in an awkward way. We formulated an OGC API style in SLD as a SymLayerSet with one or more NamedLayers (representing each of the collections that can be rendered with this style), each of which defines exactly one UserStyle (whose name is the ID of the style being defined), each of which has exactly one FeatureTypeStyle (whose FeatureTypeName is implicitly or explicitly the same as that of the NamedLayer). See the attached Night_sld11.txt as an example of this.

But this is way too ugly. It's a clumsy hack at best.

I propose that the SLD formulation of an OGC API style have a UserStyle as its top-level element. This UserStyle can have one or more FeatureTypeStyles, each of which explicitly specifies a FeatureTypeName indicating the collection that that FeatureTypeStyle is for. This is a more direct and concise representation of an OGC API style. See the attached Night_sld11style.txt as an example of this.

CubeWerx has a demo implementation of this up at "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa". In this demo implementation, requesting a style with "f=sld10" or "f=sld11" requests the old convoluted representation, whereas requesting a style with "f=sld10style" or "f=sld11style" requests the new concise representation. However, perhaps the sld10 and sld11 formats should simply be defined to be this new concise representation.

Whatever decision is made on this, the "OGC API - Styles" specification will need to be very clear on exactly how to formulate an OGC API style in SLD.

Night_sld11.txt Night_sld11style.txt

[cportele]

@pomakis - If I understand you correctly, you propose to add more requirements to the SLD requirements classes to constraint the type of SLD document that is "acceptable" as an SLD style? Do you have a proposal how the additional requirement should be phrased?

[pomakis]

I'll attempt to draft some wording to propose.

BTW, I'm curious if anybody else has experimented with a client or server implementation of "OGC API - Styles" using SLD. I'd like to hear other experiences so that I can confirm (or dispel) my belief that this really is something that needs to be addressed.

[jeffharrison]

@pomakis Yes, there were multiple implementations of OGC API - Styles with SLD encodings over the last 18 months... in OGC Pilots, Testbed and external efforts.

I'm not sure if they addressed the issue you've raised... The draft OGC API - Styles manages and fetches styles, and is capable of supporting styles with multiple style encodings. For example the encoding could be Mapbox Style, 'old school' SLD or 'new school' SLD and shouldn't matter as far as the API is concerned (?)... unless I'm missing something, which is quite possible.

Best Regards, Jeff

[pomakis]

If any of the implementations accepted or returned an OGC API style definition encoded as SLD, and that style contained rendering rules for more than one feature collection, then they would have run into this issue. A <StyledLayerDescriptor> element (which is the typical top-level element of an SLD document) defines the wrong type of thing. There's no straightforward one-to-one mapping between a StyledLayerDescriptor and an OGC API style.

[pomakis]

Okay, here are my proposed adjustments to the "OGC API - Styles" specification. In essence, it simply indicates that the SLD documents that are accepted and returned are SLD UserStyle documents (i.e, with a root element of <UserStyle>) rather than full StyledLayerDescriptor documents. It might be nice to eventually add an example of such a document, but my proposed adjustments below don't include this.

--

In section 2 (Conformance), change:

• "sld-10" supports OGC SLD 1.0 as a style encoding.
• "sld-11" supports OGC SLD 1.1 as a style encoding.

to:

• "sld-10" supports OGC SLD 1.0 UserStyle as a style encoding.
• "sld-11" supports OGC SLD 1.1 UserStyle as a style encoding.

--

In section 4.4 (Terms and Definitions, style encoding), change:

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

to:

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

--

In section 7 (Styles API), change:

For example, a Styles API may publish a "night" style in the style encodings OGC SLD 1.0, OGC SLD 1.1 and Mapbox Style.

to:

For example, a Styles API may publish a "night" style in the style encodings OGC SLD 1.0 UserStyle, OGC SLD 1.1 UserStyle and Mapbox Style.

--

In section 7.1.5 (Styles API, Requirements Class "Core", Fetch style metadata), Example 4, change:

{ "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" } }

to:

{ "title": "OGC SLD UserStyle", "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" } }

--

In section 7.7 (Styles API, Requirements Class "OGC SLD 1.0"), Requirement 36, change:

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.

to:

Every POST or PUT operation of the server that accepts a stylesheet document as content SHALL accept a valid OGC SLD 1.0 UserStyle document (i.e, with a root element of <UserStyle>) without errors.

--

In section 7.7 (Styles API, Requirements Class "OGC SLD 1.0"), add the following requirement (perhaps before Requirement 36):

Every GET operation of the server that returns a stylesheet document with a media type of application/vnd.ogc.sld+xml;version=1.0 (f=sld10), shall return a valid OGC SLD 1.0 UserStyle document (i.e, with a root element of <UserStyle>).

--

At the end of section 7.7 (Styles API, Requirements Class "OGC SLD 1.0"), insert the following operation to the middle of the list:

GET /styles/{styleId}

--

In section 7.8 (Styles API, Requirements Class "OGC SLD 1.1"), Requirement 38, change:

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.

to:

Every POST or PUT operation of the server that accepts a stylesheet document as content SHALL accept a valid OGC SLD 1.1 UserStyle document (i.e, with a root element of <UserStyle>) without errors.

--

In section 7.8 (Styles API, Requirements Class "OGC SLD 1.1"), add the following requirement (perhaps before Requirement 38):

Every GET operation of the server that returns a stylesheet document with a media type of application/vnd.ogc.sld+xml;version=1.0 (f=sld10), shall return a valid OGC SLD 1.1 UserStyle document (i.e, with a root element of <UserStyle>).

--

At the end of section 7.8 (Styles API, Requirements Class "OGC SLD 1.1"), insert the following operation to the middle of the list:

GET /styles/{styleId}

--

In section A.8 (Annex A, Conformance Class "SLD 1.0"), change:

If the API supports the conformance classes "Manage styles" or "Style validation", execute all test cases of the supported conformance classes using stylesheets that are OGC SLD 1.0 documents using the media type application/vnd.ogc.sld+xml;version=1.0.

to:

If the API supports the conformance classes "Manage styles" or "Style validation", execute all test cases of the supported conformance classes using stylesheets that are OGC SLD 1.0 UserStyle documents using the media type application/vnd.ogc.sld+xml;version=1.0.

--

In section A.9 (Annex A, Conformance Class "SLD 1.1"), change:

If the API supports the conformance classes "Manage styles" or "Style validation", execute all test cases of the supported conformance classes using stylesheets that are OGC SLD 1.1 documents using the media type application/vnd.ogc.sld+xml;version=1.0.

to:

If the API supports the conformance classes "Manage styles" or "Style validation", execute all test cases of the supported conformance classes using stylesheets that are OGC SLD 1.1 UserStyle documents using the media type application/vnd.ogc.sld+xml;version=1.1.

(Note also the media-type fix.)

[cportele]

Thanks @pomakis !

It would be good to get feedback on the proposal from client / style editor implementers that have worked with SLDs in the Styles API context. While we have stored SLDs in our API instances, we have never used them for anything, we have only used the Mapbox styles to render data.

A related aspect is then the media type definition that the SLD group would have to prepare. Is a document with a UserStyle root element the same or a different media type and the SLD media type is only used for StyledLayerDescription documents?

[ghobona]

@aaime Any comment on https://github.com/opengeospatial/ogcapi-styles/issues/5#issuecomment-656229796 ?

[pomakis]

@cportele wrote:

A related aspect is then the media type definition that the SLD group would have to prepare. Is a document with a UserStyle root element the same or a different media type and the SLD media type is only used for StyledLayerDescription documents?

That's a good question. AFAIK, a UserStyle element has never been used standalone like this before. In CubeWerx's current test implementation at "https://test.cubewerx.com/cubewerx/cubeserv/demo/ogcapi/Daraa" we use the ad hoc media type "application/vnd.ogc.sld+xml; version=1.1; styleOnly=true" for this.

[jeffharrison]

Styles SWG reviewed and agreed there is a need for User Styles representation as presented in this Issue. This Issue needs to be coordinated with the SLD/SE Group (cross SWG coordination needed here).

Note - May need a separate MIME type.

Jerome and Keith will coordinate and develop proposal to be reviewed also with SLD/SE.

[jeffharrison]

SWG discussed this Issue... Chair will contact OGC implementers via email to assess.

[jerstlouis]

At the May 2021 sprint we clarified that a sld:StyledLayerDescriptor is required as the top level element in an SLD/SE document. We may need to clarify how multiple UserStyle within a NamedLayer should be handled.

[jeffharrison]

When Clemens P writes a Pull Request he will clarify that the root element of any SLD used by OGC API - Styles will be the sld:StyledLayerDescriptor.

Once this is accomplished, we will clarify what can be in that element.

See related issue Issue #24

[pomakis]

Or, more to the point I think, how the definition of an OGC API style (which isn't owned by a collection but may reference multiple collections within its definition) should be represented in SLD.

Multiple UserStyles within a NamedLayer is old hat in SLD. But to represent an OGC API style, a StyledLayerDescriptor would presumably need to include multiple NamedLayers (representing collections), each of which has exactly one UserStyle, which has the ID of the OGC API style being represented. This is an awkward-enough arrangement that it definitely needs to be clarified in the "OGC API - Styles" standard.

[jerstlouis]

@pomakis Agreed. See #24

[jeffharrison]

SWG reviewed this on 13 July 2021. As discussed previously, PR28 will handle this Issue. SWG recommend closing as this Issue as it is resolved by PR28.