URI policy for ref.gs1.org

Purpose of the domain

The domain ref.gs1.org is the place where GS1 Global Office departments may host content on the web in a way that ensures both:

1. persistence of the URL of the content and (e.g., so that the link itself never changes); and
2. permanence of the content itself (e.g., so that the content never changes or disappears).

The primary use case is for GS1 standards, guidelines and related resources, such as machine-readable files and position papers, that 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 for all content 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.

Change management

Resources on ref.gs1.org will typically be associated with and defined by formal processes within GS1. For example, standards, guidelines and their related resources will be managed according to the Global Standards Management Process (GSMP); anything published under ref.gs1.org/architecture will be produced by the Architecture Group and so on. Other resources that define or support GS1 processes and services, and that benefit from persistent hosting, may also be published on ref.gs1.org.

The detailed management of which department or member of staff has authority over which sections of ref.gs1.org will change over time as individual roles and responsibilities within the organisation evolve. Those details are out of scope for this document, but the underlying principle is that all content hosted on the domain will have been subject to an applicable review process and be "signed off" by the relevant senior member of staff.

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.

• URI persistence means that the same URI will function indefinitely.
• Immutable content remains unchanged indefinitely.

To give an example of the difference, consider the versioned document at ref.gs1.org/standards/epcis/2.0.0/ that was published in June 2022. This document will never change. Following publication and implementation, minor errors were detected in that document so that in July 2025, version 2.0.1 was published at https://ref.gs1.org/standards/epcis/2.0.1/. Again, this version will never 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. On the day of publication of version 2.0.0, the shorter, un-versioned URI https://ref.gs1.org/standards/epcis returned version 2.0.0 as it was the latest version. However, when version 2.0.1 was published that same, persistent, un-versioned URI returned 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

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.

Documents may be published using Microsoft Office files formats, however, an equivalent document in a standard format should also be published alongside it. For example, the Global Data Model (GDM) is published as an Excel file. However, an Open Office version is also published. Both are linked from that standard's artefacts page.

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.

Note that within an HTTP exchange, the content type (a.k.a. Media Type or MIME Type) of an online resource is conveyed separately from the URI itself. For example, the URI https://ref.gs1.org/docs/2023/QR-Code_powered-by-GS1-best-practices does not indicate the format of the document. However, at the HTTP level, the server returns the following headers

HTTP/1.1 200 OK
Date: Fri, 25 Jul 2025 13:40:29 GMT
Content-Type: application/pdf
Content-Length: 1096440
Connection: keep-alive
Content-Location: QR-Code_powered-by-GS1-best-practices.pdf
Vary: negotiate

Note the Content Type header that shows that the document is a PDF. If a future version of that document were published in a different format, the existing URI would still function perfectly well.

Versioned documents

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.

The current version of a document is always available via an un-versioned URL of the form ref.gs1.org/{document-type}/{document-name} such as ref.gs1.org/standards/genspecs/. A complete archive of versions of the document is always available at ref.gs1.org/{document-type}/{document-name}/archive. Any associated artefacts are listed at ref.gs1.org/{document-type}/{document-name}/artefacts.

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

• The current version of the EPCIS standard is available at https://ref.gs1.org/standards/epcis. Even when the standard is updated, this same URI will return whatever the current version of the standard is.
• Version 2.0.0 of the EPCIS standard, which is an immutable document, is available at https://ref.gs1.org/standards/epcis/2.0.0
• Normative artefacts that form part of the current EPCIS standard are available at https://ref.gs1.org/standards/epcis/artefacts
• Normative artefacts that specifically form part of version 2.0.0 of the EPCIS standard are available at https://ref.gs1.org/standards/epcis/2.0.0/artefacts
• The archive of all available versions of the EPCIS standard is available at https://ref.gs1.org/standards/epcis/archive

Versioning rules are defined in the GS1 Style Guide. On ref.gs1.org, the slight deviation is that all three integers 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 document 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.

An 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 archive pages are not replacements for the relevant landing page on the www.gs1.org site which remains the marketing-led entry point to GS1.

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 the GSMP manual, the standards disclaimer and this document. Such documents should be published at ref.gs1.org/gs1/{docName} following the same pattern as for standards and guidelines, complete with archive.

Tools & test suites

GS1 creates and maintains tools and test suites 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 at https://ref.gs1.org/tools/gs1-barcode-syntax-resource/syntax-dictionary/ and the GS1 Digital Link resolver test suite at https://ref.gs1.org/test-suites/resolver/. 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).

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.