Working with SLD¶
This section describes how to create, view and troubleshoot SLD styling in GeoServer.
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.
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
A layer’s styles can be changed using the Layers page of the Web administration interface.
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
each of which may contain any number of
Within a Style Layer Descriptor document, the name of any
<NamedLayer> elements should match a layer (or layer group) in the catalog.
<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
/geoserver/styles) or the geoserver REST api.
Styling can be defined externally to the server in a number of ways:
An internet-accessible SLD document can be provided via the
SLD=urlparameter in a WMS GetMap GET request
An SLD document can be provided directly in a WMS GetMap GET request using the
SLD_BODY=styleparameter. The SLD XML must be URL-encoded.
A StyledLayerDescriptor element can be included in a WMS
GetMapPOST 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.
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.
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
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
layerslist, the applied style is either a named style specified in the
styleslist (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
<IsDefault>element having the value
1then 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.
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
layersparameter, and the corresponding styles in the
stylesparameter (if non-default styles are required).
Submit a WMS
GetMapPOST 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.
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.
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 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.