Naming Convention for Data Services

As a group, state agencies that author services intended to be published on the Commons have developed a naming convention for such services. The purpose of this naming convention is:

• To create consistent naming patterns across state agencies
• To reduce the chances that services across state agencies have conflicting names
• To help the end user to understand “at-a-glance” what the service content is (without overload)
• To ensure that if services are eventually moved to a common infrastructure, consistent naming patterns make it easier to expose them alongside each other.

Target Audience

This documentation is targeted at data administrators and service providers (GIS data publishers and server administrators) charged with implementing the convention. It should be noted that service names are essentially “shorthand names” which are accompanied by descriptive names (plain English names) as part of the service metadata. It is these descriptive names and associated keywords that typical GIS end-users will encounter on the Geospatial Commons, for example. However, the naming convention only applies to the shorthand name.

Scope

The scope of this convention includes the following:

• Conventions related to the name of the service itself, as exposed on a REST endpoint.
• Descriptors having to do with data content, including thematic keywords
• Structural conventions

The following considerations are out of scope for this convention:

• Naming of “private", “internal", or application-specific services which are not intended to be consumed by other agencies or the general public.
• Service agreements or implicit guarantees regarding service availability and support.
• Describing the internal structure of the service (structure of content). For example, single-layer versus multi-layer service.
• Including capabilities and functions of the service in the name
• Components of the URL which are out of control of the publisher (i.e. instance name, domain name, etc.)
• Descriptive names, and other service metadata elements

Proposed Structural Conventions

Structural conventions are simple rules which enhance browse-ability and ensure multi-platform and system compatibility. They include the following:

• 32 character limit on service name length.
  
  • Justification: this length allows for reasonable description to be displayed on one line. 
• No spaces. Use underscores instead.
  
  • Justification: spaces and hyphens in service names cause issues with some systems.
• All lower case letters
  
  • Justification: all lower-case formatting is easier to read when browsing through a long list of service names. Words are separated by underscores as necessary, so camel case is not appropriate.
• No periods or other punctuation marks aside from underscore.
  
  • Justification: special characters can be misinterpreted by some systems.

Proposed Components of the Name

• Do not place services inside a folder, using the folder name in a descriptive manner
  
  • Justification: for browse-ability, data administrators and developers should be able to see all the services available at a REST endpoint in one list, without having to dig into a folder structure. Under this convention, folders can be reserved for application-specific services or other purposes.

• Prefix the service name with a primary ISO topic category keyword abbreviation.
  
  • Justification: this is the current standard for naming resources on the GDRS. It effectively groups resources into primary themes, making it easier for the reader to browse and find the data they are looking for quickly. 
  • It is not perfect (you have to pick a primary topic category when more than one may apply) but it groups services with similar content together.
  • When delivering a Geospatial Commons resource in both download and service formats, the names (and specifically the ISO topic abbreviation) should match. 
  • The help includes the list of ISO topic category keyword abbreviations.
• The remaining available characters are for use in describing the content of the service
  
  • Justification: This is where the data administrator or publisher may get creative and describe the content of the service in a brief manner.