MS RFC 138: Reference SLD files in Mapfiles¶
- Last Updated:
Targeting MapServer 8.4
This proposal outlines how Styled Layer Descriptor (SLD) files could be referenced directly in a Mapfile, allowing styles
to be applied using SLD files rather than MapServer’s
This would allow easier creation of Mapfiles from other applications, such as QGIS, which could export a Mapfile referencing SLD files, rather than attempting to translate QGIS styles directly to MapServer Mapfile syntax. It would make it easier to reuse styles between different applications.
It is proposed that the LAYER’s STYLEITEM keyword is used to reference the SLD files, as in the example below:
STYLEITEM "sld://mysldfile.xml" # uses SHAPEPATH and if not set then relative path to the Mapfile or absolute path
CLASS # define an empty CLASS here
The mechanisms to load and apply a file from disk referenced in a Mapfile could also be used in the future to apply future styling formats for example e.g. OGC styling could use file://style.json.
2.1 Proposed Solution¶
MapServer currently supports drawing layers in a Mapfile using SLD files in the following scenarios:
When applying SLD from a client application using the
SLD_BODYparameters to a MapServer layer - see the SLD docs
When using the WMS client -
wms_sld_bodycan be used to specify SLD to apply to the WMS
When using the WMS client -
wms_sld_urlcan be used to specify a URL pointing to an SLD file
msSLDApplySLDURL saves an SLD file a URL to a temporary file, and then applies this SLD to the layer.
Much of the code is already available and can be reused to implement applying SLD directly from a file.
Currently all uses of SLD rely on the NamedLayer Name property matching the LAYER NAME. For example
popplace in the SLD file:
Will only be applied if the LAYER NAME, or WMS name are also
"wms_title" "popplace" # this property is also checked for a match
If an SLD file is defined within a layer, it is proposed there is no need for the NamedLayer property to match the LAYER NAME. This would allow SLD files to be more easily reused, and would avoid confusion as to why the SLD isn’t being applied when specified in the Mapfile.
MapServer supports applying multiple NamedLayers to a LAYER, by creating a copy of the layer and applying subsequent NamedLayer styles to these copies. It is proposed only one NamedLayer will be applied to a LAYER when defined as a file in the STYLEITEM property. Cloning layers already containing a STYLEITEM will make the code overly complex, and a Mapfile author is free to create as many LAYERs in the Mapfile as they wish. If multiple NamedLayers are contained in the SLD file only the first will be used.
Mapfiles and sample SLD files will be created and added to the msautotest test suite. There are several conflicting features that will need to be tested. Tests will include:
Applying SLD to a LAYER
Checking an error is returned if the SLD file cannot be found
Checking if multiple NamedLayer files are contained in an SLD file only the first is used
Checking SLD is applied even if the LAYER NAME doesn’t match the NamedLayer Name
Checking Legends are correctly generated
Checking SLD can be supplied from a URL or querystring to override the SLD in the STYLEITEM
Reviewing SLD support in MapServer highlighted several use cases which do not currently have tests. Tests may be added as part of this implementation. These include:
wms_sld_bodyin a WMS client
wms_sld_urlin a WMS client
Several other SLD tests however are provided:
Passing SLD via
sld_bodyin a querystring is tested in many cases for example
Passing in an SLD URL is tested in
2.4 Security Concerns¶
MapServer already accepts SLD from remote URLs and client requests, so local SLD files shouldn’t cause any concerns.
MapScript currently includes an
applySLD function on both Map and Layer objects.
layerObj also includes a
styleitem property which can be used to set the STYLEITEM property.
3. Implementation Details¶
3.1 Affected files¶
More files may be affected once implementation is underway.
3.2 Ticket Reference¶
TODO - add GitHub pull request URLs.
4. Voting History¶