---
updatedAt: 2025-06-02T21:39:44.000Z
agentTools:
  projectIndex: https://developers.evrythng.com/llms.txt
---

# digital-link.js

[`digital-link.js`](https://github.com/evrythng/digital-link.js) is a JavaScript library for creating, verifying, and representing/transferring GS1 Digital Links in JavaScript front-end and back-end applications. It can create UIs for Digital Link creation, as well as a validation step for data storage/processing systems.

This is the library powering the EVRYTHNG [GS1 Digital Link Tools project](https://digital-link.evrythng.com/), which allows easy generation and validation of GS1 Digital Links through a UI.

***

## Installation

The library is installed through [`npm`](https://www.npmjs.com/package/digital-link.js):

```shell
npm i --save digital-link.js
```

After you finish installing, include the library using `require` (for web applications, a modern bundler such as Webpack or Parcel is recommended):

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

***

## Usage Examples

Create a `DigitalLink` using the setter functions, useful if the UI handles each set of elements separately, or the elements come from different sources/datasets:

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

const dl = DigitalLink();
dl.setDomain('https://dlnkd.tn.gg');
dl.setIdentifier('01', '9780345418913');
dl.setKeyQualifier('21', '43786');
dl.setAttribute('thngId', 'UMwxDXBdUbxgtyRaR2HBrc4r');
```

Alternatively, create the `DigitalLink` from an object describing individual elements:

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

const dl = DigitalLink({
  domain: 'https://dlnkd.tn.gg',
  identifier: {
    '01': '9780345418913',
  },
  keyQualifiers: {
    '21': '43786',
  },
  attributes: {
    thngId: 'UMwxDXBdUbxgtyRaR2HBrc4r',
  },
});
```

Finally, create the `DigitalLink` from an existing (possibly user input) URI string:

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

const uri = 'https://dlnkd.tn.gg/01/9780345418913/21/43786?thngId=UMwxDXBdUbxgtyRaR2HBrc4r';

const dl = DigitalLink(uri);
```

After it's created, a `DigitalLink` can validate itself:

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

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

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

It can also generate URI string and JSON string representations as results:

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

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

console.log(dl.toWebUriString());
console.log(dl.toJsonString());
```

Some utility functions are available for specific use cases (see *Function Reference* below). Also, see the [`README.md`](https://github.com/evrythng/digital-link.js/blob/master/README.md) file for more usage examples.

***

## Function Reference

### Creation

A `DigitalLink` object can be created using multiple input representations.

```
DigitalLink();        // Create empty object to be populated with setters
DigitalLink(string);  // Create from URI string
DigitalLink(object);  // Create from object (see examples)
```

After it's created, all the functions below apply to each instance.

### Setters

Use setters to add or change one part of the overall Digital Link object.

```
.setDomain(domain);            // Set the URI domain

.setIdentifier(key, value);    // Set the identifier

.setKeyQualifier(key, value);  // Set a single key qualifier

.setAttribute(key, value);     // Set a single attribute
```

### Getters

Use getters to retrieve one part of the Digital Link object. Useful if the input was a raw URI string.

```
.getDomain();           // Get the domain

.getIdentifier();       // Get the identifier

.getKeyQualifier(key);  // Get a single key qualifier

.getKeyQualifiers();    // Get the list of key qualifiers

.getAttribute(key);     // Get a single attribute

.getAttributes();       // Get the list of attributes
```

### Outputs

The outputs of a `DigitalLink` object after construction allow easy conversion to multiple output formats, as well as validation with trace details.

```
.toWebUriString();      // Output a GS1 Digital Link URI string

.toJsonString();        // Output a JSON representation of the DigitalLink that
                        // can construct a changed version directly

.isValid();             // Outputs true if the URI string is valid

.getValidationTrace();  // Output an object containing an array of major
                        // validation steps. Useful for debugging purposes
```

\### Utilities

There are a couple of utility functions also available for specific use-cases such as HTML generation and validation of individual rules according to the underlying grammar scheme.

First, import `Utils`:

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

Then, use each utility function directly from the `Utils` import:

```
Utils.Rules                           // Object of rules available to use with 
                                      // the testRule() function

Utils.testRule(rule, value)           // Test a single rule from Rules

Utils.generateStatsHtml(uriString)    // Generate apglib HTML for stats

Utils.generateTraceHtml(uriString)    // Generate apglib HTML for validation
                                      // trace results

Utils.generateResultsHtml(uriString)  // Generate apglib HTML for validation 
                                      // results details
```