Publish a codelist as a file in a web accessible folder

This recipe presents a minimal approach for publishing a (extended) code list. The code list is stored as a text file on a web accessible folder. A number of potential formats to use for the text file are discussed in this article. Concepts within the codelist are referenced as http://example.com/codes.xml#concept. The concept identifier is concatenated to the url with a ‘#’ character. ‘#’ represents a local link within the document, a convention adopted from the html standard.

Codelist format options

The richest and most common format for code list storage is SKOS (RDF). It is the format used by for example Glosis to publish its codelists. Tools like GeoNetwork and Hale Studio are able to ingest codelists based on the SKOS ontology.

An alternative format is based on the iso19135:2005 standard. TC 211 develops the iso19135 standard to offer a format for code lists in the spatial data community. The standard is for example used in the gmx-codelists as used in iso19139:2007.

The approach described on this page is for example used in Lithuania. The gml described in this catalogue record links to codelists published in an XML format inspired by the INSPIRE registry. See https://inspire-geoportal.lt/resources/codelist/SO/OtherHorizonNotationTypeValue.xml. This format is probably selected because it can directly be ingested by Hale Studio.

Host your codelist

The location of the codelist can be a webserver folder (apache/nginx), a git repository, even a shared sharepoint folder. But it is important that the url of the file is persistent for a considerable period. Because the datasets which link to codelist items depend on its availability.

Persistency can be improved by adding an intermediary layer between the location of the file and the url on which it is made available, mechanisms such as provided by DOI and W3ID. Glosis codelists are for example stored at https://github.com/rapw3k/glosis but are referenced as http://w3id.org/glosis/model/codelists and then forwarded.

Extending INSPIRE codelists

A dedicated recipe describes the actual code list extension mechanism.

Content negotiation (optional)

When a human arrives at a codelist file, if it is not in html format, the syntax with https://example.org/#concept opens the file at the top, and does not point to the relavant section, because the web browser does not understand the format. A mechanism of content negotiation can identify web browsers and present them an alternative format (html). Content negotiation can be set up in an intermediary webserver layer, the transformation from SKOS/iso19135 to html should be managed by an extra utility (such as SKOSMOS).

Multilingual concept labels (optional)

Both SKOS, ISO19135 and the Re3gistry format support the option to provide labels for concepts in multiple languages.