Overview

This guide walks you through implementing AIOSchema from scratch. By the end, you will be able to:

  1. Construct a valid AIOSchema manifest
  2. Compute hash_original for any file
  3. Derive core_fingerprint from the Core Block
  4. Verify a manifest against its source file

Prerequisites: Familiarity with JSON, SHA-256, and your language’s standard cryptography library.

Time estimate: 4–8 hours for a complete Level 1 implementation.

Step 1: Understand the Manifest Structure

An AIOSchema manifest is a JSON object with two top-level keys:

{
  "core": { ... },
  "extensions": { ... }
}

The Core Block contains the five architecturally frozen fields plus computed/derived fields. The Extensions Block is optional and carries additional metadata.

Step 2: Core Block Fields

Every manifest must include these five fields:

Field Type Description
asset_id UUID v7 string Unique identifier for the asset
schema_version string "0.5.5"
creation_timestamp ISO 8601 string UTC, must end with Z
hash_original string or array SHA-256 hash of the original file
creator_id string Identity fingerprint (e.g. ed25519-fp-...)

Step 3: Compute hash_original

Hash the raw bytes of the original file using SHA-256:

import hashlib

def compute_hash(file_bytes, algorithm="sha256"):
    h = hashlib.new(algorithm)
    h.update(file_bytes)
    return f"{algorithm}-{h.hexdigest()}"

The result is a prefixed string like sha256-a1b2c3d4....

Step 4: Canonical JSON

AIOSchema uses deterministic JSON serialization for all hash computations. The rules are simple:

  • Keys sorted alphabetically
  • No whitespace
  • UTF-8 encoding
  • No trailing commas

Step 5: Core Fingerprint

The core_fingerprint is computed by:

  1. Selecting the five Core Block fields (excluding core_fingerprint itself — the bootstrap rule)
  2. Serializing them as canonical JSON
  3. Hashing the resulting bytes with SHA-256

Step 6: Verification

To verify a manifest:

  1. Read the manifest JSON
  2. Read the original file bytes
  3. Recompute hash_original — compare
  4. Recompute core_fingerprint — compare
  5. If both match, the manifest is valid at Level 1

No keys. No network calls. No specialized tools.

Next Steps

Read the full specification → View conformance vectors →