digital-link.js

Javascript library by Digimarc for creating, verifying, and representing/transferring GS1 Digital Links.

This is the library powering the GS1 Digital Link Tools project, which allows easy generation and validation of GS1 Digital Links via a UI.

• Installation
• Usage
• Test App
• Utilities
• Unit Tests

Installation

Node.js or bundler

Install via npm:

$ npm i --save digital-link.js

Then require it in code:

const { DigitalLink, Utils } = require('digital-link.js');

Script tag

Add a <script> tag to your HTML page:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/digital-link.js.browser.js"></script>

Then access the digitalLinkJs global variable:

const { DigitalLink, Utils } = digitalLinkJs;

Usage

The DigitalLink object can be created in three ways - with options, using setters, or an existing URL string. Either method of creation will produce the same result.

Create with object

The object can contain the following items:

• domain (string) - The domain name of the Digital Link.
• identifier (object) - An object containing a single GS1 Application Identifier, such as GTIN, as a key-value pair.
• keyQualifiers (object) - An object containing one or more GS1 Key Qualifiers as key-value pairs.
• attributes (object) - As for keyQualifiers, but containing GS1 Data Attributes and custom extensions supported in the standard as query parameters.
• sortKeyQualifiers (boolean) - false by default. If you set it to true, the key qualifiers will be sorted in the Web URI String to match the order defined by the GS1 Digital Link Grammar.
• keyQualifiersOrder (Array) - It's an array that contains all the keys of the key qualifiers. If the length of the array is not equal to the length of the keyQualifiers field, this array will be ignored. In this case, the order of the key qualifier in the Web URI String will be the order of the map. Otherwise (if the length of the two fields are equal), the order of the key qualifier in the Web URI String will be the order define in this field.
• linkType - (string) - This optional parameter allows you to request standard types of information for a particular Digital Link.

An example is shown below:

const { DigitalLink } = require('digital-link.js');

const dl = DigitalLink({
  domain: 'https://dlnkd.tn.gg',
  identifier: {
    '01': '00860080001300',
  },
  keyQualifiers: {
    '21': '43786',
    '10': '12345'
  },
  keyQualifiersOrder: [
    '10','21'
  ],
  linkType : webVoc.linkType.allergenInfo,
  attributes: {
    thngId: 'UMwxDXBdUbxgtyRaR2HBrc4r',
  },
});

Alternatively, you can add the line below to replace the keyQualifiersOrder. This will sort them automatically.

sortKeyQualifiers: true

Create with setters

The equivalent to the object-based example above can also be created piecemeal using setters:

const { DigitalLink } = require('digital-link.js');

const dl = DigitalLink();
dl.setDomain('https://dlnkd.tn.gg');
dl.setIdentifier('01', '00860080001300');
dl.setKeyQualifier('21', '43786');
dl.setKeyQualifier('10', '12345');
dl.setKeyQualifiersOrder(['10', '21']);
dl.setLinkType('gs1:allergenInfo');
dl.setAttribute('thngId', 'UMwxDXBdUbxgtyRaR2HBrc4r');

Setters can also be chained:

const { DigitalLink } = require('digital-link.js');

const dl = DigitalLink()
  .setDomain('https://dlnkd.tn.gg')
  .setIdentifier('01', '00860080001300')
  .setKeyQualifier('21', '43786')
  .setKeyQualifier('10', '12345')
  .setKeyQualifiersOrder(['10', '21'])
  .setLinkType('gs1:allergenInfo')
  .setAttribute('thngId', 'UMwxDXBdUbxgtyRaR2HBrc4r');

Create from Web URI aka URL

A DigitalLink object can also be created using an existing string:

const uri = 'https://dlnkd.tn.gg/01/00860080001300/10/12345/21/43786?linkType=gs1:allergenInfo';

const dl = DigitalLink(uri);

Web URI and JSON Generation

A DigitalLink object can transform itself into a string Web URI (aka URL) representation:

const uri = dl.toWebUriString();

console.log(uri);

It is also possible to view the object makeup of the DigitalLink. This can then be used to construct the same DigitalLink from an object.

// Get JSON representation
const jsonString = dl.toJsonString();
console.log(jsonString);

// Create DigitalLink using same data
const dl2 = DigitalLink(JSON.parse(jsonString));

Link Types - linkType

The SDK supports the GS1 Digital Link linkType feature. Link types allow applications to request specific information for a given product. For instance an application could request allergen information for a given GTIN by adding the link type linkType=gs1:allergenInfo. Supported standard link types are specified in the GS1 Web Vocabulary and additionally you can define your own types.

setLinkType and getLinkType allow specifying respectively reading a link type. On top of this the SDK provides a convenient list of all supported standard link types. To use it simply import webVoc as shown below:

const { DigitalLink, webVoc } = require('digital-link.js');
dl.setLinkType(webVoc.linkType.allergenInfo);

Digital Link Validation

Once created, the DigitalLink object can validate itself:

const isValid = dl.isValid();

console.log(`Is the Digital Link valid? ${isValid}`);

You can also view the validation trace output at each match stage. Any remainder after the last stage can be deemed erroneous, as it did not match any rule in the grammar:

const dl = DigitalLink('https://gs1.evrythng.com/01/9780345418913x');
const trace = dl.getValidationTrace();

console.log(trace);

The example above contains an erroneous 'x' at the end, so it does not validate:

{
  "trace": [
    { "rule": "scheme", "match": "https", "remainder": "://gs1.evrythng.com/01/9780345418913x" },
    { "rule": "reg-name", "match": "gs1.evrythng.com", "remainder": "/01/9780345418913x" },
    { "rule": "host", "match": "gs1.evrythng.com", "remainder": "/01/9780345418913x" },
    { "rule": "hostname", "match": "gs1.evrythng.com", "remainder": "/01/9780345418913x" },
    { "rule": "customURIstem", "match": "https://gs1.evrythng.com", "remainder": "/01/9780345418913x" },
    { "rule": "gtin-code", "match": "01", "remainder": "/9780345418913x" },
    { "rule": "gtin-value", "match": "9780345418913", "remainder": "x" },
    { "rule": "gtin-comp", "match": "/01/9780345418913", "remainder": "x" },
    { "rule": "gtin-path", "match": "/01/9780345418913", "remainder": "x" },
    { "rule": "gs1path", "match": "/01/9780345418913", "remainder": "x" },
    { "rule": "gs1uriPattern", "match": "/01/9780345418913", "remainder": "x" },
    { "rule": "customGS1webURI", "match": "https://gs1.evrythng.com/01/9780345418913", "remainder": "x" }
  ],
  "success": false
}

Warning : if your domain contains a custom path (for example : https://example.com/custom/path/01/00860080001300), It will be removed (https://example.com/01/00860080001300) in the validation trace. That's because the Digital Link Grammar file doesn't support the custom paths.

Warning : The isValid method also checks if the identifier has a valid check digit. If it isn't the case, it will return false. However, the getValidationTrace won't show any error since it doesn't take into account the check digit verification.

Compression

The GS1 Digital Link standard also describes an (offline) compression/decompression mechanism that allows for shorter URLs and hence unlocks use cases where the size of the data carrier (e.g., QR code) is very limited.

To create a compressed URI, use the toCompressedWebUriString() method:

const uri = 'https://dlnkd.tn.gg/01/00860080001300/21/43786';
const dl = DigitalLink(uri);

const compressedUri = dl.toCompressedWebUriString();

To attempt decompression of a compressed URI use the constructor function as usual:

const compressedUri = 'https://dlnkd.tn.gg/DBHKVAdpQgqrCg';

const dl = DigitalLink(compressedUri);

Note: decompression will fail if the result is not a valid GS1 Digital Link.

The Utils object also provides methods for direct compression and decompression of URI strings:

const { Utils } = require('digital-link.js');

const uri = 'https://dlnkd.tn.gg/01/00860080001300/21/43786';

// Compress a URI
const compressedUri = Utils.compressWebUri(uri);

// Compress without optimisations or compressing other key-value pairs
const useOptimisations = false;
const compressOtherKeyValuePairs = false;
const semiCompressedUri = Utils.compressWebUri(uri, useOptimisations, compressOtherKeyValuePairs);

// Decompress a compressed URI
const decompressedUri = Utils.decompressWebUri(compressedUri);

// Detect if a URI is compressed
const isCompressed = Utils.isCompressedWebUri(compressedUri);

Test App

The test-app directory contains a simple app built with Hyperapp that demonstrates how to easily build a simple GS1 Digital Link verification tool using this SDK.

To use it:

1. cd test-app && npm i
2. npm run serve
3. Open http://localhost:1234/index.html in a browser of choice.
4. Enter or type a GS1 Digital Link, and observe the validity.

The trace steps (which matched a parser rule) are also shown, allowing you to see which parts of your input did not match any rule. The output of toJsonString() is also shown as an insight into the make-up of the URL itself.

Utilities

Since this library is based on apglib, it can do more than simply validate GS1 Digital Link URLs. The Utils object allows a single Application Identifier to be validated (as well as a whole canonical URL). All available individual rules are available from the Rules object

For example, validating a GTIN by itself:

const { Utils } = require('digital-link.js');

// Validate a GTIN
const gtin = '00860080001300';
const rule = Utils.Rules.gtin;

console.log(`Is the GTIN ${gtin} valid? ${Util.testRule(rule, gtin)}`);

It also allows generation of simple HTML tables that detail the results of the parser run against the input:

const { DigitalLink, Utils } = require('digital-link.js');

const dl = DigitalLink('https://gs1.evrythng.com/01/00860080001300');

// See all the parser trace steps for a given DigitalLink URL
traceSpan.innerHTML = Utils.generateTraceHtml(dl.toUrlString());

// See all the parser stats for a given DigitalLink URL
statsSpan.innerHTML = Utils.generateStatsHtml(dl.toUrlString());

// See all the parser results for a given DigitalLink URL
resultsSpan.innerHTML = Utils.generateResultsHtml(dl.toUrlString());

Warning : if your domain contains a custom path (for example : https://example.com/custom/path/01/00860080001300), We recommand you to remove it (https://example.com/01/00860080001300) by calling Utils.removeCustomPath() for the generateTraceHtml, generateStatsHtml and generateResultsHtml functions. Since the Digital Link Grammar file doesn't support the custom path. Otherwise, all your fields (identifier, key qualifiers, ...) won't be recognized.

ABNF Grammar

The generation of this tool is based on the standard's ABNF grammar. The grammar files corresponding to each version of the standard can be found in the grammar folder.

The grammar files are used by the apglib library to generate the grammarObject.js file.

To update the grammar object go to the grammar folder and run the following command:

apg -i GS1_Digital_Link_Grammar_<VERSION_NUMBER>.abnf -o ../lib/grammarObject.js

This will generate the grammarObject.js file in the lib folder. You will have to apply some modifications to the generated file to make it work.

Generated grammarObject.js file

// Generated by JavaScript APG, Version [`apg-js2`](https://github.com/ldthomas/apg-js2)
module.exports = function(){
"use strict";
  //```
  // [...]
}

Updated grammarObject.js file

/* eslint-disable */
  
// Generated by JavaScript APG, Version [`apg-js2`](https://github.com/ldthomas/apg-js2)
module.exports = {
  grammarObject: function(){
  "use strict";
    //```
    // [...]
  }
}

As the generated file is not exporting an object, so you have to wrap it into an object with grammarObject field to be able to use it.

Unit Tests

Unit tests can be run with the npm test command, and cover all methods, creation methods, and output formats.

Third party libraries

digital-link.js was built using some great third party libraries, in particular:

• apglib - which is used to verify links based on the standard ABNF grammar.
• GS1DigitalLinkCompressionPrototype - which is a prototype implementation of the Digital Link compression as specified in the GS1 Digital Link 1.1 draft specification.

Deployment

This tool is deployed using npm publish command. The version should be updated in the package.json file. Once the version is updated, you should create a new release on GitHub with the new version number, and update the Script tag section of this README with the last version number.