Write and review claims

A claim history keeps what a source said separate from what a reviewer assessed. It contains an observation and a list of claims, each with its own identity, recording time and subject. Earlier claims remain available when a review is revised.

Three claim shapes

An omitted claim is not the same as an explicitly unassessed question. An assessed absence is also different: a reviewer has performed an assessment and declared absent.

1. Run the complete history

Requirements: Node.js 22 and npm. This walkthrough uses the published @disclosureos/records@2.0.0-beta.4 package. It needs no source checkout, account or service. Reuse your first-record project if it already has that exact package, or create one:

mkdir disclosureos-claims
cd disclosureos-claims
npm init -y
npm install --save-exact @disclosureos/records@2.0.0-beta.4

Download the complete teaching history and its checker into the same directory:

curl --fail --location \
  https://os.disclosure.org/examples/v2/claims/history.json \
  --output history.json
curl --fail --location \
  https://os.disclosure.org/examples/v2/claims/check-claims.mjs \
  --output check-claims.mjs
node check-claims.mjs history.json

The .mjs extension lets Node run the ESM import directly. The checker reads the file and calls parseExperimentalClaimHistory from @disclosureos/records/experimental/v2. It does not save, upload or publish anything.

{
  "success": true,
  "checks": {
    "structural": "passed",
    "semantic": "passed",
    "profile": "not_checked",
    "external": "not_checked"
  },
  "uncheckedRefs": [
    "source:account-a",
    "source:account-a-follow-up",
    "method:account-review"
  ],
  "issues": [],
  "currentClaimRefs": [
    "claim:statement",
    "claim:clarification",
    "claim:revised",
    "claim:independent"
  ]
}

Both structure and local relationships pass. The two source files and the method remain unchecked: declaring a digest does not read the file, and declaring a method does not run it. currentClaimRefs includes source statements as well as assessments. It means not superseded within this document, not accepted, verified or preferred.

The history uses document version 0.1.0, separately from package version 2.0.0-beta.4. It supports observation and measurement subjects. Choose a subject-specific contract when reviewing a witness, document edition, specimen or other entity.

2. Trace the source and review

The first account says:

The arrangement appeared to move upward relative to the ridge.

Its follow-up clarifies:

I meant that the light's apparent position changed relative to the ridge. I did not measure its distance, and I did not calculate a physical speed.

These are excerpts; the complete accounts retain the surrounding qualifications. The follow-up is another account from the same person, not another witness. The teaching history retains both statements. Its event time and position stay unknown because this exercise does not assemble the field session's timing or location information.

The full source wording does not supply a physical acceleration measurement. The two teaching reviewers agree that the question remains unresolved. Separate reviewers can disagree, but this example does not manufacture a disagreement.

{
  "kind": "assessment",
  "topic": "Do the accounts establish physical acceleration?",
  "subject": {
    "kind": "observation"
  },
  "id": "revised",
  "recordedAt": "2026-10-16T10:03:00Z",
  "status": "assessed",
  "outcome": "inconclusive",
  "inputRefs": ["claim:statement", "claim:clarification"],
  "rationale": "The follow-up explicitly distinguishes apparent position from a physical speed estimate. The added source changes the rationale, but leaves the question unresolved.",
  "evaluatedBy": "Reviewer A (fictional)",
  "evaluatedAt": "2026-10-16T10:03:00Z",
  "methodRef": "method:account-review",
  "methodVersion": "1",
  "supersedes": ["claim:initial"]
}

Assemble your own history

1. Put the observation in history.observation. Declare its sources, products, methods and measurements before referring to them. Keep missing values explicit.
2. Add a source_assertion for wording you want to preserve. Its provenance.sourceRef points to the declared source or product. Record known attribution without substituting the extractor for the speaker.
3. Give each assessment a precise topic and subject. Add its input references and rationale. Use unassessed until a review exists; use assessed only with the required evaluator, time, method and outcome.
4. Add a new claim ID for a revision and list the earlier claim in supersedes. Preserve the earlier entry. A different evaluator records a separate assessment.
5. Parse the whole history and handle failure before using its contents. Persist the original submission and revision history according to your application's storage policy.

Sources, locators and input references

Keep these roles separate:

The observation's assertion: namespace identifies reported field values. claim: identifies source statements or assessments in this history. They are not interchangeable. A measurement subject uses its bare measurementId; an assessment input uses measurement:<id>.

Original-voice attribution is provenance.attributedTo; extraction attribution is provenance.extractedBy. Both are optional. In the example, recordedAt records when the teaching entry was made, not when Observer A originally spoke or when the event occurred. Do not invent a page or time locator for a plain-text source that has no such coordinate.

A topic is free text. To connect a review to an exact observable or origin definition, follow Use observable terms. The shared vocabulary connection is included in Beta 4. The term never replaces the subject or the supporting inputs.

3. Inspect failures and a valid branch

Each flag changes only an in-memory copy. The file stays unchanged. A failed check exits with status 1 and omits currentClaimRefs; unsupported arguments exit with status 2. Run without a flag to return to the original passing history.

Refer to a missing input

node check-claims.mjs history.json \
  --missing-input

The revised claim refers to claim:missing. Structure still passes, but semantics fail with REF.LOCAL_RESOLUTION at /claims/4/inputRefs/0. Do not fill the gap by dropping the reference or silently choosing a different source.

Replace another reviewer's assessment

node check-claims.mjs history.json \
  --change-reviewer

Changing the revised claim's evaluator to B while retaining its link to A's assessed predecessor fails with CLAIM.REVISION_ATTRIBUTION at /claims/4/supersedes/0. B needs a separate assessment, as the independent claim already demonstrates. Matching evaluator labels satisfy a local rule; they do not authenticate an identity.

Keep two revisions of the same predecessor

node check-claims.mjs history.json \
  --branch

This is valid. The checker adds parallel-revision, another assessment by A that supersedes initial. Both revised and parallel-revision remain current, along with the source statements and B's separate review. The parser does not select the last array entry or average outcomes. A later explicit revision can supersede both branches if it satisfies the same scope, attribution and timing rules.

Revisions and disagreement

A revision must preserve claim kind, topic and subject. An assessed predecessor can be replaced only by another assessed claim with the same evaluator label. Moving from unassessed to assessed is allowed; moving from an assessed conclusion back to unassessed is not a valid supersession.

Revision times cannot precede their predecessors, and an evaluation time cannot follow its own recording time. Claim-input and supersession references form one acyclic dependency graph. Array order does not establish priority.

Changing a subject or its exact snapshot creates a different review. Keep a separate claim rather than making a revision appear to assess the same thing. Two reviews that cite the same accounts are not two independent observations. Shared inputs remain visible; the parser does not compute a vote or aggregate score. A parser sees the submitted document; your storage layer must prevent a later submission from silently removing earlier history.

Outcomes and confidence

An assessed claim declares one of four outcomes: reported, confirmed, absent or inconclusive. The outcome applies to the stated question, subject, method and inputs. confirmed is not a document-wide badge or a finding automatically assigned by the standard. inconclusive does not mean absent.

confidence is an optional evaluator-declared number between 0 and 1. The example omits it. Do not fill omission with zero, interpret it as a calibrated probability without a stated basis, or average values across reviewers with different methods. Observable support levels and provider scores have their own meanings; see Observables and Scoring and checks.

What validation establishes

The parser does not read source bytes, verify that an excerpt matches its source, execute a method or establish scientific validity. It can compare digest declarations when both are supplied; that is not byte verification. An assessment can structurally allow an empty input list, so parser success alone is not research eligibility.

Check success, checks, issues and uncheckedRefs together. Structural failure leaves semantics unchecked. Semantic failure has diagnostic codes and JSON Pointers; an issue inside the embedded observation retains its /observation prefix. Use the appropriate profile checks or supplied-document evaluator for additional scope, and retain what those checks leave unresolved.

Review subjects

Choose a contract for the subject being reviewed. Later document versions add specific subject families; they are not a reason to relabel a base history's schemaVersion. Each needs its matching parser and dependencies.

All rows above are available in 2.0.0-beta.4. Parsers are exported by @disclosureos/records/experimental/v2; supplied-document evaluators are exported by @disclosureos/schema/experimental/v2. Follow the linked guide for each subject's required documents and checks.

Context subjects

A context review identifies the exact context snapshot, entity and optional field. Specific assertion references identify its supporting declarations. Follow Event and setting for the supplied-document checks.

Reviews of witnesses and accounts

A witnessReview preserves factors, rationale and uncertainty as the evaluator's declarations. It does not generate an automatic credibility score. The witness guide keeps source-reported procedures distinct from a reviewer's assessment.

Reviews of document editions

Edition citations retain the exact entity snapshot, edition, artifact and locator. Source-reported reviews remain separate from evaluations by a named reviewer. Follow Documents and custody for a runnable example.

Download and inspect the example

The downloadable history and checker above are the complete base example. Open the history JSON to inspect all six entries, or the checker to reuse its result handling. The browser inspector also accepts observation and claim-history JSON.

Field reference

Use the searchable base claim-history reference to choose a claim shape, inspect required fields and follow exact nested paths. It includes every branch of the 0.1.0 schema; subject-specific additions stay in the references listed above. The schema export is @disclosureos/records/experimental/v2/claims/schema, with identifier urn:disclosureos:experimental:claim-history:0.1.0.

Compare the showcase's retained reviews to see source changes, revisions and independent reviewers in the complete example. Continue to Origins to describe an explanation without confusing it with an observed characteristic.