Source and capture context

Up to 14 fields. Source- and endpoint-specific.

This page defines a response- and record-level provenance schema with up to 14 fields. Routes and source builders can emit a subset or no tuple, and nullable fields must remain null rather than being inferred. The schema records attribution and processing context; it does not create a signature link for each returned fact. Separate snapshot attestations apply only to the object they identify.

Cryptographic chain → Identity layer → Webhook events → Semantic search →

Core fields

Source attribution. Freshness. Methodology. Confidence.

01_sourcestring | nullnullable

Standard: FAIR R1.2 (data is associated with detailed provenance)

Canonical name of the upstream data source. Human-readable; matches the public name the source publishes itself under.

Example: "CMS NPPES NPI Registry (public API)"

02_source_urlstring | nullnullable

Standard: FAIR F4 (resources registered or indexed)

Public URL of the upstream source. Resolves to either the source's own portal or its API endpoint.

Example: "https://npiregistry.cms.hhs.gov/api/"

03_dataset_idstring | nullnullable

Standard: FAIR I1 (knowledge representation)

Fonteum-internal dataset slug. Stable across snapshots; matches data_sources.slug + the source-defaults registry key.

Example: "nppes-npi-registry"

04_snapshotstring | null (ISO date)nullable

Standard: HIPAA §164.312(c)(1) (integrity controls require dated snapshots)

ISO date YYYY-MM-DD of the snapshot used to produce this response. Stable identifier for the upstream pull.

Example: "2026-05-10"

05_methodologystring | nullnullable

Standard: ICMJE author guidelines (cite the methodology version)

Fonteum methodology version that produced the response. Bumps land in /methodology/changelog with date + summary.

Example: "v2026.05.0"

06_last_checkedstring | null (ISO timestamp)nullable

Standard: SOC 2 Type 2 CC7.1 (system monitoring)

ISO timestamp Fonteum last re-checked the value against the source. May be more recent than _snapshot when re-checks happen between snapshot pulls.

Example: "2026-05-10T07:00:00.000Z"

07_confidencenumber | null (0..1)nullable

Standard: ICMJE author guidelines (declare confidence in derived values)

0..1 score. 1.0 = verbatim from source. <1.0 = derived via cross-source matching, name normalization, or other inference.

Example: 1.0

08_data_availabilitystring[] | nullnullable

Standard: FAIR A1 (retrievable by their identifier)

Availability flags. Common values: ["present"] (verbatim), ["pending_refresh"] (snapshot stale), ["archived"] (deprecated source). Multi-flag arrays allowed for compound states.

Example: ["present"]

Additional fields

Compliance + academic + cryptographic standards.

09_pipeline_versionstring | nullnullable

Standard: SOC 2 Type 2 CC8.1 (change management)

Git commit SHA of the ingestion code when the response builder supplies it. It may be null and does not by itself attest to the source data or an individual fact.

Example: "abc1234"

10_doistring | nullnullable

Standard: ICMJE academic citation + FAIR F1 (persistent identifier)

Reserved for a persistent archival DOI for the methodology version. Currently always null — no DOI is minted at this time.

Example: null

11_licensestring | nullnullable

Standard: FAIR R1.1 (data are released with a clear and accessible data usage license)

SPDX identifier for redistribution rights. Federal sources (CMS, OIG, HRSA, BLS, BEA, Census) use US-Government-Works (public domain per 17 USC §105). Fonteum-derived datasets use CC-BY-4.0. Sources we don't recognize get null — caller can override.

Example: "US-Government-Works"

12_coverage_period_startstring | null (ISO-8601)nullable

Standard: HIPAA §164.312(c)(1) (integrity controls require knowing data range)

ISO-8601 date when the upstream source first started publishing this kind of data. Backstops the snapshot date with the source's own inception.

Example: "2007-09-15"

13_coverage_period_endstring | "ongoing" | nullnullable

Standard: HIPAA §164.312(c)(1)

ISO-8601 end date OR the literal "ongoing" for live sources. Future deprecated sources would set explicit end dates.

Example: "ongoing"

14_slsa_provenance_urlstring | nullnullable

Standard: SLSA Build Level 3 (cryptographic check of artifact origin)

Reserved URL for a build-provenance artifact when one is actually published. It is nullable; a URL applies to the identified build artifact and is not a signature on each data fact.

Example: null

Backward compatibility

Treat provenance fields as nullable and optional.

Consumers must feature-detect the provenance object and tolerate null or absent fields. Source- and endpoint-specific builders do not guarantee all fourteen keys. The TypeScript schema references live in the central ProvenanceContract interface in src/mcp/types.ts + the ProvenancePayload interface in src/lib/events/types.ts; runtime responses remain authoritative for actual availability.

Phase roadmap

Schema support does not imply field coverage.

Current schema: up to fourteen response- or record-level fields; actual keys and values vary by route and source.
Persistent identifiers: _doi remains null because Fonteum has not minted a DOI.
Build provenance: _slsa_provenance_url remains null unless a concrete published artifact URL is supplied.
Signature scope: no provenance fact currently links deterministically to a signature.