ref.gs1.org

The Global Language of Business

URI policy for ref.gs1.org

Latest version
https://ref.gs1.org/gs1/uri-policy/
This version
https://ref.gs1.org/gs1/uri-policy/1.0.0/
Publication date
28 June 2022

Purpose of the domain

The domain ref.gs1.org has been established as a place where GS1 standards and related resources, such as machine-readable files and position papers, can be published and managed in a process that is distinct from other subdomains operated by GS1. Examples of machine-readable files include vocabularies, XML and JSON schemas, JSON-LD context files, and SHACL files. Of particular note is that URIs minted (created) on ref.gs1.org are persistent. That is, users may have a reasonable expectation that resources will continue to be available at the same URI indefinitely. No one can predict the future and so it is all but meaningless to try and fix today what future generations will do. However, the intention is that the domain be managed such that resources will be available for many decades to come, certainly beyond the working life of any individual involved in their creation.

Not the purpose of the domain

ref.gs1.org is not a replacement for, or competitor to, www.gs1.org. It’s a repository of artefacts that can be linked to reliably. Users will not generally be expected to navigate their way through the domain in the way they would in a regular website. However, there will be a full sitemap to aid external search engines to index all resources and a site-wide search function. The regular pattern for reposing standards and vocabularies in particular will aid discovery through predictability.

Change management

Resources on ref.gs1.org will typically be associated with and defined by formal processes within GS1. Standards and their related resources will therefore be managed according to the Global Standards Management Process (GSMP). Other resources that support GS1 processes and services and that require persistent hosting may also be published on ref.gs1.org.

Backup

It is essential that the ref.gs1.org content be backed up regularly. This is the company archive and must be restorable in the case of failure. This may be accomplished by backing up the server itself or, more likely, maintaining the publication image in a service that itself does backups.

URI persistence and content immutability

The concepts of URI persistence and content immutability are distinct from each other.

To give an example of the difference, consider the document at ref.gs1.org/standards/epcis/2.0.0/. This document will not change over time. It is very likely that minor errors will be detected leading to the publication of version 2.0.1 which will be published at ref.gs1.org/standards/epcis/2.0.1/. Again, this version will not change. Both these documents are immutable and identified by a persistent URI.

The version numbers of those documents are included in each of the URIs. From the day of publication of version 2.0.0, the shorter, unversioned URI https://ref.gs1.org/standards/epcis also returns version 2.0.0 as it is the latest version. However, when version 2.0.1 is published that same, persistent, unversioned URI will now return version 2.0.1.

This means that it is possible to link, reliably, to an immutable version of a document or to simpy its latest version.

Persistent URI, consistent but mutable content

There is a third class of resource: one that is reliably and persistently available at a given URL, that changes over time, but only in the sense that new content is added without old content disappearing. This is the framework for vocabularies such as those for EPCIS and CBV. New terms can be added, definitions may be tightened and refined, but shall not be deleted. They may, however, be deprecated, that is, marked as retained purely for archival reasons and not for future use.

Immutability and long-term usability

Resources intended to be immutable should comprise only static elements. For HTML documents, included assets, such as images and stylesheets, should be available in the same directory as the HTML document. Immutable documents shall not be dynamically generated from a content management system (CMSs are ephemeral). The legibility and usability of HTML documents may, and typically will, be improved by scripting. This is acceptable, but the script should itself either be part of the HTML document or hosted in the same directory, and the HTML should be readable without style or scripting.

In some cases, the primary format of the document is machine-readable or machine-interpretable data, such as a JSON-LD document. In such cases, an HTML view of that machine-interpretable data is generated dynamically. This is typically the case for ontology browsers.

File formats should be based on open standards with readily available open-source tooling. Examples include XML, JSON, HTML and PDF/A. Microsoft Office files such as DOCX (Word), XLSX (Excel), and PPTX (PowerPoint) do not meet this criterion unless they conform to Open Office XML formats defined by ISO/IEC 29500.

Less formal, editable documents and archiving

Not all documents on ref.gs1.org need be immutable. Many documents can be created and edited as needed over time. The URIs that identify those documents should, however, be persistent and, when creating content, authors should consider their work as part of the archive that is informative about the resources on the domain. If content is out of date, it should be marked as such and a new document created rather than overwriting the original. This is a matter of judgement as it is necessarily subjective.

Classes of URI

The preceding sections point to four distinct classes of URI on ref.gs1.org:

  1. URIs of immutable documents, typically indicating a version or date in the URI.
  2. ‘Current version’ alias URIs that may serve (or redirect to) different immutable documents over time.
  3. Living documents, especially vocabularies, to which new content may be added but from which no content may be completely deleted.
  4. URIs of documents that may be changed.

Number of resources

At the time of writing, the expectation is that the server will handle a relatively small number of resources. Given the long-term aim, it is unsafe to assume that this will always be the case and, anyway, the volume of material on the server should only grow over time so ‘good housekeeping’ is essential.

Avoid file extensions where possible

File extensions give a strong indication of the format of the file. It is the nature of the world that technology changes over time. Therefore, persistent URIs should not normally include file extensions except where the type of file is an intrinsic feature. For example, an XML schema or JSON-LD context file exists as a reference point within that specific technology. Therefore, it is appropriate to include the relevant file extension. For more general documents, including human-readable standards publications, the server configuration should make use of content negotiation, even where there is only one data format for the resource. This allows for a future where the original file’s function is provided by a new data format of the same resource. The commonly experienced data formats of RDF in XML, Turtle, and JSON-LD is a classic example of this. Until recently, all GS1 standards were published as PDFs. It is possible that they will one day be re-published as HTML documents.

Document classes and their top level paths

In the following examples, URIs written in monospace font with elements enclosed in braces, for example, ref.gs1.org/standards/{standardName}, should be read as templates where the content of the braces (only) is replaced by a relevant real value.

Standards

The current version of a standard is always available via ref.gs1.org/standards/{standardName}. A complete archive of versions of the standard is always available at ref.gs1.org/standards/{standardName}/archive. Any normative artefacts that form part of the current standard but that exist in their own right are listed at ref.gs1.org/standards/{standardName}/artefacts.

The un-versioned URI is an alias for the latest version of the document. Every version of the standard is available as an immutable document at a versioned URI of the form ref.gs1.org/standards/{standardName}/{X.Y.Z}/. It follows that normative artefacts for the specific version of the standard are available at ref.gs1.org/standards/{standardName}/{X.Y.Z}/artefacts. For example:

It is important that the versioning rules are adhered to consistently:

  • The first number indicates a major release. For example, 1 is the first release, while 2 indicates a new release that is incompatible with release 1.
  • The second digit is used for a minor release. This indicates backward-compatible additions or small changes to the wording or structure.
  • The third field is used for any subsequent change to a published standard that does not necessitate a more significant release number change and is typically for errata and bug fixes.

All three digits should be included so that, for example, the second major iteration of a standard will be at ref.gs1.org/standards/{standardName}/2.0.0 (not just /2).

When a new version of a standard is created, all assets associated with the new version are published to the new version directory, even those that are unchanged from the previous version.

A page at ref.gs1.org/standards/{standardName}/archive will include a list of the available versions in reverse version order. It can, of course, also include other content and list other assets as deemed desirable but it does not replace the standard’s landing page on the www.gs1.org site which remains the marketing-led entry point to the standard.

Guidelines

As well as standards, guidelines are developed and ratified under the GSMP. They typically refer to a single standard but some may provide guidance on implementing multiple standards. Even when related to a single standard, they are typically developed and maintained under a different time line to the standard itself. For these reasons, guidelines will be published under a their own top level directory of ref.gs1.org/guidelines/{guidelineName} pointing to the latest version and immutable versions published in the same style as for standards.

Other formal GS1 documents

There is a small number of documents that are neither standards nor guidelines but that nevertheless are formally published and updated over time. Examples include the GS1 Architecture document, the GSMP manual and this document. Such documents should be published at ref.gs1.org/gs1/{docName} following the same pattern as for standards and guidelines.

Tools

GS1 creates and maintains tools that exemplify its standards and aids their implementation. Typically, these will be published and maintained as open source software in GitHub. It is appropriate in some cases to publish the tool, or perhaps a snapshot of the tool, on ref.gs1.org. Examples include the syntax dictionary and the GS1 Digital Link resolver test suite. It is a matter of judgement as to whether any specific tool, or at least its user interface, should be published on ref.gs1.org but doing so does imply that the tool is itself a reference for implementations and is expected to be maintained as the relevant standard is itself maintained.

Tools will be published under ref.gs1.org/tools/{toolName} and are not expected to be versioned (since the source code is itself versioned on GitHub).

Vocabularies and reference terms

Formally-defined terms, such as vocabulary terms, application identifiers, glossary terms etc. take a top-level directory of their own and form a clean, referenceable URI. Examples include

  • https://ref.gs1.org/epcis/eventTime (a term from the EPCIS vocabulary)
  • https://ref.gs1.org/cbv/BizStep-shipping (a term from the CBV vocabulary)
  • https://ref.gs1.org/voc/Product (a term from the GS1 Web Vocabulary)
  • https://ref.gs1.org/ai/01 (the GTIN AI)

These are not aliases. They are the formal URI for a defined term that can be used, for example, in Linked Data applications. Terms may be deprecated - that is, flagged in some way to say that the term should not be used - but never deleted entirely. Their definitions can be updated but only in a manner that is backwards compatible. If a ‘breaking change’ is required, mint a new term and deprecate the old one.

Formal terms may be provisioned in whichever way is appropriate at the time to provide a browsable interface, and such ‘browser code’ can be updated or replaced entirely behind the scenes, but each term should be accessible directly by its permanent URI.

Other documents

The /docs directory is the ‘everything else we want to publish permanently’ bucket. In general, documents published under /docs will be in a sub directory that is the year of publication, such as ref.gs1.org/docs/2022/. The rules around creating sub directories of those year-of-publication directories can be relatively relaxed since the year of publication - which is always a fixed data point - provides a basis for disambiguation between documents that may have similar names.

Documents published under /docs do not have aliases.

URI style

The following style guide is intended to encourage consistency in URI design.

  1. Acronyms and/or abbreviations shall be used to avoid excessively long URIs. For example use ref.gs1.org/guidelines/mrhi rather than ref.gs1.org/guidelines/mobile-ready-hero-images.
  2. All URIs shall be in lower case. This does not apply where convention dictates otherwise, in particular, where they identify terms in a vocabulary. For example UpperCamelCase is used to identify classes and lowerCamelCase is used to identify properties.
  3. A hyphen [-] may be used to separate text elements in the URL. Underscores [_] should not be used. For example, use ref.gs1.org/standards/epcis/2.0.0/epcis-json-schema.json rather than ref.gs1.org/standards/epcis/2.0.0/epcis_json_schema.json
  4. For versioned documents, the full three digit version number, separated by dots [.] shall be used in the URL. When the version number appears in the URL, it does not need to be repeated. For example: ref.gs1.org/standards/epcis/2.0.0/epcis-json-schema.json is the correct form to be used rather than any of ref.gs1.org/standards/epcis/2/epcis-json-schema.json, ref.gs1.org/standards/epcis/2-0-0/epcis-json-schema.json or ref.gs1.org/standards/epcis/2.0.0/epcis-2.0.0-json-schema.json.