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:

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:

  • https://instance.geocat.live/geoserver/[prefix]/ows?service=wms&version=1.3.0&request=GetCapabilities

  • https://instance.geocat.live/geoserver/[prefix]/[layer]/ows?service=wms&version=1.3.0&request=GetCapabilities

  • https://instance.geocat.live/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 https://instance.geocat.live/geoserver/schemas/wfs/2.0/wfs.xsd
                      http://www.opengis.net/gml/3.2 https://instance.geocat.live/geoserver/schemas/gml/3.2.1/gml.xsd
                      [uri] https://instance.geocat.live/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