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: public-credentials@w3.org (subscribe, archives)

Introduction

In streamlining operations and reacting to increasing expectations of market transparency and traceability, global supply chains are undergoing continuous digital transformation. At the same time, the surfaces exposed to cyber attacks are increasing. These vulnerabilities of critical society infrastructure are recognized by governments around the world, clearly described in this US Presidential Order:

The private sector must adapt to the continuously changing threat environment, ensure its products are built and operate securely, and partner with governments to foster a more secure cyberspace. In the end, the trust we place in our digital infrastructure should be proportional to [the trustworthiness and transparency of that infrastructure, and] to the consequences [that may be incurred] if that trust is misplaced.
Source: https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/

Similar recognition is seen in this Digital Strategy statement from the European Commission:

The digital transformation of society [...] has expanded the threat landscape and is bringing about new challenges, which require adapted and innovative responses. Now any disruption, even one initially confined to one entity or one sector, can have [more broad, cascading effects], potentially resulting in far-reaching and long-lasting negative impacts in the delivery of services across the whole internal market.
Source: https://digital-strategy.ec.europa.eu/en/library/proposal-directive-measures-high-common-level-cybersecurity-across-union

The goal of this specification is to provide a path towards a secure digitized global supply chain. It does so by leveraging modern cryptography and web technology standards like the Verifiable Credential Data Model (VCDM), JSON for Linked Data (JSON-LD), and Decentralized Identifiers (DIDs).

Supply Chain Digitization

While digitization has revolutionized other industries with decades of value, supply chain industries have been slow and fragmented in their digital transformation journey. The sheer number and variety of supply chain actors makes technological advances incredibly difficult. For example, physical paper, manual processing, and outdated technologies still support the vast majority of supply chain information flows. Paper processing costs the supply chain industry upwards of $3 billion every year (not counting the additional costs of paper, ink, and printing) (see "When Will Supply Chains Finally Move on From Paper?"). The resulting data silos and blind spots throughout the supply chain have created a crisis that enterprises and regulators can no longer ignore. This problem is made worse by the coordination challenges inherent in increasingly global supply chains.

As long as semantic standards depend on manual adoption and complex implementations, the impacts of these investments are limited and delayed. Semantic standards and code lists are being rigorously managed by various standards organizations. However, language barriers and differing contexts between standards is a major source of imprecision and errors. The fragmentary environment around different standard types, applications, and governing bodies only adds to the complexity involved in adoption and integration of standards.

The identity of supply chain actors is another problem resulting in costs and errors. While nations and platforms have established digital identity regimes within their boundaries, no useful global identity scheme has emerged or been adopted. Public policy, borders, and commercial obstacles create large barriers for a global centralized model to be adopted. The result is that most businesses need to invest heavily in IT infrastructure and middleware data mapping tools to be integrated with their trading partners. In fact, digitizing a major supply chain will cost tens of millions of dollars at the current pace and will be a 3-to-5 year transformation effort in the future (see "A Simpler Way to Modernize Your Supply Chain"). Today, most enterprises only have 20% visibility into their supply chains when they need about 70% to 90% visibility to properly monitor their investments (see "In 2020, Supply-Chain Digitization Is No Longer Optional"). This means a heavy investment of capital is required to achieve this visibility, which results in de-facto vendor software lock-in.

Establishing Trust

Trust and efficiency are fundamental to supply chains and global trade. Supply chains are a network of economically connected and collaborative stakeholders that includes shippers, carriers, importers, regulators, and other key actors. Traditionally, trust is established in the supply chain by analogue signed contracts, physical meetings, phone calls, faxes, and regular audits that prove credibility of the engaging parties and compliance with relevant regulation. Digitization efforts in the sphere of “contractual trust” have been limited by challenges like altering digital data such as PDFs, which is both easy to do and difficult to detect. Some noteworthy steps have been taken to address this such as encrypted communication channels like HTTP-over-TLS (a/k/a HTTPS) and commercial digital signature platforms (i.e. Docusign). However, a trusted channel does not prevent data alteration by either party and globally scaling a proprietary platform is expensive and comes with political and practical implications.

This landscape has changed with the advent of the VC standard. This standard makes digital contractual trust accessible and affordable for anyone on the planet. VCs work by applying existing cryptographic standards (particularly modern curve-based digital signature algorithms) to business data that is typically exchanged over APIs or XML. The VC specification provides a data model for how data paired with a cryptographic signature should be represented in a data file. The data itself can be anything; it can describe a shipment, an organization, a product, an agreement, etc. The cryptographic signature ensures that anyone with the VC can verify that the data is how the issuer intended it to be. In other words, the VC standard enables the use of cryptographic standards and provides the verifier a sense of trust when presented with the data file from the issuer. The implications of this technology for global supply chains are far-reaching.

However, there remains a great deal of untapped potential from VCs. Trust can be established remotely and fully automated provided that suitable claims are presented and issued by a trustworthy third party such as an existing business partner, a commercial agent, or a government. "Chains of trust" can be established by linking back through relevant claims to a known trust anchor. As you can see, VCs have a great deal of potential in the future of supply chain technology.

Linked Semantics

Supply chain organizations use different words to say the same thing. For example, “Shipper” and “Consignor” are used interchangeably in shipping. Ensuring precise communication across supply chain participants given these varying vocabularies is challenging. For example, standards bodies govern semantic models with term definitions, APIs for common use cases, and code lists in an attempt to avoid ambiguity. The traditional challenge for these technical publications has been the human element: reading the spec, interpreting the API attribute name, or skimming through the code lists. This labor is required because the data sender and the data receiver have to establish the same understanding. This results in effort and IT costs for both the sender and receiver to ensure they’re communicating unambiguously.

Linked Data addresses this problem by letting computers establish semantic meaning. Leveraging how the web works, Linked Data explicitly ties terms to a precise Uniform Resource Identifier (URI). Much like a URL pointing at a specific website, a URI defines a specific term. Thus, when the data sender defines a term by pointing at a URI, no interpretation is needed and a computer can automatically understand it. Beyond the obvious benefit of establishing shared understanding, integrating Linked Data is simpler and more cost-effective than data interpretation and mapping.

Linked Data is not new. It drives internet indexing and search engines. This traceability-vocab specification simply introduces this technology for use in the supply chain industry. All of the schemas which define the data content of Verifiable Credentials are constructed with explicit pointers to the most relevant URIs of the terms used. Existing term definitions, which are available in online vocabularies, can be used to construct the Verifiable Credential schemas.

Global Identifiers

A final important part of modernizing the digital supply chain is targeting the problem of identification. The difficulty of scaling centralized solutions has led to the emergence of Decentralized Identifiers (DIDs). DIDs rely on cryptography to prove that you are in control of a given identity. A variety of different types of DIDs exist and apply to different use-cases, like short-term DIDs or long-term, enterprise, security-grade DIDs. A DID is trustless, meaning that anyone can make and control a DID at any time. The value and credibility of a DID comes from its relationship with credentials that are tied to it. These credentials are typically issued by third-party organizations and/or governments.

While the identification of supply chain parties is a major identity problem, DIDs also provide value in other contexts. DIDs can be used to represent products, shipments, contractual agreements, or anything else in the supply chain that would benefit from the properties of DIDs. When paired with DIDs representing supply chain actors, DIDs that represent supply chain products or shipments stand to offer an ever more granular snapshot of the supply chain.

Note that the traceability-vocab's use of Decentralized Identifiers is limited to example uses. Traditional means of identification can also be used, but use of DIDs is encouraged to ensure that actual control of an identity can be proven.

Technology Summary

This section describes the emerging technology standards of Verifiable Credentials, Linked Data, and Decentralized Identifiers with a real-world supply chain use case.

The Commercial Invoice is a critical supply chain document that is essential to Customs who use it for duty determination and other tasks. This document includes data such as the description of the goods, where the goods are being shipped to and from, and the value of the goods. This document is supplied by the shipper.

The Commercial Invoice document is typically exchanged via PDF, email, or EDI. With the use of Verifiable Credential technology, we are able to digitize a Commercial Invoice into a verifiable Commercial Invoice credential. Each data point on the Commercial Invoice VC is mapped to a semantic model for common definition using Linked Data. For example, the “Consignee” field or the “Shipper” field on the Commercial Invoice are defined unambiguously to precise URIs. This promotes a singular, common definition of the data labels so that organizations have a shared understanding.

In addition, certain data points on the Commercial Invoice are used to identify an organization. For example, the “Consignee” field identifies the receiver of the goods and the “Shipper” field identifies the shipper of the goods. In this example, both the consignee and shipper would be organizations. Using a Decentralized Identifier (DID), for example, the consignee organization can self-authenticate as the receiver of the goods.

The Shipper’s Decentralized Identifier is included as the Verifiable Credential issuer, binding the claims on the Commercial Invoice back to the Shipper. Cryptographic traceability of the Commercial Invoice is thus established from the Shipper to the Consignee. Anyone presented with the Commercial Invoice can verify that it originates from the Shipper and is targeted to the Consignee.

This example portrays a specific use case with a Commercial Invoice and shows how Verifiable Credentials, Linked Data, and Decentralized Identifiers apply. We apply these technologies to common trade documents to further digitize documents and promote trust throughout the entire supply chain.

Vocabulary

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 mprorock@mesur.io
E-Commerce Nis Jespersen nis@transmute.industries
Oil and Gas Mahmoud Alkhraishi mahmoud@mavennet.com
Software Supply Chain Benjamin Collins benjamin@transmute.industries
Steel and Metals Orie Steele orie@transmute.industries

Vocabulary Linkage

The traceability-vocab ensures that coherent sets of use case-specific schemas, blended together with corresponding resolvable @context data, point all the schemas' terms to their defining URIs. These URIs will generally point at existing, established vocabularies. Only when no applicable vocabularies can be found are terms defined as part of the traceability-vocab spec; these are considered exceptional cases.

In determining the most applicable vocabulary for a particular term, the most generic and widely adopted vocabulary is chosen. For example, a common term defined in schema.org will be chosen over a similar term defined in a industry-specific vocabulary. This is to ensure the broadest possible interoperability, within and beyond supply chain.

Open API

This vocabulary can also be viewed as an Open API Specification.

See w3id.org/traceability/interoperability for REST API and interoperability tests associated with this vocabulary.

Undefined Terms

This vocabulary uses '@vocab': 'https://www.w3.org/ns/credentials/issuer-dependent#' to disable JSON-LD related errors associated with Verifiable Credentials, issued about terms that have not yet been added here.

Issuers are advised to review the JSON-LD and all associated terms before issuing verifiable credentials.

Use Cases

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).

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.

E-Commerce

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.

Software Supply Chain

Modern physical supply chains are heavily dependent upon software supply chains. As such, being able to secure digital services has become a requirement for securing physical ones.

As with physical supply chains, customers demand vendors to take responsibility and prove the provenance of software products and platforms. Beyond organizations securing their supply chains, the digital supply chain has become an issue of national security. Notably, this led to the May 21st, 2021 US President Executive Order of enhancing software supply chain security, outlining minimum software traceability requirements.

One approach for increased visibility and accountability in software is to provide a Software Bill of Materials which allows consumers to understand what is in the software, much like how food ingredients are labeled. Software is widely built from open source and other types of components, and the Software Bill of Materials document lists all such dependencies, providing a detailed and accurate understanding of organizations' software infrastructure. This is key for remediating software vulnerability exposure and assessment of software licensing compliance.

Including the Software Bill of Materials in a Verifiable Credential establishes a verifiable link from the software back to its origin.

Supporting Documents
Mill Test Report Certificate
Mill Test Report example
Sample Mill Test Report

The Mill Test Report certifies metal type and quality, listing chemical and mechanical properties.

Commercial Invoice Certificate
Commercial Invoice example
Sample Commercial Invoice

Commercial Invoice indicates to authorities the value of goods subject to tariffs and duties.

Bill of Lading Certificate
Bill of Lading example
Sample Bill of Lading

Bill of Lading certificates are issued by the carrier, indicating a) receipt of goods, b) evidence of consignment contract, and c) title of goods.

Verifiable Business Card

Verifiable Business Cards hold verifiable presentation endpoint addresses.

USMCA Certificate Of Origin
USMCA Certificate Of Origin
USMCA Certificate Of Origin

The USMCA Certificate Of Origin schema is adapted from FedEx's and UPS's USMCA Forms, implementing the United States - Mexico - Canada Agreement (USMCA).

Purchase Order
Purchase Order example
Sample Purchase Order
Sample Purchase Order form
Sample Purchase Order form

The Purchase Order is a formal request of goods by buyer to seller.

Packing List
Packing List example
Packing List example
Sample Packing List form
Sample Packing List form

The Packing List lists the goods of a shipment. It is used by the consignee and Customs to practically manage and organize the consgned goods.

Waybill
Sample Air Waybill form
Sample Air Waybill form

A Waybill is a transport document issued by the carrier. It serves a similar purpose as a Bill of Lading, except that it does not carry title. Instead, the consignee is identified on the document.

Proforma Invoice
Sample Proforma Invoice form
Sample Proforma Invoice form

The Proforma Invoice is a sample invoice provided by an exporter prior to a sale.

Commercial Invoice
Commercial Invoice example
Sample Commercial Invoice

An Invoice requests payment for a shipment of goods. It is based on the same schema as the Commercial Invoice, but is typically at a finer level of details, line items corresponding to the Purchase Order.

Importer Security Filing form
Sample Importer Security Filing form

The Importer Security Filing, commonly referred to as "10+2" is a requirement for import containerized cargo into the United States.

Extensions to Standard

Supported media types

This profile supports the following media types.

  • application/vc+ld+json
  • application/vp+ld+json
  • application/vc+ld+jwt
  • application/vp+ld+jwt

Verifiable Credential

The object MUST conform to the basic requirements section of the W3C VC Data Model.

It is RECOMMENDED the id be a valid URN, for example urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5

Verifiable Presentation

The object MUST conform to the basic requirements section of the W3C VC Data Model.

Traceable Presentation

This object extends VerifiablePresentation to support workflows.

The @context MUST contain "https://w3id.org/traceability/v1".

The object MUST have an id property.

The id MUST be a UUID v4 URN per [[rfc4122]], for example, urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5.

Workflow

Workflows enable correlation of multiple Traceable Presentations, made at different points in time and between different holders and verifiers.

A TraceablePresentation MAY specify a workflow.

A workflow MAY reference one or more WorkflowDefinitions to indicate the intention of the presentation.

A workflow MAY reference one or more WorkflowInstances to correlate multiple TraceablePresentations.

When a Workflow references both Definition(s) and Instance(s), the Workflow Instance's progress MAY be tracked by comparing the credentials which have been presented within the Workflow Instance (numerator) against the combined set of credentials types required by the targeted Workflow Definitions (denominator).

Workflow Definition

The sequence of industrial, administrative, or other processes through which a piece of work passes from initiation to completion, or the type of workflow that the presented credentials belong to.

In the context of this vocabulary, we consider the specifics of workflows out of scope. We acknowledge that different use cases may have complicated workflows, which may yield many individual presentations of credentials.

A Workflow Definition MUST be identified with an [[rfc3986]] conformant URI, for example, https://w3id.org/traceability#us-cbp-entry.

By referencing a Workflow Definition `id` in a Traceable Presentation, the holder indicates to the verifier their intent to make the presentation.

The Workflow Definition SHOULD resolve to a manifest file describing the intent to complete the workflow, participating parties, and required credential types. For example, https://w3id.org/traceability#us-cbp-entry indicates that an Importer intends to import goods following common US CBP Entry filings.

There are several systems for workflow definitions. See BPMN, YAWL, and/or GitHub Workflows.

Multiple Workflow Definitions MAY be referenced by a Traceable Presentation, indicating that multiple relevant circumstances apply.

We enable the grouping of all presentations related to a definition, using the convention:

                {
                  "@context": [
                    "https://www.w3.org/2018/credentials/v1",
                    "https://w3id.org/traceability/v1"
                  ],
                  "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
                  "type":
                  [
                    "VerifiablePresentation",
                    "TraceablePresentation"
                  ],
                  "workflow": {
                    // This refers to a Workflow Definition
                    "definition": [
                      "https://w3id.org/traceability#us-cbp-entry" 
                    ],
                    "instance": [
                      "urn:uuid:f5fb6ce4-b0b1-41b8-89b0-331ni58b7ee0"
                    ],
                  },
                  "holder":{
                    "id":"did:web:sender.example",
                    "type":"Organization",
                    "location":{
                       "type":"Place",
                       "geo":{
                          "type":"GeoCoordinates",
                          "latitude":"68.7083",
                          "longitude":"4.6377"
                       },
                       "address":{
                          "type":"PostalAddress",
                          "organizationName":"Ratke - Bergstrom",
                          "streetAddress":"21851 Ima Heights",
                          "addressLocality":"O'Connellborough",
                          "addressRegion":"Missouri",
                          "postalCode":"65587",
                          "addressCountry":"Cyprus"
                       }
                    }
                 }
                }
                
Workflow Instance

Each defined workflow may be executed many times for different sets of inputs and among different stakeholders.

We refer to Workflow Instance's as an execution of a particular workflow, which may or may not be formally defined.

A Workflow Instance MUST be identified with a UUID v4 per [[rfc4122]], for example, urn:uuid:f5fb6ce4-b0b1-41b8-89b0-331ni58b7ee0.

By referencing the same Workflow Instance `id` in separate Traceable Presentations, the holder indicates to the verifier that the presentations are related.

For example, an initial presentation of an Intent to Import Credential may be followed at a later date by presentation of a Commercial Invoice Credential. The two presentations reference a common Workflow Instance identifier to indicate that they relate to the same shipment import.

An example of a workflow definition is US Customs ACE Entry Summary Process. Where specific instances are used to track cross border imports, it is important to be able to identify specific collections of documents associated with a given import. Workflow instances help achieve this by providing a topic identifier enabling the grouping of related credentials and presentations.

The same Traceable Presentation MAY reference multiple Workflow Instances. This is a signal by the holder that the referenced Workflow Instances are the same and should be joined.

We enable the grouping of all presentations related to an instance, using the convention:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/traceability/v1"
  ],
  "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "type":
  [
    "VerifiablePresentation",
    "TraceablePresentation"
  ],
  "workflow": {
    "definition": [
      "https://w3id.org/traceability#us-cbp-entry"
    ],
    // This refers to a Workflow Instance
    "instance": [
      "urn:uuid:f5fb6ce4-b0b1-41b8-89b0-331ni58b7ee0"
    ]
  },
  "holder":{
    "id":"did:web:sender.example",
    "type":"Organization",
    "location":{
        "type":"Place",
        "geo":{
          "type":"GeoCoordinates",
          "latitude":"68.7083",
          "longitude":"4.6377"
        },
        "address":{
          "type":"PostalAddress",
          "organizationName":"Ratke - Bergstrom",
          "streetAddress":"21851 Ima Heights",
          "addressLocality":"O'Connellborough",
          "addressRegion":"Missouri",
          "postalCode":"65587",
          "addressCountry":"Cyprus"
        }
    }
  }
}

Presentation Replacement

A holder MAY use the replace property of a TraceablePresentation to communciate to a verifier that a previous presentation should be replaced with a new presentation.

Holders SHOULD ensure the previous presentation was accepted before presenting a replace presentation.

The presentation id of the replace presentation MUST be unique, and MUST NOT be the same as any previously presented values.

The credential id of any corrected credentials MUST be unique, and MUST NOT be the same as any previously presented values.

In the example below did:web:customs.broker.1.example had made a mistake in a previous presentation, and corrects the mistake with a replace presentation.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/traceability/v1"
  ],
  "id": "urn:uuid:p2",
  "type": [
    "VerifiablePresentation",
    "TraceablePresentation"
  ],
  "replace": {
    "id": "urn:uuid:p1",
    "note": "I made a mistake in my presentation 'urn:uuid:p1', the invoice number was incorrect, this presentation corrects the error."
  },
  "workflow": {
    "definition": [
      "urn:definition:customs-commodity-import-workflow-456"
    ],
    "instance": [
      "urn:instance:commodity-import-for-us-customs-123"
    ]
  },
  "holder": {
    "id": "did:web:customs.broker.1.example"
  },
  "verifiableCredential": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://w3id.org/traceability/v1"
      ],
      "id": "urn:uuid:c2",
      "type": [
        "VerifiableCredential"
      ],
      "invoice": "123xxxx"
    }
  ]
}
          

Considerations

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.

Appendix

Acknowledgements

Portions of the work on this specification have been funded by the United States Department of Homeland Security's (US DHS) Silicon Valley Innovation Program under contracts 70RSAT20T00000003, 70RSAT20T00000031, 70RSAT20T00000033, 70RSAT20T00000043, and 70RSAT20T00000044. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.

RDF Type Details