SMALL

The SMALL Protocol exposes a machine-readable API contract via OpenAPI 3.0. This enables agents and tools to discover, validate, and interact with SMALL primitives programmatically.

Specification

The OpenAPI specification is available at:

/openapi/small.v1.yaml

This file is served as a static asset and can be consumed by OpenAPI tooling, API clients, and documentation generators.

Endpoints

Protocol Discovery

http 
GET /protocol/small/v1

Returns the SMALL Protocol v1 contract, including:

  • Protocol name and version
  • Available primitives (Schema, Manifest, Artifact, Lineage, Lifecycle)
  • Protocol rules and guarantees
  • Schema locations for validation

Example Response:

json 
{
  "protocol": "SMALL",
  "version": "1.0.0",
  "primitives": ["Schema", "Manifest", "Artifact", "Lineage", "Lifecycle"],
  "rules": {
    "materializationRequiresValidation": true,
    "artifactsAreImmutable": true,
    "lineageIsAppendOnly": true,
    "lifecycleIsEventBased": true,
    "explicitContractsOnly": true
  },
  "schemas": {
    "schema": "/schemas/small/v1/schema.schema.json",
    "manifest": "/schemas/small/v1/manifest.schema.json",
    "artifact": "/schemas/small/v1/artifact.schema.json",
    "lineage": "/schemas/small/v1/lineage.schema.json",
    "lifecycle": "/schemas/small/v1/lifecycle.schema.json"
  }
}

Schema Access

http 
GET /schemas/small/v1/{schemaName}

Returns the JSON Schema for a SMALL primitive. Valid schema names:

  • schema - Schema registry item schema
  • manifest - Manifest schema
  • artifact - Artifact schema
  • lineage - Lineage schema
  • lifecycle - Lifecycle schema

Example:

bash 
curl http://localhost:5173/schemas/small/v1/manifest.schema.json

Manifest Validation

http 
POST /small/v1/validate-manifest

Validates a manifest against the SMALL manifest schema. Returns validation result and replay ID if valid.

Request Body:

json 
{
  "protocolVersion": "1.0.0",
  "manifest": {
    "artifact": "track.audio",
    "schema": "artifact.v1",
    "version": 1
  }
}

Response:

json 
{
  "valid": true,
  "replayId": "abc123...",
  "errors": []
}

Example:

bash 
curl -X POST http://localhost:5173/small/v1/validate-manifest \
  -H "Content-Type: application/json" \
  -d '{
    "protocolVersion": "1.0.0",
    "manifest": {
      "artifact": "track.audio",
      "schema": "artifact.v1",
      "version": 1
    }
  }'

Replay Workflow

http 
POST /small/v1/replay

Validates a manifest and generates lineage + lifecycle records. Returns deterministic replay ID, validation result, and generated records.

Request Body:

json 
{
  "protocolVersion": "1.0.0",
  "manifest": {
    "artifact": "track.audio",
    "schema": "artifact.v1",
    "version": 1
  }
}

Response:

json 
{
  "replayId": "abc123...",
  "valid": true,
  "lineage": {
    "artifact": "track.audio",
    "derivedFrom": "artifact.v1",
    "generatedAt": "2024-01-01T00:00:00Z",
    "replayId": "abc123..."
  },
  "lifecycle": [
    {
      "type": "validated",
      "at": "2024-01-01T00:00:00Z",
      "replayId": "abc123..."
    },
    {
      "type": "materialized",
      "at": "2024-01-01T00:00:00Z",
      "replayId": "abc123..."
    }
  ]
}

Example:

bash 
curl -X POST http://localhost:5173/small/v1/replay \
  -H "Content-Type: application/json" \
  -d '{
    "protocolVersion": "1.0.0",
    "manifest": {
      "artifact": "track.audio",
      "schema": "artifact.v1",
      "version": 1
    }
  }'

Deterministic Replay

All SMALL operations are deterministic. Given the same manifest and protocol version:

  • Validation produces the same result
  • Replay ID is identical
  • Lineage records are identical
  • Lifecycle events are identical

This enables reproducible agent workflows and reliable automation.

Replay ID Computation

The replay ID is computed as:

text 
sha256("SMALL|" + protocolVersion + "|" + canonicalJson(manifest))

Where:

  • protocolVersion is the SMALL protocol version (e.g., "1.0.0")
  • canonicalJson(manifest) is a deterministic JSON serialization with sorted keys
  • The hash is base64url-encoded

This ensures:

  • Same manifest + same protocol version → same replay ID
  • Different protocol version → different replay ID
  • Different manifest → different replay ID

Integration

OpenAPI Tooling

The OpenAPI specification can be used with standard tooling:

  • Swagger UI: Visual API explorer
  • Postman: Import and test endpoints
  • Code Generation: Generate client SDKs
  • API Testing: Automated test generation

Agent Integration

Agents can integrate with SMALL by:

  1. Discovering the protocol via GET /protocol/small/v1
  2. Fetching schemas from /schemas/small/v1/{schemaName}
  3. Validating manifests before materialization
  4. Replaying workflows to generate lineage and lifecycle records
  5. Operating within the protocol's deterministic guarantees

Versioning

SMALL follows semantic versioning (Major.Minor.Patch):

  • Major: Breaking changes requiring agent updates
  • Minor: Backward-compatible additions
  • Patch: Bug fixes and clarifications

The current version is 1.0.0.