Skip to content

UID Document Schema Service

The UidDocumentSchema module provides utilities to create, store, and fetch UID Document Schemas on the IDCHAIN blockchain. Schemas are reusable definitions (similar to JSON Schemas) that standardize credential structures for issuance and verification.

Overview

This service allows developers to:

  • Generate reusable schemas (e.g., National ID, certificates).
  • Store schemas on-chain so they can be referenced by multiple issuers.
  • Fetch schemas from the blockchain for validation or reuse.

Schemas define the structure of credential subjects to ensure consistency and interoperability across dApps.

API Reference

Store Schema

UidDocumentSchema.storeSchema(verifierAccount, verifierDid, uidDocument): Promise<IUidDocument>

Stores a new UID Document Schema on the blockchain. If the schema already exists, the method will skip creation and return the existing schema.

Parameters:

  • verifierAccount (UidKeyringPair): The blockchain account authorized to submit the schema transaction.
  • verifierDid (Uid): The DID URI of the verifier (schema owner).
  • uidDocument (IUidDocument): The schema object, typically created with fromProperties or a helper function (like generateSchema).

Returns:

  • IUidDocument: The schema stored or fetched from the chain.

Fetch UidDocument

UidDocumentSchema.fetchUidDocument(uidDocumentId): Promise<IUidDocumentDetails>

Fetches a UID Document Schema from the blockchain by its ID.

Parameters:

  • uidDocumentId (string): The unique schema ID. Example format: uid:document:0x329a2a5861ea63c250763e5e4c4d4a18fe4470a31e541365c7fb831e5432b940

Returns:

  • IUidDocumentDetails: Object containing:
  • uidDocument: The schema content.
  • metadata: On-chain metadata (version, timestamps, etc.).

Generate Schema

generateSchema(schemaName: string, fields: Record<string, { type: string }>, version: "V1" | string): IUidDocument

Utility function (example) to quickly generate a UID Document Schema. This is not part of the core module but is a recommended pattern for projects.

Parameters:

  • schemaName (string): A human-readable schema title.
  • fields (object): Field definitions with type annotations (string, number, etc.).
  • version (string): Schema version (typically "V1").

Returns:

  • IUidDocument: A ready-to-use UID Document Schema object.

Example

import { fromProperties, IUidDocument } from "@idchain-sdk";

function generateKTPSchema(): IUidDocument {
  console.log("⚙️  Creating KTP Schema...");
  const uidDocument = fromProperties(
    "KTP Schema",
    {
      NIK: { type: "string" },
      Nama: { type: "string" },
      TTL: { type: "string" },
      status: { type: "string" },
    },
    "V1"
  );
  console.log("✅ Schema generated");
  return uidDocument;
}

// Usage
const schema = generateKTPSchema();
await UidDocumentSchema.storeSchema(attesterAccount, attesterDid.uri, schema);

Full Usage Example

import {
  connect,
  disconnect,
  fromProperties,
  UidDocumentSchema,
  IUidDocument,
} from "@id-chain";

// Helper: Generate a standardized KTP schema
function generateKTPSchema(): IUidDocument {
  console.log("⚙️  Creating KTP Schema...");
  const uidDocument = fromProperties(
    "KTP Schema",
    {
      NIK: { type: "string" },
      Nama: { type: "string" },
      TTL: { type: "string" },
      status: { type: "string" },
    },
    "V1"
  );
  console.log("✅ Schema generated");
  return uidDocument;
}

async function manageSchemas() {
  await connect(process.env.WSS_ADDRESS as string);

  // Step 1: Generate schema
  const schema = generateKTPSchema();

  // Step 2: Store schema on-chain (for an attester DID)
  const storedSchema = await UidDocumentSchema.storeSchema(
    attesterAccount,
    attesterDid.uri,
    schema
  );
  console.log("Stored schema ID:", storedSchema.$id);

  // Step 3: Fetch schema from blockchain
  const fetched = await UidDocumentSchema.fetchUidDocument(storedSchema.$id);
  console.log("Fetched UID Document Schema:", JSON.stringify(fetched, null, 2));

  await disconnect();
}

manageSchemas();

Error Handling

  • Missing DID: Throws "Could not resolve DID" if the verifierDid cannot be resolved.
  • Invalid Schema: Will throw during storage if validation or encoding fails.
  • Network Errors: Blockchain connection failures will cause fetch and store operations to reject.