Open Primitive Protocol Specification

1 Abstract

The Open Primitive Protocol (OPP) defines a standard interface for serving public government data to both human readers and autonomous agents. It solves the problem of fragmented, undocumented, and unsourced federal data APIs by requiring every response to carry its source, freshness, and optional cryptographic proof. OPP is designed for data providers who publish public-interest information and for agent developers who need structured, verifiable data without scraping or guesswork.

2 Status

3 Terminology

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

Additional terms used in this specification:

• Provider — An organization or service that publishes data through an OPP-compliant endpoint.
• Consumer — Any client that reads data from an OPP endpoint. This includes browsers, scripts, LLM agents, and orchestration frameworks.
• Manifest — A JSON document at /.well-known/opp.json that describes the provider's domains, endpoints, and capabilities.
• Envelope — The standard response wrapper that every OPP endpoint returns, containing source metadata alongside the data payload.
• Domain — A distinct category of public data (e.g., food-recalls, vehicle-complaints, water-quality).
• Registry — An optional index service that aggregates manifests from multiple providers for discovery.

4 Protocol Overview

OPP defines three components:

1. Provider Manifest — A machine-readable declaration of what data a provider serves, where to find it, and how to verify it.
2. Response Envelope — A standard wrapper around every data response that includes source attribution, freshness timestamps, and optional cryptographic proof.
3. Query Interface — Conventions for requesting data via HTTP GET, including parameter naming, error handling, and CORS policy.

Design principles

• Every response carries its own provenance. A consumer never needs to guess where data came from.
• Verification is optional but standardized. Providers that sign responses all use the same cryptosuite.
• The protocol is transport-layer simple. HTTP/HTTPS only. JSON payloads. No WebSocket, no streaming, no binary framing.

Interoperability

OPP is designed for compatibility with existing protocols and standards:

• MCP (Model Context Protocol) — An OPP provider can expose its domains as MCP tools. The manifest includes an optional mcpServer discovery URL.
• A2A (Agent-to-Agent Protocol) — An OPP provider can publish an A2A agent card. The manifest includes an optional agentCard discovery URL.
• OpenAPI — Providers SHOULD publish an OpenAPI 3.x specification alongside the manifest.
• W3C Data Integrity — The proof object in the response envelope follows the W3C Data Integrity EdDSA Cryptosuites specification.
• JSON-LD — The manifest and response envelope use JSON-LD @context for semantic interoperability.

Transport and format

All OPP endpoints MUST be served over HTTP or HTTPS. Public providers SHOULD use HTTPS. All request and response bodies MUST be JSON. Providers MAY include a JSON-LD @context field for linked data compatibility.

5 Provider Manifest

Location

The provider manifest MUST be served at /.well-known/opp.json relative to the provider's base URL. The Content-Type header MUST be application/json.

Schema

provider object

domains[] object

endpoints object

discovery object

geographic object

authentication object

Example manifest

{
  "@context": "https://openprimitive.com/ns/opp/v1",
  "name": "Open Primitive API",
  "description": "US federal data across 16 domains from 11 agencies.",
  "version": "1.0.0",
  "protocolVersion": "0.1.0",
  "provider": {
    "name": "Open Primitive",
    "url": "https://openprimitive.com",
    "contact": "david@openprimitive.com",
    "publicKey": "z6MkhaXg..."
  },
  "domains": [
    {
      "id": "food-recalls",
      "name": "Food Recalls",
      "source": "FDA openFDA API",
      "entityTypes": ["recall", "enforcement"],
      "freshness": "daily",
      "license": "US-PD",
      "endpoint": "/api/food-recalls"
    }
  ],
  "endpoints": {
    "base": "https://api.openprimitive.com",
    "query": "/api/query"
  },
  "discovery": {
    "openapi": "https://api.openprimitive.com/openapi.json",
    "llms": "https://api.openprimitive.com/llms.txt",
    "mcpServer": "https://api.openprimitive.com/mcp",
    "agentCard": "https://api.openprimitive.com/.well-known/agent.json"
  },
  "geographic": {
    "scope": "US",
    "granularity": "zip"
  },
  "authentication": {
    "type": "none"
  },
  "lastUpdated": "2026-03-19T00:00:00Z"
}

6 Response Envelope

Every response from an OPP endpoint MUST return a JSON object conforming to the envelope schema. The envelope carries source metadata alongside the domain-specific payload, so that no response exists without provenance.

Top-level fields

confidence object

citations object

version object

proof object

Example response

{
  "domain": "food-recalls",
  "source": "FDA openFDA API",
  "source_url": "https://api.fda.gov/food/enforcement.json",
  "freshness": "2026-03-19T08:00:00Z",
  "data": {
    "results": [
      {
        "product": "Organic Peanut Butter",
        "reason": "Salmonella contamination",
        "classification": "Class I",
        "status": "Ongoing",
        "date": "2026-03-18"
      }
    ],
    "total": 1
  },
  "confidence": {
    "completeness": 0.95,
    "methodology": "Direct FDA API query, filtered to last 30 days",
    "note": "FDA data may lag 24-48 hours behind actual recall announcements"
  },
  "citations": {
    "statement": "Data from the FDA openFDA enforcement database",
    "source_name": "FDA openFDA",
    "source_url": "https://open.fda.gov/apis/food/enforcement/",
    "accessed": "2026-03-19T08:00:00Z",
    "license": "US-PD"
  },
  "version": {
    "data": "2026-03-19",
    "schema": "1.0.0",
    "protocol": "0.1.0"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "verificationMethod": "https://api.openprimitive.com/.well-known/opp.json#provider",
    "created": "2026-03-19T08:00:01Z",
    "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndTn..."
  }
}

7 Query Interface

HTTP method

All OPP data endpoints MUST accept GET requests. Providers MAY additionally support POST for complex queries, but GET is the baseline.

Query parameters

Query parameter names SHOULD use lowercase, with words separated by underscores (e.g., zip_code, date_from). Providers MUST document accepted parameters per domain in their OpenAPI specification or equivalent documentation.

Pagination

Providers that return lists SHOULD support pagination using limit and offset parameters. Default limit SHOULD be between 10 and 100. Providers MUST document the maximum allowed limit.

Error responses

When a request fails, the response MUST return a JSON object with an error field containing a human-readable error message. The HTTP status code MUST be appropriate to the error:

Example error response:

{
  "error": "Missing required parameter: zip_code"
}

CORS

Public providers MUST set the Access-Control-Allow-Origin header to * on all responses. Providers that require authentication MAY restrict the origin list, but MUST still support CORS preflight requests.

Content-Type

All responses MUST include the header Content-Type: application/json.

8 Discovery

The manifest at /.well-known/opp.json serves as the primary discovery mechanism for OPP providers. Any client that knows a provider's base URL can fetch the manifest and learn what domains are available, where to query them, and how to verify responses.

Providers SHOULD publish at least one additional discovery mechanism to maximize reachability across different consumer types:

• OpenAPI specification — For traditional API consumers and developer tooling. List the URL in discovery.openapi.
• llms.txt — A plain-text file describing the provider's capabilities in natural language, optimized for LLM consumption. List the URL in discovery.llms.
• MCP server — An MCP-compatible server endpoint that exposes domains as tools. List the URL in discovery.mcpServer.
• A2A agent card — An Agent-to-Agent protocol agent card for agent orchestration frameworks. List the URL in discovery.agentCard.

Consumers SHOULD check for /.well-known/opp.json first. If it exists, the consumer has everything needed to interact with the provider. The additional discovery URLs are convenience entry points for ecosystems that do not natively understand OPP.

9 Verification

Verification is optional. Providers that choose to sign responses gain Level 3 (Verified) conformance and give consumers a way to detect tampering between the provider and the end user.

Algorithm

Providers that sign responses MUST use Ed25519 with the eddsa-jcs-2022 cryptosuite, as defined in the W3C Data Integrity EdDSA Cryptosuites specification.

Key management

The Ed25519 public key MUST be included in the provider manifest at provider.publicKey, encoded as a base64url string. Providers SHOULD rotate keys by publishing a new manifest with the updated key and re-signing subsequent responses. Old responses signed with the previous key remain valid against that key.

Signing process

1. Construct the complete response object (all fields except proof).
2. Canonicalize the JSON using JCS (JSON Canonicalization Scheme, RFC 8785).
3. Sign the canonicalized bytes with the provider's Ed25519 private key.
4. Encode the signature as a base64url string.
5. Attach the proof object to the response with type, cryptosuite, verificationMethod, created, and proofValue fields.

Verification process

A consumer verifies a signed response with these steps:

1. Fetch the provider manifest from /.well-known/opp.json.
2. Extract the public key from provider.publicKey.
3. Remove the proof field from the response object.
4. Canonicalize the remaining JSON using JCS (RFC 8785).
5. Decode proof.proofValue from base64url.
6. Verify the signature against the canonicalized bytes using the Ed25519 public key.

If verification fails, the consumer SHOULD treat the response as untrusted. The consumer MAY still use the data but MUST NOT represent it as verified.

10 Federation

OPP is designed to work without centralized coordination. Any organization can publish a manifest and serve data. Federation adds an optional layer for discovery across providers.

Registries

Providers MAY register with one or more OPP registries. A registry is a service that indexes provider manifests and exposes a search interface.

Registries SHOULD support search by:

• Domain — Find providers that serve a specific domain (e.g., food-recalls).
• Entity type — Find providers that serve a specific entity type (e.g., recall).
• Geographic scope — Find providers that cover a specific region (e.g., US, EU).

Authority

No registry is authoritative. Multiple registries MAY index the same provider. Consumers MAY query multiple registries and merge results. When two providers serve the same domain, the consumer decides which to trust based on freshness, conformance level, and verification status.

Registry protocol

The registry protocol is not defined in this version of the specification. A future version will specify the registry manifest format, search API, and registration process.

11 Versioning

OPP uses three distinct version numbers, each tracking a different rate of change.

Protocol version

Tracked in manifest.protocolVersion. Uses semantic versioning (semver). The current protocol version is 0.1.0.

• Patch (0.1.x) — Clarifications, typo fixes, non-behavioral changes to the spec text.
• Minor (0.x.0) — New optional fields added. Existing fields unchanged. Backwards compatible.
• Major (x.0.0) — Removed or renamed fields. Changed semantics of existing fields. Not backwards compatible.

Schema version

Tracked per domain in response.version.schema. Each domain defines its own payload structure, and that structure versions independently from the protocol. A provider MAY update a domain schema without changing the protocol version.

Data version

Tracked temporally in response.version.data. This represents the vintage of the data, not the structure. A data version of "2026-03-19" means the data reflects the state of the upstream source as of that date.

Backwards compatibility

New fields added to the envelope or manifest are always additive and constitute a minor version bump. Consumers MUST ignore fields they do not recognize. Removing a field or changing the type or semantics of an existing field requires a major version bump.

12 Conformance

OPP defines three conformance levels. Each level builds on the previous one. A provider claims a level by meeting all of its requirements.

Claiming conformance

Providers SHOULD indicate their conformance level in their documentation and llms.txt. There is no certification process. Conformance is self-declared and verifiable by any consumer that checks the manifest and response structure.

Partial conformance

A provider that includes proof on some responses but not all MUST NOT claim Level 3. Conformance applies to the provider as a whole, across all domains and endpoints.

13 References

• [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. https://www.rfc-editor.org/rfc/rfc2119
• [RFC8785] Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, June 2020. https://www.rfc-editor.org/rfc/rfc8785
• [DI-EDDSA] W3C, "Data Integrity EdDSA Cryptosuites v1.0", W3C Recommendation, 2024. https://www.w3.org/TR/vc-di-eddsa/
• [VC-2.0] W3C, "Verifiable Credentials Data Model v2.0", W3C Recommendation, 2024. https://www.w3.org/TR/vc-data-model-2.0/
• [JSON-LD] W3C, "JSON-LD 1.1", W3C Recommendation, 2020. https://www.w3.org/TR/json-ld11/
• [MCP] Anthropic, "Model Context Protocol Specification", 2024. https://modelcontextprotocol.io/specification
• [A2A] Google, "Agent-to-Agent Protocol Specification", 2025. https://a2a-protocol.org/latest/specification/