content-explorer/architecture/CanonicalDataModel.md

# Canonical data model — draft contract v0.1

The JSON Schema in `contracts/snapshot.schema.json` is frozen at `schemaVersion` 0.1, including claims. Producing those claims from an external source is still CONTENT-WP-0003. Display policy is `contracts/fact-policy.md`.

## Records

- `Dataspace`: namespace, version, title, description, schemaVersion, language, source policy, kind registry, navigation, view registry.
- `Entity`: ID, kindId, title, aliases, tldr, summary, tags, properties, effective time, sourceRefs, claimRefs, state.
- `Relation`: id, predicate, from/to, evidenceRefs, asOf, sourceRef; direction preserved.
- `Claim`: id, subject, key or predicate, value/target, assertedBy, evidenceRefs, status, valid interval, observedAt; no mandatory scalar probability.
- `Source`: id, canonical URI, title, author/publisher, retrievedAt, publishedAt, license, attribution, contentHash.
- `Collection`: ordered set of entity IDs + editorial purpose, optionally computed from a view.
- `View`: declarative facets, columns, sorts, summary cards, panels and graph traversal policy.

## Projection semantics

A `view` never changes truth; it chooses presentation. Projected `Entity.summary` is a **display decision** (may be curated), and `Claim`s retain competing assertions. Edges without provenance can be shown as `unverified` but must not be presented as sourced fact. All counts derive from the snapshot and query state.

## Mappings versus ontology

Types such as `concept`, `person`, `organization`, `document`, `pattern`, `decision`, `problem` are example `kindId`s, not privileged ontological primitives. The core representation is open-world and domain-specific names live in the manifest. A future vocabulary layer can connect manifests to SKOS/schema.org/RDF terms when useful.

## Future-proofs

Versioned migrators (`schemaVersion`), stable source-scoped IDs, lifecycle tombstones, localizations, role/perspective-aware visibility, hierarchical collection membership, temporal relations, claim-level review state, conflict handling, event stream, and computation provenance.
Seeded repo 2026-10-12 18:28:16 +02:00			`# Canonical data model — draft contract v0.1`

Freeze the v0.1 contract and the local ingest connector. The snapshot and manifest schemas, both example dataspaces, and the shared text renderer now pass the fixture validator and the negative contract tests. JSON, NDJSON, and Markdown frontmatter publish a snapshot only when rights, identity, and references allow it. CONTENT-WP-0001 and CONTENT-WP-0003 are marked finished against those artifacts. CONTENT-WP-0000-T04 stays open. SCOPE.md and the 19:05 scope-against-intent note record the stop. Assistant: grok Assistant-Session: 01a130f1-abfb-7d71-9cd6-a8b75ec7f95a 2026-10-12 19:07:32 +02:00			The JSON Schema in `contracts/snapshot.schema.json` is frozen at `schemaVersion` 0.1, including claims. Producing those claims from an external source is still CONTENT-WP-0003. Display policy is `contracts/fact-policy.md`.
Seeded repo 2026-10-12 18:28:16 +02:00
			`## Records`

			- `Dataspace`: namespace, version, title, description, schemaVersion, language, source policy, kind registry, navigation, view registry.
			- `Entity`: ID, kindId, title, aliases, tldr, summary, tags, properties, effective time, sourceRefs, claimRefs, state.
			- `Relation`: id, predicate, from/to, evidenceRefs, asOf, sourceRef; direction preserved.
			- `Claim`: id, subject, key or predicate, value/target, assertedBy, evidenceRefs, status, valid interval, observedAt; no mandatory scalar probability.
			- `Source`: id, canonical URI, title, author/publisher, retrievedAt, publishedAt, license, attribution, contentHash.
			- `Collection`: ordered set of entity IDs + editorial purpose, optionally computed from a view.
			- `View`: declarative facets, columns, sorts, summary cards, panels and graph traversal policy.

			`## Projection semantics`

			A `view` never changes truth; it chooses presentation. Projected `Entity.summary` is a display decision (may be curated), and `Claim`s retain competing assertions. Edges without provenance can be shown as `unverified` but must not be presented as sourced fact. All counts derive from the snapshot and query state.

			`## Mappings versus ontology`

			Types such as `concept`, `person`, `organization`, `document`, `pattern`, `decision`, `problem` are example `kindId`s, not privileged ontological primitives. The core representation is open-world and domain-specific names live in the manifest. A future vocabulary layer can connect manifests to SKOS/schema.org/RDF terms when useful.

			`## Future-proofs`

			Versioned migrators (`schemaVersion`), stable source-scoped IDs, lifecycle tombstones, localizations, role/perspective-aware visibility, hierarchical collection membership, temporal relations, claim-level review state, conflict handling, event stream, and computation provenance.