Identifier Converter for EPCIS 2.0 and GS1 DigitalLink
OpenEPCIS solution to convert EPCIS instance or class identifier from URN to digital link WebURI and vice versa.
Quick links
The identifier converter is available as a web application, as an API and as source code:
- Identifier converter web application: https://tools.openepcis.io/ui/format-converter
- Identifier converter API endpoint: https://tools.openepcis.io/q/swagger-ui/#/Identifier%20Converter
- Identifier converter application code: https://github.com/openepcis/openepcis-epc-digitallink-translator
Introduction
Every physical or digital object in EPCIS, whether a document, a location, a product or an asset, is identified by a universal identifier. Up to EPCIS 1.2, these identifiers could only be written as URNs. Since EPCIS 2.0 they can be written either as an EPC URI (Pure Identity URI) or as a GS1 Digital Link Web URI, and applications using EPCIS must use one of these two syntaxes. The Pure Identity URI uses the URN (Uniform Resource Name) format. Here is a GTIN (Global Trade Item Number) with a serial number in URN format:
urn:epc:id:sgtin:952012.0345678.1001
The Digital Link URI (Uniform Resource Identifier) is the format EPCIS 2.0 added for writing identifiers as Web URIs. The same identifier looks like this as a Digital Link URI:
https://id.gs1.org/01/09520123456788/21/1001
Some organizations use both formats side by side for better visibility and accessibility, and they need to translate between URN and Digital Link URI in both directions. The OpenEPCIS identifier converter performs this translation for the standard GS1 application identifiers. It works on its own and together with the other OpenEPCIS tools, and it supports the identifier types listed below.
Supported instance-level identifiers
- GTIN (GTIN): Global Trade Item Number
- GTIN with serial (SGTIN): Serialised Global Trade Item Number
- SSCC: Serial Shipping Container Code
- UPUI: Unit Pack Identifier
- GDTI with serial: Global Document Type Identifier
- SGCN with serial: Serialised Global Coupon Number
- GINC: Global Identification Number for Consignment
- GSIN: Global Shipment Identification Number
- GRAI with serial: Global Returnable Asset Identifier
- GIAI: Global Individual Asset Identifier
- ITIP: Individual Trade Item Piece
- CPI with serial: Component/Part Identifier
- GSRN: Global Service Relation Number (Recipient)
- GSRNP: Global Service Relation Number (Provider)
Supported class-level identifiers
- GTIN: Global Trade Item Number
- GTIN + Lot (LGTIN): GTIN + Batch/Lot
- GTIN + Serial (SGTIN): GTIN + Serial
- GDTI without serial
- SGCN without serial
- GRAI without serial
- CPI without serial
Supported location/party identifiers
- GLN with extension: Global Location Number with extension
- GLN without extension: Global Location Number without extension
- Party GLN: Party Global Location Number
Usage
You can convert identifiers between URN and Digital Link URI in the browser, through the API or from the command line.
Web Application
In the web application you enter an EPCIS identifier as a URN or as a Digital Link Web URI and get it back in the other format. You can also upload a whole EPCIS document that uses either URN or Web URI identifiers and convert it between the two formats. The web application is available here.
API Endpoint
The identifier converter API accepts an identifier and returns the converted identifier in its response. You can call it from your own application's code or try it online through Swagger-UI, which is available here.
Command Line
cURL (Client URL) is a widely used command-line tool for sending data to a server and receiving its response, and many developers prefer it to a web interface. To convert an identifier with cURL, post it to
https://tools.openepcis.io/api/convert/identifier/urn or https://tools.openepcis.io/api/convert/identifier/web-uri, depending on the target format. The following request converts a URN to a Digital Link Web URI:
curl -X 'POST' \
'https://tools.openepcis.io/api/convert/identifier/web-uri' \
-H 'accept: application/json' \
-H 'Content-Type: text/plain' \
-d 'urn:epc:id:sgtin:952012.0345678.1001'
Application code
The converter is written mainly in Java. You can get the code here and use it in your own projects.
Conversion from URN to DL URI
To convert a URN to a Digital Link URI, call the following method with the URN:
ConverterUtil.toURI(inputURN);
The method detects the identifier type, converts it to the matching Digital Link URI and returns it as a String. If the URN does not follow the GS1 identifier syntax, the method throws an exception.
This example converts an SGTIN from URN to Digital Link URI:
System.out.println(ConverterUtil.toURI("urn:epc:id:sgtin:952012.0345678.1001"));
//https://id.gs1.org/01/95201203456781/21/1001
Conversion from DL URI to URN
To convert a Digital Link URI to a URN, call the following method with the Digital Link URI and the GCP length:
ConverterUtil.toURN(inputURI, gcpLength);
The method detects the identifier type, converts it to the matching URN and returns a Map<String, String> with the URN and further details. If the
inputURI does not follow the GS1 identifier syntax, the method throws an exception.
This example converts an SGTIN from Digital Link URI to URN:
System.out.println(ConverterUtil.toURN("https://id.gs1.org/01/95201203456781/21/1001", 10));
// {gtin=95201203456781, asURN=urn:epc:id:sgtin:952012.0345678.1001,
// asCaptured=https://id.gs1.org/01/95201203456781/21/1001,
// serial=1001, canonicalDL=https://id.gs1.org/01/95201203456781/21/1001}
Conversion from class level URN to Web URI
To convert a class-level URN to a Web URI, call the following method with the URN. The method detects the identifier type, converts it to the matching Web URI and reports any error it finds in the identifier.
ConverterUtil.toURIForClassLevelIdentifier(inputURN);
This example converts a GTIN from URN to Web URI:
System.out.println(ConverterUtil.toURIForClassLevelIdentifier("urn:epc:idpat:sgtin:3489348.939489.*"));
//https://id.gs1.org/01/93489348394895
Conversion from class level Web URI to URN
To convert a class-level Digital Link URI to a URN, call the following method with the URI, with or without the GCP length. Without a GCP length, the method determines it from the GS1 standards.
ConverterUtil.toURNForClassLevelIdentifier(inputURI, gcpLength);
ConverterUtil.
toURNForClassLevelIdentifier(inputURI);
This example converts a GTIN from Web URI to URN:
System.out.println(ConverterUtil.toURNForClassLevelIdentifier("https://id.gs1.org/01/88588588585452"));
// {gtin=88588588585452, asURN=urn:epc:idpat:sgtin:8588588.858545.*,
// asCaptured=https://example.com/path/01/88588588585452,
// canonicalDL=https://id.gs1.org/01/88588588585452}
Conversion from URN to Bare String
To convert CBV values in URN format to bare strings, call the following method with the CBV value:
ConverterUtil.toBareStringVocabulary(eventVocabulary);
This example converts a business step in CBV URN format to a bare string:
ConverterUtil.toBareStringVocabulary("urn:epcglobal:cbv:bizstep:inspecting");
//inspecting
Conversion from Bare String to URN
To convert bare strings to CBV values in URN format, call the following method with the bare string:
ConverterUtil.toUrnVocabulary(eventVocabulary);
This example converts a business step given as a bare string to its CBV URN:
ConverterUtil.toUrnVocabulary("inspecting");
//urn:epcglobal:cbv:bizstep:inspecting