Structured fact data with a visible audit trail

Model the relationship, not only the answer

A statement and a source are separate things. An assessment records how a source passage relates to a specific statement during a particular check. Separating those objects makes it easier to reuse evidence, correct an interpretation, and preserve the history of a result.

Use stable identifiers for claims, source versions, evidence passages, and assessments. Document whether those identifiers are local or externally resolvable. One source may support several claims, while one claim may need several pieces of evidence. Your data model should make those relationships visible rather than hide them inside a single explanation field.

What provenance adds

W3C’s PROV overview describes provenance through entities, activities, and the people involved in producing information. That provides a useful conceptual reference: what material was used, which process acted on it, and who or what was responsible for the result.

The FactAPI.com examples use a small illustrative JSON contract rather than claim conformance to a complete provenance standard. The practical objective is reconstructability. Another reviewer should be able to locate the claim, inspect the evidence, and understand the limited conclusion without guessing which document or model version was involved.

Choose fields that cannot silently change meaning

Keep original wording separate from normalized wording. Distinguish source publication, source revision, retrieval, and assessment dates. An old document retrieved today has not become a newly published source. Use null deliberately for unavailable information instead of substituting zero or an empty string.

Separate processing errors from evidence assessments. Define every status in plain language. A supported status in our examples means supported by the named fictional passage, not verified against the entire public record. Any confidence measure should have its own documented interpretation rather than masquerade as a universal probability of truth.

Version the contract and the decisions

Add a schema version and a compatibility policy. Validate successful, partial, and failed responses. Preserve an earlier assessment when a correction is issued, and link the new assessment to the one it supersedes. Do not let a delayed result overwrite a newer decision merely because it arrived last.

Record why something changed: a revised source, an extraction repair, a reviewer correction, or additional evidence. The reason determines how downstream content should be revisited. A bibliographic typo and a contradicted central claim are not the same maintenance event.

Put the schema to work

The developer examples contain a local JSON evidence pack and a machine-readable schema. They are downloadable static files, not an API service. Use them to discuss the shape of an evidence-oriented response and adapt the contract to your own evaluation and access requirements.

Read the full structured-data article for implementation considerations, and connect it to the source-watch operating model. Good structure does not make a claim true; it makes the basis and limits of an assessment visible enough to review.