ecz-agent.json — Schema Reference

Purpose

A small, machine-readable JSON document at /.well-known/ecz-agent.json that lets a verifier discover which Agent Credential and API Passport references to resolve.

Canonical reference

This page is the one reference for the ecz-agent-json-v1 declaration. Every ecz-agent.json example on this site is generated from the same machine-readable registry, /schemas/declaration-contracts.json. The operator is operator_ecz_id: the Parent ECZ-ID of the accountable operator, as ECZ-ID Core and the Resolver name it.

Required fields

• schema_version — the manifest schema version, e.g. ecz-agent-json-v1
• operator_ecz_id — the Parent ECZ-ID of the accountable operator
• agent_credential_id — the Agent Credential identifier the relying party should resolve
• agent_name — the human-facing agent name
• logical_agent_id — the stable logical identifier the operator uses internally
• manifest_url — the canonical URL where this manifest is published
• resolver_url — the public Resolver URL for the Agent Credential

Recommended fields

• declared_scope — short human description of what the agent is authorised to do
• api_dependencies — array of API Passport references with name, api_passport_id, and resolver_url
• updated_at — ISO 8601 timestamp of the last manifest update

Forbidden fields

• No secrets
• No private keys
• No tokens or auth headers
• No prompts or system messages
• No source code
• No user data
• No signatures, JWS, or key proof unless the backend and Resolver actually support that signal live
• No claims of marketplace, platform, or regulatory approval

Example (illustrative only — not a live credential)

{
  "schema_version": "ecz-agent-json-v1",
  "operator_ecz_id": "ECZ-GB-EXAMPL",
  "agent_credential_id": "ECZ-GB-EXAMPL::AGENT-ABC123",
  "agent_name": "Example Support Agent",
  "logical_agent_id": "example-support-agent",
  "declared_scope": "Customer support triage for example.com",
  "manifest_url": "https://example.com/.well-known/ecz-agent.json",
  "resolver_url": "https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/AGENT/ABC123",
  "api_dependencies": [
    {
      "name": "Example Support API",
      "api_passport_id": "ECZ-GB-EXAMPL::API-DEF456",
      "resolver_url": "https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/API/DEF456"
    }
  ],
  "updated_at": "2026-05-01T00:00:00Z"
}

Validation notes

• Serve over HTTPS only
• Serve as Content-Type: application/json
• Keep the manifest small — discovery payload, not data dump
• Re-publish when the underlying Agent Credential reference or API dependency changes
• Do not assume the manifest itself confers trust

Privacy and security notes

The manifest is public. Treat it like a sign on the front door. Anything that should not be public must not appear in this document.

TrustOps and Resolver linkage

Acquisition, activation, and lifecycle of the referenced credentials happen in TrustOps. Current proof state lives in Resolver. The manifest only points at both.

Declaration, not binding proof

A declaration names its operator with operator_ecz_id. A binding proof is a separate step: when ECZ-ID Core opens a binding challenge, its proof instructions give the exact document to publish, with parent_ecz_id, binding_id and challenge. Copy that document verbatim. Never write those fields by hand, and never rename operator_ecz_id to parent_ecz_id in a declaration.