Engineering · Reference

Schemas

The exact wire shape of the four objects the platform revolves around. Every field below exists in a dataclass and its to_dict().

Evidence schema

The EvidenceEnvelope is a frozen dataclass with eleven top-level blocks. schema_version is "1.0"; kind is "evidence_envelope".

src/vailidator/evidence/envelope.py

Field	Type	Contents
`schema_version`	str	`"1.0"`
`envelope_id`	str	ev_ + uuid4 hex
`operation`	str	operation/type identifier
`created_at`	str	ISO-8601 UTC
`provider`	dict	`ProviderResult.to_dict()`
`routing`	dict	requested/selected/attempted/skipped, fallback, router_mode
`execution`	dict	flattened operational summary of the run
`diagnostics`	dict	safe provider diagnostics (secret-free)
`evidence`	dict	identifier block: id, kind, schema_version, operation, created_at
`receipt`	dict	`Receipt.to_dict()` (see below)
`provenance`	dict	`Provenance.to_dict()`
`replay`	dict	inert placeholder, `{status:"pending", replayable:false, input_ref:null}`

{
  "schema_version": "1.0",
  "envelope_id": "ev_1a2b…",
  "operation": "audit_ai_response",
  "created_at": "2026-07-04T12:00:00+00:00",
  "provider":    { "provider": "mock", "mode": "mock", "status": "ok",
                   "latency_ms": 0.0, "result": { … }, "diagnostics": { … } },
  "routing":     { "requested_provider": null, "selected_provider": "mock",
                   "attempted_providers": ["mock"], "skipped_providers": [],
                   "fallback_used": false, "fallback_reason": null,
                   "router_mode": "forced" },
  "execution":   { "operation": "…", "requested_provider": null,
                   "selected_provider": "mock", "mode": "mock", "status": "ok",
                   "latency_ms": 0.0, "attempted_providers": ["mock"],
                   "skipped_providers": [], "fallback_used": false,
                   "fallback_reason": null, "router_mode": "forced" },
  "diagnostics": { "provider": "mock", "env": "development",
                   "provider_mode": "mock", "enabled": true,
                   "key_present": true, "reason": "mock_provider",
                   "routing": { … } },
  "evidence":    { "id": "ev_1a2b…", "kind": "evidence_envelope",
                   "schema_version": "1.0", "operation": "…",
                   "created_at": "…" },
  "receipt":     { … Receipt.to_dict() … },
  "provenance":  { … Provenance.to_dict() … },
  "replay":      { "status": "pending", "replayable": false, "input_ref": null }
}

Receipt schema

Receipt: frozen dataclass, receipt_version "1.0". Operational metadata only; no cryptography.

src/vailidator/evidence/receipt.py

Field	Type	Contents
`receipt_id`	str	rcpt_ + uuid4 hex
`evidence_id`	str	parent envelope id
`operation_id`	str	operation/type identifier
`created_at`	str	ISO-8601 UTC (shared with the envelope)
`provider`	str	adapter that produced the result
`selected_provider`	str	provider the router chose
`status`	str	`ok` · `fallback` · `error`
`execution_status`	str	`primary` · `fallback`
`diagnostics_summary`	dict	safe subset: provider, env, provider_mode, enabled, key_present, reason
`routing_summary`	dict	requested/selected, fallback_used, router_mode, attempted_providers
`receipt_version`	str	`"1.0"`

Passport schema

AgentPassport: frozen dataclass, passport_version "1.0", status ∈ {active, provisional, unknown}.

src/vailidator/passport/models.py

Field	Type	Contents
`passport_id`	str	pass_ + SHA-256(agent_id)[:16]
`agent_id`	str	content-derived agent id
`created_at` / `issued_at`	str	ISO-8601 UTC (injectable clock)
`identity_summary`	dict	provider, platform, runtime, agent_name, agent_type, identity_version, present
`trust_summary`	dict	latest/average/best/worst trust score, latest level, trust_level_counts
`compliance_summary`	dict	latest_status + status_counts
`risk_summary`	dict	latest_level + level_counts
`quality_summary`	dict	latest_level + level_counts
`operation_summary`	dict	operation_count, first_seen, last_seen
`status`	str	active · provisional · unknown
`metadata`	dict	caller metadata

Trust object schema

TrustAssessment: frozen dataclass, trust_version "1.0". Aggregates compliance + risk + quality.

src/vailidator/trust/models.py

Field	Type	Contents
`trust_assessment_id`	str	tr_ + uuid4 hex
`evidence_id` / `receipt_id` / `provenance_id`	str?	linkage ids picked from the components/envelope
`created_at`	str	ISO-8601 UTC (injectable)
`trust_score`	int	0–100
`trust_level`	str	trusted · acceptable · caution · untrusted · unknown
`compliance_summary` / `risk_summary` / `quality_summary`	dict	id-free component summaries (keeps output deterministic)
`signals`	list	weighted `TrustSignal` contributions (category, source, value, weight, contribution, detail)
`findings`	list	`TrustFinding` detractors (category, source, title, severity, detail)
`summary`	dict	score, level, max_score, breakdown, components_present, confidence, counts
`disclaimer`	str	"automated, aggregated trust signal … not a guarantee, certification, or advice"
`trust_version`	str	`"1.0"`

Every other assessment (compliance / risk / quality / reputation) and the identity, trust-profile, signal and registry-entry objects follow the same discipline: a frozen dataclass, an explicit *_version, and a to_dict() that is the wire contract. See the API reference for the response envelopes.