Working with SLD

This section describes how to create, view and troubleshoot SLD styling in GeoServer.

Creating

GeoServer comes with some basic styles defined in its catalog. Any number of new styles can be added to the catalog. Styles can also be specified externally to the server, either to define a complete map, or to extend the server style catalog using library mode.

Catalog Styles

Styles in the catalog can be viewed, edited and validated via the Styles page menu of the Web administration interface. They may also be created and accessed via the REST Styles API.

There are two types of Catalog Styles: Symbology Encoding styles (the default) and Style Layer Descriptor styles.

Symbology Encoding Styles

A Symbology Encoding style consists of a Symbology Encoding document used to specify the styling of a single layer. In GeoServer, this is more commonly referred to as a style.

GeoServer supports the use of a StyledLayerDescriptor document containing a single <NamedLayer> element, which contains a single <UserStyle> element to specify the styling.

  • When used in this fashion the layer name is ignored, since the style may be applied to many different layers.

  • When using an StyledLayerDescriptor generated by another application keep in mind only the first <NamedLayer> is used, any subsequent content is ignored.

Every layer (featuretype) registered with GeoServer must have at least one symbology encoding style associated with it, which is the default style for rendering the layer. Any number of additional styles can be associated with a layer. This allows layers to have appropriate styles advertised in the WMS GetCapabilities document. A layer’s styles can be changed using the Layers page of the Web administration interface.

Note

When adding a layer and a style for it to GeoServer at the same time, the style should be added first, so that the new layer can be associated with the style immediately.

Style Layer Descriptor Styles

A Style Layer Descriptor is a StyledLayerDescriptor document containing any number of <NamedLayer> and <UserLayer> elements, each of which may contain any number of <UserStyle> or <NamedStyle> elements.

Within a Style Layer Descriptor document, the name of any <NamedLayer> elements should match a layer (or layer group) in the catalog. Likewise, any <NamedStyle> elements should refer to a style in the catalog.

Style Layer Descriptor styles can define new layers of styled data, by using the InlineFeature element to provide feature data.

Within GeoServer, when Style Layer Descriptor styles are used they are typically in the form of style groups. Style groups can be added to layer groups as an alternative way of defining a collection of styled layers, using either the Web Administration interface or the REST API.

Style Layer Descriptor styles can still be assigned to layers and used like a layer style, in which case only the first <NamedLayer> will be used. Style Layer Descriptor styles can also be used as an External Style, via the geoserver styles endpoint (/geoserver/styles) or the geoserver REST api.

External Styles

Styling can be defined externally to the server in a number of ways:

  • An internet-accessible SLD document can be provided via the SLD=url parameter in a WMS GetMap GET request

  • An SLD document can be provided directly in a WMS GetMap GET request using the SLD_BODY=style parameter. The SLD XML must be URL-encoded.

  • A StyledLayerDescriptor element can be included in a WMS GetMap POST request XML document.

In all of these cases, if the WMS layers parameter is not supplied then the map content is defined completely by the layers and styles present in the external SLD. If the layers parameter is present, then styling operates in Library Mode.

The structure of an external style is the same as a Style Layer Descriptor style, as described above.

External styles can define new layers of styled data, by using the SLD InlineFeature element to provide feature data. This can be used to implement dynamic feature highlighting, for example.

External styling may be generated dynamically by client applications, This provides a powerful way for clients to control styling effects.

Library Mode

In library mode externally-defined styles are treated as a style library, which acts as an extension to the server style catalog. Library mode occurs when map layers and styles are specified using the layers and styles WMS parameters, and additional styling is supplied externally using one of the methods described in the previous section. The styles in the external style document take precedence over the catalog styles during rendering.

Style lookup in library mode operates as follows:

  • For each layer in the layers list, the applied style is either a named style specified in the styles list (if present), or the layer default style

  • For a named style, if the external style document has a <NamedLayer>...<UserStyle> with matching layer name and style name, then it is used. Otherwise, the style name is searched for in the catalog. If it is not found there, an error occurs.

  • For a default style, the external style document is searched to find a <NamedLayer> element with the layer name. If it contains a <UserStyle> with the <IsDefault> element having the value 1 then that style is used. Otherwise, the default server style for the layer (which must exist) is used.

Generally it is simpler and more performant to use styles from the server catalog. However, library mode can be useful if it is required to style a map containing many layers and where only a few of them need to have their styling defined externally.

Viewing

Once a style has been associated with a layer, the resulting rendering of the layer data can be viewed by using the Layer Preview. The most convenient output format to use is the built-in OpenLayers viewer. Styles can be modified while the view is open, and their effect is visible as soon as the map view is panned or zoomed. Alternate styles can be viewed by specifying them in the styles WMS request parameter.

To view the effect of compositing multiple styled layers, several approaches are available:

  • Create a layer group for the desired layers using the Layer Groups page, and preview it. Non-default styles can be specified for layers if required.

  • Submit a WMS GetMap GET request specifying multiple layers in the layers parameter, and the corresponding styles in the styles parameter (if non-default styles are required).

  • Submit a WMS GetMap POST request containing a StyledLayerDescriptor element specifying server layers, optional layers of inline data, and either named catalog styles or user-defined styling for each layer.

Troubleshooting

SLD is a type of programming language, not unlike creating a web page or building a script. As such, problems may arise that may require troubleshooting.

Syntax Errors

To minimize syntax errors when creating the SLD, it is recommended to use a text editor that is designed to work with XML (such as the Style Editor provided in the GeoServer UI). XML editors can make finding syntax errors easier by providing syntax highlighting and (sometimes) built-in error checking.

The GeoServer Style Editor allows validating a document against the SLD XML schema. This is not mandatory, but is recommended to do before saving styles.

Semantic Errors

Semantic errors cannot be caught by SLD validation, but show up when a style is applied during map rendering. Most of the time this will result in a map displaying no features (a blank map), but some errors will prevent the map from rendering at all.

The easiest way to fix semantic errors in an SLD is to try to isolate the error. If the SLD is long with many rules and filters, try temporarily removing some of them to see if the errors go away.

In some cases the server will produce a WMS Exception document which may help to identify the error. It is also worth checking the server log to see if any error messages have been recorded.

Previous: Introduction to SLD
Next: SLD Cookbook