SMALL

Note: The .small/ file protocol is the primary SMALL contract. The hosted HTTP surface on smallprotocol.dev is intentionally narrower: protocol discovery plus published schema files. Hosted manifest validation and replay endpoints are not currently part of the live site contract.

The SMALL Protocol exposes a machine-readable OpenAPI 3.0 document for the public discovery surface. This allows tools and agents to discover protocol metadata and fetch versioned schema assets without guessing URLs.

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
  • Concrete schema URLs currently published by the site

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": {
    "intent": "/schemas/small/v1/intent.schema.json",
    "constraints": "/schemas/small/v1/constraints.schema.json",
    "plan": "/schemas/small/v1/plan.schema.json",
    "progress": "/schemas/small/v1/progress.schema.json",
    "handoff": "/schemas/small/v1/handoff.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 Files

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

Returns one of the published JSON Schema files served by the site. Supported filenames are:

  • intent.schema.json
  • constraints.schema.json
  • plan.schema.json
  • progress.schema.json
  • handoff.schema.json
  • manifest.schema.json
  • artifact.schema.json
  • lineage.schema.json
  • lifecycle.schema.json

Example:

bash 
curl https://smallprotocol.dev/schemas/small/v1/manifest.schema.json

For local development, replace the origin with http://localhost:5173.

What Is Not Hosted

The live site does not currently implement these as hosted HTTP endpoints:

  • POST /small/v1/validate-manifest
  • POST /small/v1/replay

Validation, replay identity, and lineage generation remain part of the SMALL CLI and downstream implementations, not the static public docs site.

Integration

OpenAPI Tooling

The OpenAPI specification can still be used with standard tooling:

  • Swagger UI: Inspect the public discovery contract
  • Postman: Import the protocol and schema fetch surface
  • Code Generation: Generate lightweight clients for discovery endpoints
  • API Testing: Validate the hosted discovery contract against deploys

Agent Integration

Agents can integrate with the public surface by:

  1. Discovering the protocol via GET /protocol/small/v1
  2. Fetching published schemas from /schemas/small/v1/<name>.schema.json
  3. Validating artifacts locally or inside their own runtime boundary
  4. Treating replay generation as CLI/runtime behavior, not a hosted site API

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 protocol version is 1.0.0.