This repository will be versioned at periodic points in time with a Q1 Calendar Year target for major releases. Versioning tags will follow a pattern of `[MAJOR].[MINOR].[PATCH]`

Version Definitions:

As a rule, versioning will follow the specification outlined in the Semantic Versioning 2.0 spec This approach to versioning gives the ability to integrate with and provided automated testing and validation against defined types without worry of instability or breaking changes being introduced, while also limiting the frequency of possibly breaking changes to prevent a large number of incompatible versions.

To contribue to this vocabulary or reference technical details related to the project, please reference the primary README located on github

Please open an issue , if you wish to collaborate on this specification.

You may also reach out via the mailing list: (subscribe, archives)


This specification describes a Linked Data vocabulary for asserting Verifiable Credentials related to traceability information, such as chemical properties, mechanical properties, country of origin, and other attributes used to determine the status of a products and materials in a supply chain.

Generally, this vocabulary may be looked at as a set of common objects that are shared across multiple business verticals, and vertical or use case specific items that apply to one or more specific commodities or market segments. A primary goal of this specification is to standardize the creation of Verifiable Credentials from standardized JSON-LD which is itself created from JSON Schema definitions as would normally be passed of REST and other APIs. This promotes code re-use and establishes a pattern for the creation of JSON-LD and related Verifiable Credentials derived from those JSON-LD objects in a manner that is friendly to code and API development as well as to promote better interoperability between vendors who serve common or related markets.

The Vocabulary section covers each vocabulary item, its properties, other attributes, and provides and example Verifiable Credential for each item.

This repository has primary contributors from four main market segments, and has subject matter experts from those market segments delegated as leads for objects related to vocabulary items for each segment.
These subject matter leads help identify common elements across verticals as well as in assessing contributions of new objects to the vocabulary.

Market Segment Subject Matter Expert Contact
Agriculture Michael Prorock
E-Commerce Carsten Stöcker
Oil and Gas Mahmoud Alkhraishi
Steel and Metals Orie Steele

Use Cases and Requirements

The following use cases outline a number of key scenarios that readers might find useful in a variety of sectors, especially those that deal with cross border supply chain data interchange.

Steel and Metals

The global steel industry relies on cross-party communication of product and business information to successfully move materials from mines, to manufacturers, through customs, to end customers (such as automotive and construction companies). Today this information exists primarily in siloed paper documents. In the current format it is very difficult to make data comparisons across a small number of parties, let alone across millions of shipments over time. It can also be difficult to catch forged documents in the absence of digital signatures and clearly defined organization data attributes.

A shared vocabulary creates opportunities for steel trading partners to work from a common digital representation of trade information. Take the example of a mill report for a steel product. This document provides important information about the chemical make-up of steel materials, helping to ensure the desired specification and grade have been met. It also acts as evidence about the origins of steel materials. Unambiguous representation of mill report fields is critical for assessing appropriate duties, meeting customer requirements, and ultimately ensuring consumer safely.

By defining the schema for each field, importers can now answer questions like “How many pipes of specification XYZ did we purchase last year?” (i.e., ChemicalProperty). The mill report can also be linked to other trade documentation such as commercial invoices and bills of lading when those credentials are specified and defined. Regulators can also ask questions across a large number of mill reports to help catch transshipment issues, such as “How much steel product imported last month specified Vietnam as the country of origin?” (i.e., addressCountry).

Credentials of interest:

Food and Agriculture

Several use cases exist for common vocabulary in the food and agriculture space. Key priorities for this project revolve around items that are required for the safe and succesful importation of food to various countries.

The top level AgInspectionReport object has been created as a parent object that allows for the recording of the following inspections and audits, while giving flexibility to account for newly defined inspction types as needs change in the food and agricultre industry. This object can be sub-classed to allow for schema level validation of specific types of inspections and audits as required by the specifics of a given use case. Verifiable Credentials can be issued for this object or sub classes of this object to allow for external verification by third parties that are implementing the Verifiable Credentials sepcification

Farm GAP Inspection Report
Keep track of Good Agricultural Practices (GAP) audits and share results with a vendor
FSMA Inspection
Food Safety Modernization Act inspections and results for sharing with relevant parties, regulatory bodies and vendors.
Foreign Site Certificate of Inspection and/or Treatment
USDA APHIS PPQ FORM 203 that is required for pre-clearance of imported food and ag goods into the US
Oil and Gas

A common traceability vocabulary will enable creation of a common digital representation of an oil and gas assets and a variety of use cases. The main priority of this project is the border clearance and regulatory compliance use cases, that enable industry players to rely on the asset history, origin, and composition recorded as Verifiable credentials to be used in these processes.

The asset-specific CrudeOil VC (and NaturalGas VC) object serves as a root object that stores the key attributes of the asset as well as origin and composition. In addition to the asset VC, we are planning to represent key events in the asset’s lifecycle (inspection, transportation, transfer of ownership) as Verifiable Credentials.


A common traceability vocabulary will allow complex supply chains that import goods to US-resident customers to register individual packages and pre-register products intended for sale to the US with US Customs. For the data needs of Customs to be met by highly heterogenous supply chains that might require much "internal confidentiality" (between supply chain actors), a highly sharded data model is required, whereby many different actors can each submit data points separately that get combined at time of customs processing.

Without strong identification of legal entities (i.e., legally defined and registered supply chain actors) and of products, and without high levels of semantic flexibility, the shards can be quite hard to combine usefully. Linking the registration of individual packages together with the pre-registration of commercial products and actors is the key value-add of this system, but could also be a burdensome request on importers, retailers, and freight forwarders. To minimize this burden, we are aligning wherever possible with the ontology work of GS1 (GTINs and vLEIs), and with shipping and tracking semantics already adopted today by international logistics consortia. We distinguish between the VCs that are issued in relation to a specific package and the contextual information that needs to be queried to validate package information, as well as to make valuable assessments, inferences, and data quality remediation on Customs pre-entry data.


The following terms are used to describe concepts in this specification.

A thing with distinct and independent existence, such as a person, organization, or device that performs one or more roles in the ecosystem.
user agent
A program, such as a browser or other Web client, that mediates the communication between the various roles in this specification.
An identifier as defined by [[RFC3986]].

Privacy Considerations

This section details the general privacy considerations and specific privacy implications of deploying this specification into production environments.

Security Considerations

There are a number of security considerations that implementers should be aware of when processing data described by this specification. Ignoring or not understanding the implications of this section can result in security vulnerabilities.

While this section attempts to highlight a broad set of security considerations, it is not a complete list. Implementers are urged to seek the advice of security and cryptography professionals when implementing mission critical systems using the technology outlined in this specification.

Accessibility Considerations

There are a number of accessibility considerations implementers should be aware of when processing data described in this specification. As with any web standards or protocols implementation, ignoring accessibility issues makes this information unusable to a large subset of the population. It is important to follow accessibility guidelines and standards, such as [[WCAG21]], to ensure all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which have historically created problems for assistive technologies.

This section details the general accessibility considerations to take into account when utilizing this data model.

Internationalization Considerations

There are a number of internationalization considerations implementers should be aware of when publishing data described in this specification. As with any web standards or protocols implementation, ignoring internationalization makes it difficult for data to be produced and consumed across a disparate set of languages and societies, which would limit the applicability of the specification and significantly diminish its value as a standard.

This section outlines general internationalization considerations to take into account when utilizing this data model.