# Parcel knowledge record contract

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.

## Canonical files

All paths are relative to `org/apps/developers/`.

| Owner                               | Path                                                     | Published representation                                                                                                                                                                |
| ----------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Jurisdiction identity               | public/stormtrust-data/missouri/jurisdictions.json       | [JSON](/stormtrust-data/missouri/jurisdictions.json) and [jurisdiction reference](/stormtrust/product/platform-and-data/missouri/jurisdictions/)                                        |
| Exact Missouri source rows          | public/stormtrust-data/missouri/census-2020-missouri.txt | [Census subset](/stormtrust-data/missouri/census-2020-missouri.txt)                                                                                                                     |
| Discovery, evidence, scope, gaps    | public/stormtrust-data/missouri/research.json            | [JSON](/stormtrust-data/missouri/research.json), [sources](/stormtrust/product/platform-and-data/missouri/sources/), and [scope](/stormtrust/product/platform-and-data/missouri/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.

## Discovery schema version 1

`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.

## Source contract before implementation

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.

## Records added as evidence exists

| 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.

## State dimensions

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. |

## Evidence and time

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.

## Glossary

| 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.