Heretic Verdict Schema: Complete JSON Field Reference

Every response from the explain endpoint follows this schema. Use this reference when you write the parsing and enforcement logic on your server — for example, when deciding whether to block an action based on conclusive, branch on a specific verdict value, or inspect individual signals for audit logging.

Top-Level Fields

integer

required

Response schema version. Currently 7. The value increments on breaking changes to the response structure. Check this field in production parsers so you can gate on the version you were written against and fail safely if an unexpected version arrives.

object

required

Metadata about the API version that produced this verdict. Useful for bug reports and support tickets.

Show provenance fields

string

required

Build identifier for the API version that evaluated this session. Example: "0.0.1+11f956e".

string

required

The ruling for this session. One of contradicted, refused, disputed, uncontradicted, or insufficient. See the Verdicts table below for the full breakdown of what each value means and when to act on it.

boolean

required

true when the verdict is backed by an absolute signal or by two corroborating composite signals from different evidence families. Use this flag as your primary enforcement gate — a conclusive: true result means the evidence is strong enough to act on without additional review.

string

required

A human-readable, one-to-two sentence explanation of why the verdict was reached. Suitable for internal dashboards, support tooling, or analyst review queues. Example: "Claimed locale is physically unreachable; transport stack contradicts the claimed OS."

string[]

required

List of evidence family IDs whose signals actively contradicted the client’s claims. Empty when the verdict is anything other than contradicted. Possible family IDs: network-geometry, transport-stack, tls-construction, compute, render, declared.

object

required

Aggregate counts of how many evidence families participated in this session’s measurement.

Show families fields

integer

required

Number of families that attempted measurement during the session.

integer

required

Number of families that returned usable results. When reporting is significantly lower than measured, the client may have refused measurements — check the verdict for refused.

array

required

Individual signals that fired during evaluation. Each entry represents one specific test that produced a result. The array may be empty for insufficient verdicts where too few families reported.

Show signal object fields

string

required

Stable, dot-namespaced signal identifier. The namespace prefix corresponds to the evidence family (e.g. geo. for network-geometry, stack. for transport-stack). Example: "geo.rtt-below-vacuum".

string

required

Signal strength classification. One of:

absolute — a single signal that is conclusive on its own
composite — strong signal; two signals from different families make the verdict conclusive
conditional — meaningful only alongside other signals
weak — advisory; contributes to context but not to conclusiveness

string

required

One-line human-readable explanation of what this signal observed. Example: "RTT 2.1ms; light needs 27.4ms".

Verdicts

The verdict string and conclusive boolean work together. Use conclusive as your primary enforcement signal and verdict for categorisation, logging, and routing.

Verdict	`conclusive`	Meaning
`contradicted`	`true`	One absolute signal, or two corroborating composite signals from different families, found a direct contradiction. Safe to act on automatically.
`contradicted`	`false`	A contradiction was detected but the evidence has not yet reached the conclusive threshold. Consider flagging for review rather than blocking.
`refused`	varies	The client refused one or more required measurements. Treat refusal as a strong negative signal in most enforcement contexts.
`disputed`	`false`	Evidence leans toward contradiction but is not conclusive. Review recommended.
`uncontradicted`	`false`	No contradiction was detected across all reporting families.
`insufficient`	`false`	Too few families reported results to reach a verdict. The session may have been cut short or the collector did not complete its run.

The schema integer will increment whenever there is a breaking change to this response structure. Always check schema in your production parser and handle unexpected versions explicitly — do not silently fall through to default logic.

API Overview and Authentication: base URL, authentication, and error handling
GET /e — Explain Endpoint Reference: request parameters, code examples, and the full sample response

​Top-Level Fields

​Verdicts

​Related

Top-Level Fields

Verdicts

Related