Quick links

Below are links to the OpenEPCIS tools and code referenced on this documentation page. For enhanced understanding and practical experience with these tools, we recommend visiting and utilizing them:

• Format converter web application : https://tools.openepcis.io/ui/format-converter

• Format converter API endpoint : https://tools.openepcis.io/q/swagger-ui/#/Format%20Converter

• Format converter application code : https://github.com/openepcis/openepcis-document-converter

Introduction

EPCIS up to 1.2 was an XML-only standard. EPCIS 2.0 added JSON / JSON-LD as a first-class transport, which means organisations now need to move documents between formats — XML in from one partner, JSON-LD out to another, or the reverse — without losing detail.

The OpenEPCIS format converter handles that translation for the full EPCIS document shape: events, user extensions, sensor elements, masterdata blocks, the GS1-Extensions header semantics. The open-source converter is XSLT-based — a clean approach for single events and small batches with plain event shapes. For multi-gigabyte exports, deep extension trees and mixed 1.2 / 2.0 corpora the Business edition adds a SAX-streaming converter that processes documents with bounded memory and plugs straight into the validation + event-hash pipeline.

Both converters emit documents conformant to the EPCIS 2.0 schema.

Usage

Following section provides quick overview of how to convert the EPCIS document from one format to other:

Web application

By providing either an XML or JSON/JSON-LD EPCIS document as input, users can easily access and obtain the transformed EPCIS document using the web application. You can access the web tool from here.

Swagger-UI

Users/develoers can make use of the API to send requests to the OpenEPCIS document format converter API using an EPCIS document as the input, and to receive the converted document back as a response. These APIs can also be utilized from within another application’s code or directly online. Users can access the REST endpoint using Swagger-UI from here.

Command Line

Client URL or popularly known as cURL is a command-line utility that is used to send and receive data from or to a server. As many developers and users prefer using this utility over normal web applications, OpenEPCIS Format Converter supports the conversion of EPCIS document/event using the cURL command. Users can make requests to the Document Format Converter service https://tools.openepcis.io/api/convert/json/2.0 or https://tools.openepcis.io/api/convert/xml/2.0 using their preferred document. Following is an example of a cURL request to convert the JSON document to XML format:

curl -X 'POST' \
  'https://tools.openepcis.io/api/convert/xml/2.0' \
  -H 'accept: application/xml' \
  -H 'Content-Type: application/json' \
  -d '{
  "@context": ["https://gs1.github.io/EPCIS/epcis-context.jsonld",{"example": "http://ns.example.com/epcis/"}],
  
  "id": "https://id.example.org/document1",
  "type": "EPCISDocument",
  "schemaVersion": "2.0",
  "creationDate":"2019-11-01T14:00:00.000+01:00",
  "epcisBody": {
   "eventList": [
     {
        "eventID": "ni:///sha-256;025ac144187a8c5e14caf4d1cfa69250a33dc59a5bc42a68d31b1b5e55a3f15a?ver=CBV2.0",
        "type": "AssociationEvent",
        "eventTime": "2019-11-01T14:00:00.000+01:00",
        "eventTimeZoneOffset": "+01:00",
        "parentID":"urn:epc:id:grai:4012345.55555.987",
        "childEPCs":["urn:epc:id:giai:4000001.12345"],
        "action": "ADD",
        "bizStep": "assembling",
        "readPoint": {"id": "urn:epc:id:sgln:4012345.00001.0"}
     }

   ]
  }
}'

Application Code

The application has been primarily developed using Java. The code is available at the OpenEPCIS GitHub account and can be accessed directly or as dependencies for other projects. The complete code can be found here.

Converting XML to JSON/JSON-LD document

To convert an EPCIS 2.0 XML document to JSON/JSON-LD, provide the XML data as an InputStream to the conversion method VersionTransformer.class:

final InputStream xmlStream=getClass().getResourceAsStream("/convert/xmlDocument.xml");
final Conversion conversion=Conversion.builder()
        .generateGS1CompliantDocument(false)
        .fromMediaType(EPCISFormat.XML)
        .fromVersion(EPCISVersion.VERSION_2_0_0)
        .toMediaType(EPCISFormat.JSON_LD)
        .toVersion(EPCISVersion.VERSION_2_0_0)
        .build();
final InputStream convertedDocument=new VersionTransformer().convert(xmlStream,conversion);
//System.out.println("Converted Version Transformer JSON : \n"+IOUtils.toString(convertedDocument,StandardCharsets.UTF_8));

Converting JSON/JSON-LD to XML document

To convert an EPCIS 2.0 JSON/JSON-LD document to XML, provide the JSON/JSON-LD data as an InputStream to the conversion method VersionTransformer.class:

final InputStream jsonStream=getClass().getResourceAsStream("/convert/JsonDocument.json");
final Conversion conversion=Conversion.builder()
        .generateGS1CompliantDocument(false)
        .fromMediaType(EPCISFormat.JSON_LD)
        .fromVersion(EPCISVersion.VERSION_2_0_0)
        .toMediaType(EPCISFormat.XML)
        .toVersion(EPCISVersion.VERSION_2_0_0)
        .build();
final InputStream convertedDocument=new VersionTransformer().convert(jsonStream,conversion);
//System.out.println("Converted XML document : "+IOUtils.toString(convertedDocument,StandardCharsets.UTF_8));

Dependencies

The event conversion logic depends on the openepcis-models package.