PoQ Report spec

This is the field-by-field reference for the PoQ Report payload — the canonical JSON that every PoQ Report is a render of. For the conceptual overview (what a report is, how to read it, and how to verify one), see the PoQ Report guide.

Every PoQ Report is one canonical JSON payload (schema poq.attestation/v1), signed once. The readable formats — text, HTML — are deterministic renders of that payload, so this reference is also the source of truth for every value shown on a report page.

The payload is a single object. Its top-level keys map one-to-one onto the report's sections:

The payload is strict: additionalProperties is false at every level, so any key not listed here is rejected. Every required field must be present.

Value types

Several fields reuse the same primitive types. They are defined once here and referenced throughout.

No floats in the signed bytes. Every numeric value is carried either as a bounded integer (scores, counts) or as a string (weights, wei). The signed payload contains no floating-point numbers, so the canonical bytes are deterministic.

Identity

The four top-level scalars that identify the report. They render in the report header.

scope

Which project the report covers and how much of it was reviewed. Renders as the Scope section.

result

The headline result. Renders as the Result section.

label object:

scorecard

Per-dimension quality and consensus, with rubric weights. A non-empty array; renders as the Scorecard section. Each element:

distribution

How scores were spread across datapoints. Renders as the Distribution section (histograms).

Each bands map has at least one entry; band labels are 0-9, a two-digit range like 40-49, or 90-100, and each count is ≥ 1.

poq_record

A commitment to the full per-datapoint PoQ Record, plus an optional one-datapoint excerpt signed inline. Renders as the PoQ Record excerpt section.

excerpt object:

excerpt.datapoint object:

excerpt.datapoint.quorum[] — one entry per round:

excerpt.datapoint.quorum[].votes[] — one entry per validator:

excerpt.datapoint.dimensions[] — per-dimension breakdown:

quorum_routing

How validators were assigned across rounds, and where datapoints settled. Renders as the Quorum routing section.

quorum_routing.rounds[]:

quorum_routing.rounds[].slots[] — a validator slot. Each slot is either a human slot or an agentic slot (enforced by the schema's oneOf):

A human slot must carry credential + instructions_hash and must not carry model/prompt_hash; an agentic slot is the mirror image. Mixing the two is rejected.

quorum_routing.execution:

configuration

The rubric and the locked config. Renders as the Configuration section.

pool

Validator pool size, churn, participation, and independence. Renders as the Pool & provenance section.

stake

Collateral mode only. Present only for events that put stake at risk; omitted otherwise. Renders under Pool & provenance.

custody

The chain-of-custody timestamps. Renders as the Chain of custody section. All five are required timestamps.

attestation

The cryptographic roots and signing key. Renders as the Attestation section.

assertion

The signed payload

The object above is signed exactly once and delivered in whichever format you request. The signature and canonicalization are fixed properties of poq.attestation/v1:

Any change to a covered value — in the JSON, the readable text, or the HTML — breaks verification.

Formats

The one signed payload is delivered in any of four formats:

Envelopes

The two readable formats declare an envelope version so a verifier knows how to interpret the carrier before applying any grammar:

In the text artefact the JWS sits between -----BEGIN POQ SIGNED PAYLOAD----- / -----END POQ SIGNED PAYLOAD----- fences. In the HTML the same text artefact is embedded in a <script type="application/poq-attestation+text"> element. For how to verify either offline, see Verifying a report.

See also