---
title: "Trust Block Schema"
description: "
"
url: https://instituteofprovenance.org/docs/trust-block-schema
source: Institute of Provenance
---
# Trust Block Schema

The trust block is the core data structure embedded in every XION artifact. It contains everything needed to verify the artifact's authenticity, integrity, and provenance without external lookups.

## Schema Definition

```json
{
  "v": 1,
  "sig_alg": "ed25519",
  "hash_blake3_hex": "cd9f70ec3a4ef5a0b3c8d2f1e6a9b4d7...",
  "sig_b64": "B42QjM2R...",
  "key_id": "UA4xFIgM...",
  "x509_chain_pem": [
    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  ],
  "created_at": "2026-02-12T18:20:27Z"
}
```

## Field Specifications

### `v` — Schema Version

- **Type:** integer
- **Required:** yes
- **Current value:** `1`
- **Purpose:** Enables forward-compatible schema evolution. Verifiers MUST reject trust blocks with unrecognized version numbers rather than attempting partial validation.

### `sig_alg` — Signature Algorithm

- **Type:** string
- **Required:** yes
- **Allowed values:** `"ed25519"`
- **Purpose:** Identifies the digital signature algorithm used. Currently only Ed25519 is specified. Future versions may add additional algorithms via new version numbers.

### `hash_blake3_hex` — Content Hash

- **Type:** string (hex-encoded, 64 characters)
- **Required:** yes
- **Purpose:** The BLAKE3 hash of the canonicalized content, encoded as lowercase hexadecimal. This is the value that is signed. BLAKE3 was chosen for its speed (3x faster than SHA-256), security margin (based on the BLAKE2/ChaCha family), and 256-bit output.

### `sig_b64` — Digital Signature

- **Type:** string (base64-encoded, 88 characters)
- **Required:** yes
- **Purpose:** The Ed25519 signature computed over the raw bytes of `hash_blake3_hex` (the hex string itself, UTF-8 encoded). The signature is produced using the private key corresponding to the leaf certificate in the chain.

### `key_id` — Public Key Identifier

- **Type:** string (base64url-encoded, 11 characters)
- **Required:** yes
- **Derivation:** First 8 bytes of SHA-256(public_key_bytes), base64url-encoded without padding.
- **Purpose:** Allows efficient key lookup without parsing the full certificate chain. Verifiers SHOULD use this as a hint but MUST validate against the actual public key in the leaf certificate.

### `x509_chain_pem` — Certificate Chain

- **Type:** array of strings (PEM-encoded X.509 certificates)
- **Required:** yes
- **Ordering:** Leaf certificate first, followed by each issuer up to (but not including) the root CA
- **Purpose:** The full certificate chain enables offline verification. The verifier traces the chain from the leaf certificate to a known root CA public key.
- **Constraints:**
  - The chain MUST contain at least 2 certificates (leaf + intermediate)
  - The leaf certificate MUST contain the public key that corresponds to `sig_b64`
  - Each certificate MUST be signed by the next certificate in the chain
  - The last certificate in the chain MUST be signed by the Root CA

### `created_at` — Signing Timestamp

- **Type:** string (ISO 8601 format, UTC)
- **Required:** yes
- **Purpose:** Records when the content was signed. Used during temporal validity checks — the leaf certificate must have been valid at this timestamp.
- **Precision:** Seconds. Fractional seconds are permitted but not required.

## Validation Rules

A trust block is valid if and only if all of the following hold:

1. All required fields are present and correctly typed
2. `v` is a recognized schema version
3. `sig_alg` is a supported algorithm
4. `hash_blake3_hex` is exactly 64 lowercase hexadecimal characters
5. `sig_b64` is valid base64 encoding of exactly 64 bytes
6. `key_id` matches the derivation from the leaf certificate's public key
7. `x509_chain_pem` contains at least 2 valid PEM-encoded certificates
8. `created_at` is a valid ISO 8601 timestamp

Content-level verification (signature validity, chain integrity, revocation, temporal validity) is specified in [Verification Process](/docs/verification-process).

## Extensibility

The schema is versioned. Future versions may add fields, but existing fields will not be removed or have their semantics changed within the same major version. Verifiers encountering unknown fields SHOULD ignore them (forward compatibility).