Sprite Data Model & Schema

ELI5

A sprite is like a detailed résumé for an AI agent. It has a unique name (like SOL-FORGE), a version number, a job description (system_prompt), a list of skills (capabilities), and a cryptographic ID badge (fingerprint). Just like a résumé, it must follow strict formatting rules so every system can read it the same way.

Technical Deep Dive

Sprite JSON Schema (iris.schema.json)

A valid Sprite document must pass iris.schema.json (Draft 2020-12). It is one of three top-level types (mutually exclusive via oneOf with Sprite, Council, Chain).

Required Fields

Optional Fields

Class Diagram

classDiagram
    class Sprite {
        +UUID id
        +SpriteName name
        +Semver version
        +Role role
        +Capability[] capabilities
        +string system_prompt
        +SpriteMetadata metadata
        +Fingerprint fingerprint
        +UUID[] chains
        +TestCase[] tests
        +boolean protected
        +boolean gate_authority
        +from_file(path) Sprite
        +validate(strict) boolean
        +compute_fingerprint() HexHash
    }
    class Capability {
        +string name
        +string description
        +JSONSchema parameters
    }
    class SpriteMetadata {
        +string author
        +datetime created
        +datetime updated
        +string[] tags
    }
    class Fingerprint {
        +HashAlgorithm type
        +HexHash hash
    }
    class TestCase {
        +string name
        +object input
        +object expected_output
        +string[] tags
    }
    Sprite --> Capability : has
    Sprite --> SpriteMetadata : has
    Sprite --> Fingerprint : has
    Sprite --> TestCase : has

Sprite Role Hierarchy

Capability Structure

Each capability is a JSON Schema-described interface:

{
  "name": "generate_code",
  "description": "Generate production-ready code from a specification",
  "parameters": {
    "type": "object",
    "properties": {
      "language": { "type": "string", "enum": ["python", "typescript", "rust"] },
      "spec": { "type": "string", "minLength": 1 }
    },
    "required": ["language", "spec"]
  }
}

Packet Structure Diagram

packet-beta
  title Sprite Fingerprint Packet
  0-3: "algo"
  4-7: "ver"
  8-39: "hash_lo"
  40-71: "hash_hi"

The fingerprint format is blake3:{64-char-hex} or sha256:{64-char-hex}. The 64-character hex string represents a 256-bit digest.

Key Terms

• SpriteName → Strict uppercase pattern: ^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$. No lowercase, no underscores.
• Capability → A named skill with a JSON Schema parameter definition, declaring what a sprite can do
• Protected sprite → A sprite that cannot be bypassed in chain execution; requires ?force=true for deletion
• Gate authority → The single sprite per council with veto power over chain execution
• Fingerprint → Cryptographic identity hash computed via the 5-stage Blake3 canonical pipeline
• SemVer → Semantic Versioning 2.0.0; IRIS supports pre-release (1.0.0-alpha) and build metadata (1.0.0+build.123)

Q&A

Q: Why are sprite names uppercase with hyphens? A: The naming convention (SOL-FORGE, CORTEX-01) creates visual distinction from variables, file names, and standard identifiers. It also prevents accidental collisions with common words. The regex enforces machine-parseable uniformity.

Q: Can a sprite have zero capabilities? A: No. capabilities requires minItems: 1 in the JSON Schema. A sprite without capabilities would have no defined behaviour.

Q: What happens to the fingerprint when I update a sprite? A: The fingerprint is recomputed on every PUT. The server strips id, created, fingerprint fields from the canonical representation before hashing, so only semantic changes affect the hash.

Q: Can the system_prompt reference an external file? A: Yes. Use $ref: https://... or $ref: file:///... URIs. The server dereferences these before validation. The referenced content becomes part of the canonical representation for fingerprinting.

Examples

A sprite is like a skilled tradesperson’s union card:

• Name = Their registered trade name (SOL-FORGE like “Master Smith”)
• Version = Their certification level (1.0.0 = apprentice, 2.0.0 = journeyman, 3.0.0 = master)
• Capabilities = Their licensed skills (welding, plumbing, electrical)
• System prompt = Their professional code of conduct and specialty instructions
• Fingerprint = The union’s tamper-proof hologram on their card — proves it’s authentic