This is a proposed knowledge contract. The implemented documentation validator covers the public identity and discovery records described below. It does not implement a database, ingestion workflow, or release approval system.
All paths are relative to org/apps/developers/.
| Owner | Path | Published representation |
|---|---|---|
| Jurisdiction identity | public/stormtrust-data/missouri/jurisdictions.json |
JSON and jurisdiction reference |
| Exact Missouri source rows | public/stormtrust-data/missouri/census-2020-missouri.txt |
Census subset |
| Discovery, evidence, scope, gaps | public/stormtrust-data/missouri/research.json |
JSON, sources, and scope |
| Structural validation and rendering | bin/missouri-records.ts |
Enforced by check:missouri |
These files are public. They contain no private correspondence, credentials, agreements, or individual parcel records. Restricted evidence must remain in an authorized store and stay out of public HTML, Markdown, JSON, and search outputs. Discovery exclusion and content-use signals are not access control.
The registry uses Census five-digit GEOIDs and us-mo-<geoid> record IDs.
Endpoint URLs and display names are attributes, not identities. Source candidates
can reference several jurisdictions; several sources can reference one jurisdiction.
jurisdictions.json owns the identity vintage, download provenance, national
file checksum, retained-subset checksum, scope, and all 115 identities.
Research status belongs to research.json, not to geographic identity.
research.json owns proposed capability and layer decisions, cohort selection,
publishers, timestamped evidence, source candidates, and open gaps. Each candidate
links publisher, jurisdictions, layers, evidence, responsible role, and workflow.
null means not verified. An empty cohort with selection-pending means no cohort
has been selected. No discovery record means not assessed by this corpus.
not-observed does not mean a production system is absent.
The discovery schema permits discovered, in-review, and unresolved research
states. Access and redistribution reviews permit unknown, pending, and
denied. Approval, implementation, and release references remain null in this
schema. Add a separately reviewed, versioned contract before representing an
approved or operational source; do not bypass validation to display success.
The validator rejects unknown fields, duplicate IDs, Census identity mismatches, broken cross-record references, missing evidence metadata, and inconsistent cohort selection. It detects stale generated pages. It cannot establish the truth of prose, verify permission, or prove source freshness. Review each material new claim and its evidence before merging.
A reviewed source dossier extends discovery with these requirements:
| Section | Required evidence |
|---|---|
| Identity and scope | Publisher, dataset, jurisdictions, layers, official landing page, and exclusions. |
| Native interface | Actual service or file format, metadata, supported operations, pagination or delivery rules, authentication, limits, and errors. |
| Rights and handling | Decisions for acquisition, storage, transformation, display, redistribution, and AI use where applicable; attribution, retention, restrictions, approver, and scope. |
| Native schema | Field names and types, units, code dictionaries, null meanings, geometry, coordinate reference system, and schema revision. |
| Mapping | Source-to-canonical fields, transformations, joins, omissions, version, and tests. |
| Acquisition | Workflow, owner, prerequisites, human gates, verified checkpoint, retry and stop conditions. |
| Acceptance | Count basis, geographic scope, duplicate rules, required attributes, geometry checks, quality tolerances, and exceptions. |
| Lifecycle | Publisher cadence evidence, local freshness policy, next review due, replacement, and dependent capabilities. |
Preserve a native specification when available. Do not invent an upstream OpenAPI document for a file download or ArcGIS service. Observed behavior is not automatically a publisher guarantee.
| Record | Owns | Relationships |
|---|---|---|
| Capability | User outcome and acceptance | Required layers and delivery surfaces. |
| Jurisdiction | Geographic identity | Sources, layers, and coverage scope. |
| Publisher and source | Responsible institution and dataset contract | Evidence, access review, schemas, and jurisdictions. |
| Layer | Meaning and coverage requirements | Capabilities and source contracts. |
| Native schema and mapping | Native meaning and normalization | Source revision, canonical fields, transformations, tests. |
| Workflow and pipeline contract | Permissions, checkpoints, expected inputs and outputs | Source, owner, actual implementation when available. |
| Release | Immutable data snapshot and publication decision | Source vintages, mapping revisions, validation, lineage. |
| Observation | What a check established at a stated time | Subject, method, contract revision, result, limits. |
| Decision or gap | Approved rationale or unresolved question | Affected record, owner, evidence, next action. |
These are relationships for future records, not empty files to create today. A source spanning counties has one contract. County references link to it. A release can combine sources with different vintages; retain each lineage path.
The following vocabulary is proposed for contracts beyond discovery version 1. One dimension never establishes another.
| Dimension | States |
|---|---|
| Research | Not assessed; candidate found; verified; unresolved. |
| Access review | Unknown; pending; approved for stated use; denied; expired. |
| Contract | Draft; reviewed; approved; superseded. |
| Implementation | Not linked; proposed; implemented; verified. |
| Data release | Not observed; acquired; quarantined; validated; published. |
| Operations | Not monitored; never run; healthy; stale; failing; unknown. |
For every material claim, retain an evidence ID, authoritative URL or permitted artifact reference, retrieval or observation time, method, revision or hash when captured, reviewer or responsible role, and limitations. Preserve conflicts and failed retrievals with their actual failure modes. A page-level review date does not reverify every claim.
| Time field | Meaning |
|---|---|
published_at |
Publisher or StormTrust publication time; identify which. |
retrieved_at |
When evidence or bytes were obtained. |
data_as_of |
Vintage represented by the underlying data. |
ingested_at |
When an acquisition entered the system. |
validated_at |
When checks ran against a specific artifact. |
last_success_at |
Latest observed successful execution. |
review_due_at |
Deadline under an approved evidence-review policy. |
Retain these dates as evidence. Avoid vague claims such as “current” without a vintage and policy. Until review intervals are approved, record them as unknown and recheck evidence before a dependent decision.
| Term | Meaning |
|---|---|
| Jurisdiction | Geographic coverage unit; not necessarily the dataset publisher. |
| Parcel identifier | Native identifier whose scope and persistence require source evidence. |
| Assessment account | Administrative assessment identity; not assumed one-to-one with a parcel. |
| Source record | One native record; not necessarily one property, parcel, address, or building. |
| Snapshot | Dataset contents at a declared source revision or acquisition boundary. |
| Release | Versioned artifact with validation, lineage, and a publication decision. |
| Mapping | Versioned interpretation of native fields and transformations. |
| Provenance | Evidence connecting a value to its source, vintage, and transformations. |
| Coverage | Satisfaction of a declared jurisdiction, layer, and release contract. |
| Freshness | Data vintage evaluated against an approved source-specific policy. |
| Checkpoint | Evidence-backed workflow state from which an authorized action can resume. |
Define property, building, address, recorded instrument, and their joins before exposing them as interchangeable identities in a product.