Data Structure Guidelines

GS1 EPCIS XML

The OriginTrail node supports the GS1 EPCIS 1.2 standard for importing and connecting data in the knowledge graph. You can learn more about the GS1 EPCIS standard here.

This document will show how the GS1 EPCIS data is represented in the Knowledge Graph inside one node.

Document data

EPCIS guideline suggests “Standard Business Document Header” SBDH standard for description of the document data. This part of data is in the EPCIS Header part of the file. It has basic information about the file (sender, receiver, ID, purpose…).

Although OriginTrail is the receiver of the file and it can be named as receiver (SBDH allows defining multiple receivers) it is not necessary to include this. Receiver is some entity involved in a business process, not in the data processing.

This data will be stored separately from the dataset contents within the knowledge graph, as metadata.

Master data

EPCIS standard describes 4 ways to process Master data. OriginTrail currently supports the most common way: including the Master data in the Header of an EPCIS XML document.

Since visibility event data contains only identifiers of objects, locations or parties, the Master data serves to further describe them in a more human readable way. This data will be connected to the visibility event data as long as the identifiers of master data are found inside visibility event data.

Visibility event data

Main focus of the EPCIS standard is formalizing description of event data that are generated by activities within the supply chain. OriginTrail supports ObjectEvent, AggregationEvent, TransformationEvent and TransactionEvent, which are thoroughly described in the standard. We strongly advise reading the GS1 EPCIS implementation guideline and to evaluate our example files.

Event data describes interactions between entities described with master data. OriginTrail distinguishes between two types of event data:

  • Internal events are related to processes of object movements or transformations (production, repackaging etc) within the scope of one supply chain participant’s business location (read point) as part of some business process.

    For example, this could be production or assembly that results in output which is used for further production or for sale (repackaging, labeling etc). The important distinction is that the ownership of event objects does not change during the event.

  • External events are related to processes between different supply chain participants (sales/purchases, transport). They represent processes where the jurisdiction or ownership of the objects gets changed in the supply chain. These types of events should use connectors for connecting between parties.

How an event is represented in the graph

When converting an EPCIS Visibility Event to graph, a central vertex will be created for the event. Any event identifiers will be created as separate vertices in the graph, connected to the event vertex, in order to enable connection to other entities with the same identifier.

Any observed objects in the event (the name varies depending on the event type, see the EPCIS data structure) will be added as separate vertices, with the relation created from the object to the event). This enables the objects to connect to their respective master data if available, as the information about the object will be set as that object’s properties.

If the event contains bizLocation and/or readPoint attributes, those will be created as separate vertices, similar to the way it is done for observed objects in the event.

Another part of a visibility event that generates a separate vertex is a connector, which is explained in the following section.

Connectors in EPCIS files

If the event is external (see above) and it should be connected to an event from another data creator’s dataset (such as a business partner) the bizTransactionList should have a bizTransaction attribute containing a connection identifier and the corresponding data creator’s decentralized identity (currently supported is the ethereum ERC-725 identity), separated by a colon. This will create a connector vertex in the graph, and connect it to the event it belongs to.

Once the corresponding data creator creates an event containing the same connection identifier with your decentralized identity, an analogous connector vertex will be created and the two connector vertices will be connected together. This feature enables querying the knowledge graph data belonging to multiple parties.

Permissioned data in EPCIS files

In cases when disclosing the full data publicly is not applicable to the implementation, it is possible to add a visibility property to an attribute of a VocabularyElement in the EPCISMasterData section. The data marked as permissioned will be visible only to the data creator and the parties the data creator marks as whitelisted via the API. More information on permissioned data is available at Vertex Data permissioning

There are two visibility options available:

In cases that only value of the attribute needs to be hidden this option should be used visibility="permissioned.show_attribute". Example:

<VocabularyElement id="id:Company_Green_with_permissioned_data">
    <attribute id="id:name" visibility="permissioned.show_attribute">Green</attribute>
</VocabularyElement>

In cases that whole attribute needs to be hidden this option should be used visibility="permissioned.hide_attribute". Example:

<VocabularyElement id="id:Company_Green_with_permissioned_data">
    <attribute id="id:wallet" visibility="permissioned.hide_attribute">0xBbAaAd7BD40602B78C0649032D2532dEFa23A4C0</attribute>
</VocabularyElement>

For more information on structuring XML EPCIS files, see XML EPCIS Examples

Verifiable credentials data model

What is a Verifiable Credential

If we look at the physical world, a credential might consist of:

  • Information related to identifying the subject of the credential (for example, a photo, name, or identification number)
  • Information related to the issuing authority (for example, a city government, national agency, or certification body)
  • Information related to the type of credential this is (for example, a Dutch passport, an American driving license, or a health insurance card)
  • Information related to specific attributes or properties being asserted by the issuing authority about the subject (for example, nationality, the classes of vehicle entitled to drive, or date of birth)
  • Evidence related to how the credential was derived
  • Information related to constraints on the credential (for example, expiration date, or terms of use).

A verifiable credential can represent all of the same information that a physical credential represents. The addition of technologies, such as digital signatures, makes verifiable credentials more tamper-evident and more trustworthy than their physical counterparts.

Verifiable credentials data can be placed inside generic OT-JSON object (OT-JSON Structure) with an additional identifier and can be queried using local knowledge graph querying system (Querying the data).

More detailed information about verifiable credentials can be found here:

https://www.w3.org/TR/vc-data-model/

OT-JSON Data Structure and Guidelines

Introduction and Motivation

In order to have a database and standard agnostic data structure, the protocol utilizes a generic data structure format called OT-JSON, based on JSON-LD. The guiding principles for OT-JSON development are:

  • 1-1 convertibility from/to higher level data formats (XML, JSON, CSV, … )
  • 1-1 convertibility from/to generic graph data structure.
  • Generic, use case agnostic graph representation
  • Extendable for future use cases of the protocol
  • Versionable format

OT-JSON essentials

An OT-JSON document represents a dataset as a graph of interconnected dataset objects (use case entities), such as actors, products, batches, etc. together with relations between them. Structure of dataset objects is generally defined, but extendable to support new use cases.

  • Objects - Use case entities (products, locations, vehicles, people, … )
  • Relations - Relations between use case entities (INSTANCE_OF, BELONGS_TO, … )
  • Metadata - Data about dataset (integrity hashes, data creator, signature, transpilation data, ….)

Example: Assuming that use case request is to connect products with factories there they are produced. Entities of the use case are Product and Producer. These entities are represented as objects in OT-JSON format. Product can have relation PRODUCED_BY with producer that produces it and the producer can have relation HAS_PRODUCED with the product. Product and producer have unique identifiers Product1, Producer1 respectively.

../_images/datalayer4.png

Figure 2. Diagram of the example entities and relations

{
    "@graph": [
        {
            "@id": "Product1",
            "@type": "OTObject",
            "identifiers": [
                {
                    "identifierType": "ean13",
                    "identifierValue": "0123456789123"
                }
            ],
            "properties": {
               "name": "Product 1",
               "quantity": {
                   "value": "0.5",
                   "unit": "l"
                }
            },
            "relations": [
                {
                    "@type": "OTRelation",
                    "linkedObject": {
                            "@id": "Producer1"
                        },
                    "properties": {
                            "relationType": "PRODUCED_BY"
                        }
                }
            ]
        },
        {
            "@id": "Producer1",
            "@type": "OTObject",
            "identifiers": [
                {
                    "identifierType": "sgln",
                    "identifierValue": "0123456789123"
                }
            ],
            "properties": {
               "name": "Factory 1",
               "geolocation": {
                   "lat": "44.123213",
                   "lon": "20.489383"
                }
            },
            "relations": [
                {
                    "@type": "OTRelation",
                    "linkedObject": {
                            "@id": "Product1"
                        },
                    "properties": {
                            "relationType": "HAS_PRODUCED"
                        }
                }
            ]
        }
    ]
}

Figure 3. OT-JSON graph representing example entities

Conceptual essentials

Here are some essential conceptual things related to the data in a dataset. Try to fit example of book as an object from the physical world with its information as the data.

  • Every OT-JSON entity (Object) is identified with at least one unique identifier. An identifier is represented as a non-empty string.
  • Entities can have multiple identifiers along with the unique one. For example: EAN13, LOT number and time of some event.
  • Data can be connected by arbitrary relations. A user can define own relations that can be used with others defined by standard.
  • Relations are directed from one entity to another. It is possible to create multiple relations between two objects in both directions.

For more specific information about OT-JSON, see OT-JSON Structure

Web of Things

WoT (Web of Things) provides mechanisms to formally describe IoT interfaces to allow IoT (Internet of Things) devices and services to communicate with each other, independent of their underlying implementation, and across multiple networking protocols. The OriginTrail node supports the WOT standard for importing and connecting data in the knowledge graph.

The goals of the WOT are to improve the interoperability and usability of the IoT. Through a collaboration involving many stakeholders over the past years, several building blocks have been identified that address these challenges. The first set of WoT building blocks is now defined:

  • the Web of Things (WoT) Thing Description
  • the Web of Things (WoT) Binding Templates
  • the Web of Things (WoT) Scripting API
  • the Web of Things (WoT) Security and Privacy Considerations

More details for defined building blocks and use cases are available on the following link: https://www.w3.org/TR/wot-architecture/

Data model is composed of the following resources:

  • Things – A web Thing can be a gateway to other devices that don’t have an internet connection. This resource contains all the web Things that are proxied by this web Thing. This is mainly used by clouds or gateways because they can proxy other devices.
  • Model – A web Thing always has a set of metadata that defines various aspects about it such as its name, description, or configurations.
  • Properties – A property is a variable of a web Thing. Properties represent the internal state of a web Thing. Clients can subscribe to properties to receive a notification message when specific conditions are met; for example, the value of one or more properties changed.
  • Actions – An action is a function offered by a web Thing. Clients can invoke a function on a web Thing by sending an action to the web Thing. Examples of actions are “open” or “close” for a garage door, “enable” or “disable” for a smoke alarm, and “scan” or “check in” for a bottle of soda or a place. The direction of an action is usually from the client to the web Thing. Actions represent the public interface of a web Thing and properties are the private parts.

All these resources are semantically described by simple models serialized in JSON. Resource findability is based Web Linking standard and semantic extensions using JSON-LD are supported. This allows extending basic descriptions using a well-known semantic format such as the GS1 Web Vocabulary. Using this approach, existing services like search engines can automatically get and understand what Things are and how to interact with them. An example of WOT file is available on the following link:

https://www.w3.org/TR/wot-thing-description/

How an event is represented in the graph

When converting a WOT file to graph, a central vertex will be created for the device described in the file. All sensor measurements will be created as separate vertices in the graph, connected to the main event vertex, in order to enable connection to the rest of the graph via the main vertex. There are two custom vertices denoted as readPoint and observerdLocation. These two vertices are considered as connectors which connect data with the rest of the graph. An example of WOT file with connectors is available on the following link: https://github.com/OriginTrail/ot-node/blob/develop/importers/use_cases/perutnina_kakaxi/kakaxi.wot