Structured fact data is most useful when it preserves the difference between a statement, a source, and an assessment. A single object that mixes all three may look convenient at first, but it becomes difficult to update when a source changes or a reviewer reaches a different conclusion. A more durable design treats the evidence relationship as a first-class part of the record.
This article develops a proposed JSON design for evidence-oriented applications. The field names are illustrative rather than an industry standard or a live FactAPI.com endpoint. The goal is a record that can be read by a developer, reviewed by an editor, and revisited after an update without requiring everyone to reconstruct the original decision from a chat transcript.
Start with provenance rather than a truth score
The W3C PROV overview describes provenance in terms of information about entities, activities, and people involved in producing something. That framework is a useful reference for deciding what an evidence record needs to explain: what material was used, what process acted on it, and who or what was responsible for the resulting assessment.
You do not need to implement the full PROV family to adopt that habit. Begin with a source entity, an assessment activity, and an accountable reviewer or system version. Make the relationships explicit. A number such as confidence: 0.94 explains none of those relationships by itself, and should not substitute for the evidence needed to understand a result.
Give claims and sources different identifiers
A claim identifier should remain stable across repeated checks of the same precisely defined assertion. A source identifier should refer to a document or source record. An evidence identifier can refer to a particular passage within a particular version of that document. An assessment identifier then connects a claim with the evidence considered in one check.
This separation helps when a single source supports multiple claims or a single claim requires several sources. It also prevents accidental overwrites. For example, a new assessment of the fictional Meridian catalog’s opening date should not silently replace the source record used in an earlier assessment. Document whether identifiers are assigned locally, derived from content, or supplied by an external registry. Do not imply that a local identifier is globally resolvable.
Preserve both original and normalized wording
Use a claim_text field for the statement under review and a separate original_span field for the passage from which it was extracted. Add normalized wording only when your application needs it for search or matching. Keep the original entity names, qualifiers, and attribution recoverable even when the normalized representation uses canonical identifiers.
Time and scope deserve their own treatment. A claim about a project’s size at launch is different from a claim about its present size. A claim about a sample is different from a claim about an entire population. Represent those distinctions in readable text even when you also add structured fields. Consumers should not have to inspect an undocumented numeric code to discover that the assessment applies only to a narrow context.
Represent evidence as a relationship
Each evidence item should say which claim it addresses and what relationship it has to that claim. Useful local labels include supports, contradicts, and provides_context. Define these labels in the schema documentation. Do not make a citation’s mere presence equivalent to support; a document may discuss the topic while failing to justify the specific assertion.
Include the source title, locator, version information where available, and a retrieval time. Store a passage when permitted and useful, or a reproducible pointer when you cannot retain the content. Distinguish an unavailable passage from an empty passage. An application that failed to retrieve the text should not report that the source contains no relevant evidence. Access status belongs beside, not inside, the factual assessment.
Keep assessment labels and processing states apart
Use assessment.status for the evidence-based conclusion and a separate processing field for completion, failure, or partial work. In the accompanying illustrative schema, assessment labels are supported, contradicted, and insufficient_evidence. They are local contract choices, not claims about a universal taxonomy. A human-review flag can coexist with any of them.
Reserve null values for genuinely unknown or unavailable information and document their meaning. Zero, an empty string, and null should not be interchangeable. A missing date is not a date of zero, and an uncalculated score is not a score of zero percent. This distinction becomes important when downstream software sorts records, computes totals, or decides which items need attention. Make invalid states difficult to express.
Separate the dates that answer different questions
A robust record may need a source publication date, a source revision date, a retrieval timestamp, an assessment timestamp, and the period addressed by the claim. These values answer different questions. Retrieving an old document today does not make its findings current, and checking an assessment today does not prove the underlying source has been revised.
Use explicit timezone-aware timestamps for events where the time matters. Preserve date-only values as dates rather than inventing a midnight timestamp that suggests greater precision. A date’s provenance should be visible when it was inferred from text instead of supplied by the publisher. For changing claims, define when an assessment becomes stale and who decides whether a new source check is needed.
Version the schema and the assessment process
Place a schema_version in the response and publish a compatibility policy. Adding an optional field is different from changing the meaning of an existing status. Decide how clients should handle unknown fields and labels before introducing them. Validate representative examples against the schema as part of a release check, including incomplete and failed responses.
Record the versions of the extraction, retrieval, and assessment components when those components influence the result. Avoid placing private prompts or credentials in public records. A concise configuration identifier can point to controlled internal documentation. The audit goal is to make a decision reproducible within the authorized environment, not to expose every operational detail to every consumer. Keep public explanation and internal debugging metadata appropriately separated.
Design updates without erasing history
Treat a correction as a new assessment linked to the previous one, with an explanation of what changed. A source revision, a reviewer correction, and a newly discovered contradictory document are different reasons for an update. Preserve that reason so downstream applications can determine whether to refresh a badge, notify an editor, or reopen a dependent article.
Use explicit supersession relationships instead of relying on whichever record happened to arrive last. A delayed message should not overwrite a newer assessment. Decide whether a client requests the current view, the full history, or a view as of a particular date. For small static examples, the distinction can be documented without implementing a database. For a production service, it belongs in both the data contract and the tests.
Test whether someone else can reconstruct the check
Take a completed record and give it to a reviewer who did not create it. Can they identify the exact claim, locate the evidence, understand the scope of the conclusion, and see why the status was assigned? Ask the same questions after replacing the source with a revised version. Missing context usually becomes obvious during this exercise.
The local JSON examples and schema provide a small starting point. Pair them with the source-watch guide to plan how records change over time. Good structure does not make unsupported statements true. It makes the basis, boundaries, and history of an assessment visible enough for people and software to work with responsibly.
