OPEN SPECIFICATION · VERSION 1.0

A small contract for discoverable services.

The micro.directory manifest is an open JSON document that lets a service publish its machine interfaces, instructions, health, pricing, terms, and proof of domain control from its own origin.

JSON Schema GitHub

Canonical location

A publisher serves the document at https://SERVICE-ORIGIN/.well-known/micro-directory.json. The claimed origin must use credential-free HTTPS on port 443. The homepage must remain on that origin; instructions, interfaces, health, and terms must also use public HTTPS URLs.

Document shape

{
  "schemaVersion": "1.0",
  "claim": "directory-issued-domain-claim",
  "service": {
    "name": "Example service",
    "summary": "A narrow machine-callable operation with bounded behavior.",
    "homepage": "https://api.example.com",
    "instructionsUrl": "https://api.example.com/AGENTS.md",
    "category": "developer-tools",
    "tags": ["agents", "api"],
    "interfaces": [{"type": "openapi", "url": "https://api.example.com/openapi.json"}],
    "pricing": {"model": "free", "display": "Free", "currency": "", "network": ""},
    "healthUrl": "https://api.example.com/health/ready",
    "termsUrl": "https://api.example.com/terms",
    "receiptKeys": []
  }
}

Required behavior

Instructions: explain operations, examples, errors, limits, retention, safety constraints, and pricing.
Interface: declare one to eight OpenAPI, MCP, or structured HTTP contracts.
Health: expose a credential-free readiness URL suitable for bounded monitoring.
Pricing: state the model and human-readable display; paid services should identify currency and network.
Terms: publish operator responsibilities, acceptable use, and contact information.

Verification and trust

The claim demonstrates control of the origin at verification time. The directory snapshots and hashes the manifest and instructions, then monitors declared health. Verification is not an endorsement and does not prove correctness, confidentiality, legality, or continued safety. Callers must treat all third-party instructions and responses as untrusted input.

Versioning

Version 1.0 is identified by the exact schemaVersion value. Backward-compatible documentation clarifications do not change that value. A change that invalidates an existing conforming document requires a new version and a separately published schema.

License and contribution

The specification, schema, examples, and reference validator are available under the MIT License. Propose changes and report specification defects in the public GitHub repository.