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 no unicode noleading number	URL path XML prefix XML Entity
Workspace URI	URI	XML Namespace URI
Layer name (vector)	alphanumeric no leading number	URL path XML local name XML Entity WMS layer name WFS feature type
Layer name (raster)	alpha numeric no unicode	URL path WMS layer name WCS coverage
Layer name (group)	alphanumeric no unicode	URL path WMS layer name (optional)
WMS path	Separated by `/` characters	WMS layer titles

GeoServer Naming Examples¶

Resource Name	WMS	WFS	WCS	Notes
Layer `roads`	layer	featureType	coverageType	Safe conventions
Layer `civic roads`	invalid	invalid	invalid	None of the protocols support whitespace
Layer `civic%20roads`	caution	invalid	caution	Percent encode may work
Layer `civic_roads`	layer	featureType	coverageType	Use of underscore recommended.
Layer `CivicRoads`	layer	featureType	coverageType	Layer names are case sensitive.
Layer `1234W`	layer	invalid	coverageType	Common for raster data products to start with a number.
Layer `🛶`	invalid	invalid	invalid	Avoid use of unicode
Layer group `dusseldorf`	layer			Layer groups only used by WMS
Layer group `düsseldorf`	invalid			Avoid use of unicode
Layer group `d%C3%BCsseldorf`	caution			Percent encoding may work
Layer group	unnamed layer			Unnamed layer group used as folder
Workspace prefix `sdi`	service url	service url namespace prefix	service url	Used a URL slug and XML namespace prefix
Workspace prefix `bathymetrie/bathymétrie`	invalid	invalid	invalid	Use of illegal characters.
Workspace prefix `bathymetrie%20bathymétrie`	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 and featuretype.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 and coverage.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 / characters
Each 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 operations
CoverageStore name used by data directory workspaces/[prefix]/[stores]/coveragestore.xml, and REST API operations
Do 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 and workspace.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&amp;version=1.0.0&amp;request=DescribeFeatureType&amp;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