@trustvc/w3c-context

TrustVC W3C Context

A comprehensive package that caches commonly used JSON-LD context schemas for W3C Verifiable Credentials and Data Integrity proofs. This package provides a document loader that resolves context URLs locally, improving performance and reliability for verifiable credential operations.

Features

• Local Context Caching: Pre-cached JSON-LD contexts for faster resolution
• W3C Standards Support: Full support for W3C Verifiable Credentials and Data Integrity specifications
• Cryptosuite Support: Includes contexts for multiple cryptographic suites:
  • BBS+ signatures (bbs-v1)
  • JWS 2020 (jws-2020)
  • BLS12-381 keys
• DID Resolution: Built-in support for DID document resolution
• Custom Context Support: Ability to add additional contexts at runtime
• TypeScript Support: Full TypeScript definitions included

Installation

npm install @trustvc/w3c-context

Usage

Basic Document Loader

import { getDocumentLoader } from '@trustvc/w3c-context';

// Get a document loader with all cached contexts
const documentLoader = await getDocumentLoader();

// Use with jsonld-signatures or other JSON-LD libraries
const result = await documentLoader('https://w3id.org/security/data-integrity/v2');

With Additional Contexts

import { getDocumentLoader } from '@trustvc/w3c-context';

// Add custom contexts
const additionalContexts = {
  'https://example.com/my-context': {
    "@context": {
      "MyProperty": "https://example.com/vocab#MyProperty"
    }
  }
};

const documentLoader = await getDocumentLoader(additionalContexts);

Available Context URLs

The package includes the following pre-cached contexts:

Core W3C Contexts

• https://w3id.org/security/data-integrity/v2 - Data Integrity v2
• https://www.w3.org/ns/did/v1 - DID Core v1
• https://www.w3.org/2018/credentials/v1 - Verifiable Credentials v1
• https://www.w3.org/ns/credentials/v2 - Verifiable Credentials v2
• https://w3id.org/vc/status-list/2021/v1 - Status List 2021 v1

Cryptographic Suite Contexts

• https://w3id.org/security/bbs/v1 - BBS+ v1
• https://w3id.org/security/suites/bls12381-2020/v1 - BLS12-381 2020
• https://w3id.org/security/suites/jws-2020/v1 - JWS 2020

TrustVC Business Contexts

• https://trustvc.io/context/transferable-records-context.json - Transferable Records

• https://trustvc.io/context/obligation-records-context.json - Obligation Records (BoE)

• https://trustvc.io/context/render-method-context.json - Render Methods

• https://trustvc.io/context/render-method-context-v2.json - Render Methods v2

• https://trustvc.io/context/attachments-context.json - Attachments

• https://trustvc.io/context/qrcode-context.json - QR Code

• https://trustvc.io/context/opencerts-context.json - OpenCerts Certificate

• https://trustvc.io/context/bill-of-exchange.json - Bill of Exchange

• https://trustvc.io/context/bill-of-lading.json - Bill of Lading

• https://trustvc.io/context/bill-of-lading-carrier.json - Bill of Lading Carrier

• https://trustvc.io/context/coo.json - Certificate of Origin

• https://trustvc.io/context/invoice.json - Invoice

• https://trustvc.io/context/promissory-note.json - Promissory Note

• https://trustvc.io/context/warehouse-receipt.json - Warehouse Receipt

Samples

• samples/obligation-credential-subject.sample.json - Example Obligation / BoE credential subject payload
• samples/bill-of-exchange.md - Form label → property map for finalized BoE fields

Context Constants

You can import URL constants for type safety:

import { 
  DATA_INTEGRITY_V2_URL,
  MULTIKEY_V1_URL,
  VC_V1_URL
} from '@trustvc/w3c-context';

console.log(DATA_INTEGRITY_V2_URL); // https://w3id.org/security/data-integrity/v2
console.log(MULTIKEY_V1_URL); // https://w3id.org/security/multikey/v1

Using Modern Cryptosuites

For BBS-2023 and ECDSA-SD-2023, use the Data Integrity context:

import { DATA_INTEGRITY_V2_URL, VC_V1_URL } from '@trustvc/w3c-context';

// Create a credential with BBS-2023 or ECDSA-SD-2023
const credential = {
  "@context": [
    VC_V1_URL,
    DATA_INTEGRITY_V2_URL  // Supports BBS-2023, ECDSA-SD-2023
  ],
  "type": ["VerifiableCredential"],
  "credentialSubject": {
    // ... credential data
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "bbs-2023", // or "ecdsa-sd-2023"
    // ... proof data
  }
};

DID Resolution

The document loader automatically resolves DID URLs:

const documentLoader = await getDocumentLoader();

// Resolves DID document
const didDoc = await documentLoader('did:web:example.com');

// Resolves specific verification method
const verificationMethod = await documentLoader('did:web:example.com#key-1');

API Reference

getDocumentLoader(additionalContexts?)

Creates a document loader function that resolves JSON-LD contexts.

Parameters:

• additionalContexts (optional): Record<string, Document> - Additional contexts to include

Returns: Promise - A document loader function

Context Categories

The package organizes contexts into several categories:

• contexts - Core W3C and cryptographic contexts
• trContexts - Transferable records contexts
• renderContexts - Rendering method contexts
• attachmentsContexts - Attachment contexts
• qrCodeContexts - QR code contexts
• templateContexts - Business document templates

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.