Naming
GeoServer does not restrict the names used for workspaces, layers and layer groups - but the individual protocols do!
A common theme is that naming and publish a dataset is a long term commitment to keep the information available. Once a dataset is in use by the public (or even just your team) and change you make to the naming will “break” existing maps and processes).
When naming please consider the long term implications: next week, next month, next decade.
Not recommended (anything that is going to change):
author’s name: author can change with new versions.
subject: the dataset may be used in a range of subjects, so may not be the best choice long term. When using subject in your naming you are strongly associating the dataset with a single classification and use.
status: like old or draft
access: who has access to a dataset will change over time
file format (or file name extensions): how your data is stored may change over time (Shapefile, GeoPackaage, PostGIS)
software mechanisms or protocol used:
Since it takes some time to read all the different specifications, this page can provide an overview.
Reference:
Namespaces in XML 1.1 (W3C)
Cool URIs don’t change (W3C)
GeoServer Naming Reference
Resource |
Naming |
Restriction |
Workspace Prefix |
alphanumberic |
URL path |
Workspace URI |
URI |
XML Namespace URI |
Layer name (vector) |
alphanumeric |
URL path |
Layer name (raster) |
alpha numeric |
URL path |
Layer name (group) |
alphanumeric |
URL path |
WMS path |
Separated by |
WMS layer titles |
GeoServer Naming Examples
Resource Name |
WMS |
WFS |
WCS |
Notes |
Layer |
layer |
featureType |
coverageType |
Safe conventions |
Layer |
invalid |
invalid |
invalid |
None of the protocols support whitespace |
Layer |
caution |
invalid |
caution |
Percent encode may work |
Layer |
layer |
featureType |
coverageType |
Use of underscore recommended. |
Layer |
layer |
featureType |
coverageType |
Layer names are case sensitive. |
Layer |
layer |
invalid |
coverageType |
Common for raster data products to start with a number. |
Layer |
invalid |
invalid |
invalid |
Avoid use of unicode |
Layer group |
layer |
Layer groups only used by WMS |
||
Layer group |
invalid |
Avoid use of unicode |
||
Layer group |
caution |
Percent encoding may work |
||
Layer group |
unnamed layer |
Unnamed layer group used as folder |
||
Workspace prefix |
service url |
service url |
service url |
Used a URL slug and XML namespace prefix |
Workspace prefix |
invalid |
invalid |
invalid |
Use of illegal characters. |
Workspace prefix |
caution |
invalid |
caution |
Use of whitespace, even if percent encoded, invalid for some vector output formats. |
Use of percent encoding to represent whitespace or unicode characters, may be supported by the WMS protocol, but are error prone in practice resulting in integration challenges between systems.
Layer Naming Feature Resource
Workspace prefix:
Start with alpha, continue with alphanumeric
Do not start with a number, forbidden as part of xml schema type name
Do not use unicode, unicode cannot be used as part of a URL
Layer name used by data directory
workspaces/[prefix]/[store]/[layer]/layer.xml
andfeaturetype.xml
Layer title is used for presentation purposes and is not subject to these limitations.
Layer Naming Coverage Resources
Workspace prefix:
Alphanumeric
Do not use unicode, unicode cannot be used as part of a URL
Layer name used by data directory
workspaces/[prefix]/[store]/[layer]/layer.xml
andcoverage.xml
Layer title is used for presentation purposes and is not subject to these limitations.
As this is not used for XML content there is no restriction with respect to starting with a number.
Layer Group Naming
Layer group name:
Alphanumeric
Do not use unicode, unicode cannot be used as part of a URL
Optional: Used as a named layer in WMS GetCapabilities
Layer group name used by data directory
layergroups/[group].xml
Layer title is used for presentation purposes and is not subject to these limitations.
As this is not used for XML content there is no restriction with respect to starting with a number.
WMS Path Naming
WMS path naming:
Form a path names seperated by
/
charactersEach path break forms an unnamed layer (folder) in WMS GetCapabilities
One of the WMS options when publishing a layer is to supply a WMS Path, which forms a folder in the GetCapabilities document structure. This appears in the same fashion as a “folder tree” layer group.
As the WMS Path elements form a series of title you may experiment with use of unicode.
Store naming
Store naming:
Internal name only
DataStore name used by data directory
workspaces/[prefix]/[stores]/datastore.xml
, and REST API operationsCoverageStore name used by data directory
workspaces/[prefix]/[stores]/coveragestore.xml
, and REST API operationsDo not use
styles
(as this will conflict with workspace styles folder)
By design store name is not used as any part of URL or protocol communication
Workspace Naming
Workspace prefix:
Start with alpha, continue with alphanumeric
Do not start with a number, forbidden as part of xml schema type name
Do not use unicode, unicode cannot be used as part of a URL
Workspace prefix used by data directory
workspaces/[prefix]/namespace.xml
andworkspace.xml
.Workspace prefix used by REST API
Workspace uri:
URI is used for consistency between XML document and XMLSchema
Naming in URLs and Documents
Workspace prefix and layer name are used as part of a URL path for OGC Open Web Services family of standards:
http://localhost:8080/geoserver/[prefix]/ows?service=wms&version=1.3.0&request=GetCapabilities
http://localhost:8080/geoserver/[prefix]/[layer]/ows?service=wms&version=1.3.0&request=GetCapabilities
http://localhost:8080/geoserver/[prefix]/wms?service=WMS&version=1.1.0&request=GetMap&layers=[prefix]%3A[layer]
https://localhost:8080/geoserver/[prefix]/wfs?service=WFS&version=1.0.0&request=DescribeFeatureType&typeName=[prefix]%3A[[layer]
Workspace prefix and layer name are used as part of a URL path for OGC API family of standards:
https://localhost:8080/geoserver/ogc/features/collections/[prefix]:[layer]
https://localhost:8080/geoserver/ogc/features/collections/[prefix]:[layer]/items?f=application%2Fjson
The combination of workspace prefix and layer name is used within XML documents (example FeatureCollection). Workspace prefix is used as an XML namespace prefix, provided for the workspace URI namespace. In the example of a FeatureCollection document schemaLocation for the workspace URI is provided by DescribeFeatureType. This provides a dynamically generated XSD schema document.
<?xml version="1.0" encoding="UTF-8"?>
<wfs:FeatureCollection
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:wfs="http://www.opengis.net/wfs/2.0"
xmlns:[prefix]="[uri]"
xmlns:gml="http://www.opengis.net/gml/3.2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opengis.net/wfs/2.0 http://localhost:8080/geoserver/schemas/wfs/2.0/wfs.xsd
http://www.opengis.net/gml/3.2 http://localhost:8080/geoserver/schemas/gml/3.2.1/gml.xsd
[uri] http://localhost:8080/geoserver/[prefix]/wfs?service=WFS&version=1.0.0&request=DescribeFeatureType&typeName=[prefix]%3A[layer]">
<gml:featureMember>
<[prefix]:[layer] fid="[layer].1">
<[prefix]:geom>...</[prefix]:[geom]>
<[prefix]:featurecla>...</[prefix]:featurecla>
...
</[prefix]:[layer]>
</gml:featureMember>
</wfs:FeatureCollection>
Workspace prefix and workspace URI are used together with layer name within XSD documents (example DescribeFeatureType). Workspace prefix forms part of an XSD element definition within a schema definition. Layer name used for XSD element and type definition:
<xsd:schema
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:gml="http://www.opengis.net/gml"
xmlns:sdi="[uri]"
elementFormDefault="qualified"
targetNamespace="[uri]">
<xsd:import namespace="http://www.opengis.net/gml"
schemaLocation="https://localhost:8080/geoserver/schemas/gml/2.1.2/feature.xsd"/>
<xsd:complexType name="[layer]Type">
<xsd:complexContent>
<xsd:extension base="gml:AbstractFeatureType">
<xsd:sequence>
<xsd:element maxOccurs="1" minOccurs="0" name="geom" nillable="true" type="gml:MultiPolygonPropertyType"/>
<xsd:element maxOccurs="1" minOccurs="0" name="featurecla" nillable="true" type="xsd:string"/>
...
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
<xsd:element name="[layer]" substitutionGroup="gml:_Feature" type="[prefix]:[layer]Type"/>
</xsd:schema>
Workspace prefix and