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
This commit is contained in:
parent
2b1706559b
commit
072a7fa550
30 changed files with 1896 additions and 264 deletions
9
contracts/MIGRATIONS.md
Normal file
9
contracts/MIGRATIONS.md
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
# Snapshot and manifest migrations
|
||||
|
||||
## 0.1 — frozen 2026-10-12
|
||||
|
||||
This is the first supported `schemaVersion`. The seed draft omitted `claims`, required relation `sourceRefs`, manifest `schemaVersion`, `relationLabels`, and `factPolicy`. Those documents were edited in place. There is no 0.0 reader.
|
||||
|
||||
`content_explorer.contract.SUPPORTED_VERSIONS` accepts only `0.1`. A document with any other version fails validation. A later version must add a named migrator, for example `migrate_0_1_to_0_2`, and must not guess missing rights or claims.
|
||||
|
||||
Display text on an entity is not a second source of truth. A `tldr` claim with `status: asserted` is the statement the renderer prefers to show. `status: unknown` records that the field was considered and is not known.
|
||||
12
contracts/SNAPSHOT.md
Normal file
12
contracts/SNAPSHOT.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# Snapshot format 0.1
|
||||
|
||||
Normative files:
|
||||
|
||||
- `contracts/snapshot.schema.json` — entity, relation, source, and claim document.
|
||||
- `contracts/manifest.schema.json` — presentation. Kind names, facet names, and relation wording live here.
|
||||
- `contracts/MIGRATIONS.md` — version gate.
|
||||
- `contracts/fact-policy.md` — missing, unknown, and contradiction.
|
||||
|
||||
Identifiers for entities are `urn:ce:<dataspace>:<kind>:<key>`. The same key in another dataspace is a different entity. Relation ids are local to the snapshot.
|
||||
|
||||
A published example must contain at least three kinds and eight entities. `scripts/validate_fixtures.py` enforces that, plus the schema, dangling references, duplicate ids, missing sources, and cycles on `acyclicPredicates` only.
|
||||
19
contracts/fact-policy.md
Normal file
19
contracts/fact-policy.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
# Fact policy v0.1
|
||||
|
||||
A claim is a statement about one entity field. It is not a proof. The snapshot keeps every claim. The manifest `factPolicy` only decides what a display may show.
|
||||
|
||||
| Situation | Claim shape | `resolve_claims` state |
|
||||
|---|---|---|
|
||||
| No claim for that key | absent | `missing` |
|
||||
| The field was checked and has no value | `status: unknown` | `unknown` |
|
||||
| One asserted value | `status: asserted` | `present` |
|
||||
| The holder asked not to display it | `status: withheld` | `withheld` |
|
||||
| Two asserted values | both `status: asserted` | `contradicted` |
|
||||
|
||||
Policies when values disagree:
|
||||
|
||||
- `show-all` returns every asserted value and state `contradicted`.
|
||||
- `withhold` returns no values and state `contradicted`.
|
||||
- `preferred` returns the single claim with `preferred: true`. If none or more than one is marked, it returns no values and state `contradicted`.
|
||||
|
||||
Absence is not the same as unknown, and unknown is not the same as false. A relation with no `sourceRefs` is invalid. It is not stored as an unsourced fact. Conflicting claims stay in the snapshot either way. The policy does not delete them.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
{
|
||||
"id": "systems-thinking",
|
||||
"home": {
|
||||
"heading": "Explore systems thinking",
|
||||
"heading": "Explore Systems Thinking",
|
||||
"featuredKinds": [
|
||||
"concept",
|
||||
"person",
|
||||
|
|
@ -11,42 +11,97 @@
|
|||
},
|
||||
"navigation": [
|
||||
{
|
||||
"label": "Explore",
|
||||
"label": "Browse",
|
||||
"kinds": [
|
||||
"concept",
|
||||
"method",
|
||||
"person",
|
||||
"publication",
|
||||
"person"
|
||||
"method"
|
||||
]
|
||||
}
|
||||
],
|
||||
"kindViews": {
|
||||
"concept": {
|
||||
"facets": [
|
||||
"discipline",
|
||||
"tradition"
|
||||
],
|
||||
"columns": [
|
||||
"name",
|
||||
"tldr",
|
||||
"tags"
|
||||
],
|
||||
"facets": [
|
||||
"tags"
|
||||
]
|
||||
}
|
||||
},
|
||||
"relationLabels": {
|
||||
"influences": {
|
||||
"forward": "Influences",
|
||||
"inverse": "Influenced by"
|
||||
},
|
||||
"discusses": {
|
||||
"forward": "Discusses",
|
||||
"inverse": "Discussed in"
|
||||
"person": {
|
||||
"columns": [
|
||||
"name",
|
||||
"tldr",
|
||||
"tags"
|
||||
],
|
||||
"facets": [
|
||||
"tags"
|
||||
]
|
||||
},
|
||||
"publication": {
|
||||
"columns": [
|
||||
"name",
|
||||
"tldr",
|
||||
"tags"
|
||||
],
|
||||
"facets": [
|
||||
"tags"
|
||||
]
|
||||
},
|
||||
"method": {
|
||||
"columns": [
|
||||
"name",
|
||||
"tldr",
|
||||
"tags"
|
||||
],
|
||||
"facets": [
|
||||
"tags"
|
||||
]
|
||||
}
|
||||
},
|
||||
"panels": [
|
||||
"summary",
|
||||
"relations",
|
||||
"evidence"
|
||||
"evidence",
|
||||
"claims"
|
||||
],
|
||||
"schemaVersion": "0.1",
|
||||
"factPolicy": "show-all",
|
||||
"relationLabels": {
|
||||
"represented-by": {
|
||||
"forward": "Represented by",
|
||||
"inverse": "Represents"
|
||||
},
|
||||
"scopes": {
|
||||
"forward": "Scopes",
|
||||
"inverse": "Scoped by"
|
||||
},
|
||||
"associated-with": {
|
||||
"forward": "Associated with",
|
||||
"inverse": "Associated with"
|
||||
},
|
||||
"authored-by": {
|
||||
"forward": "Authored by",
|
||||
"inverse": "Authored"
|
||||
},
|
||||
"related-to": {
|
||||
"forward": "Related to",
|
||||
"inverse": "Related to"
|
||||
},
|
||||
"models": {
|
||||
"forward": "Models",
|
||||
"inverse": "Modeled by"
|
||||
},
|
||||
"explores": {
|
||||
"forward": "Explores",
|
||||
"inverse": "Explored by"
|
||||
}
|
||||
},
|
||||
"acyclicPredicates": [
|
||||
"authored-by"
|
||||
],
|
||||
"theme": {
|
||||
"accent": "indigo"
|
||||
|
|
|
|||
73
contracts/manifest.schema.json
Normal file
73
contracts/manifest.schema.json
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://content-explorer.local/schemas/manifest-0.1.json",
|
||||
"title": "Content Explorer dataspace manifest v0.1",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["schemaVersion", "id", "home", "navigation", "kindViews", "panels", "relationLabels", "factPolicy"],
|
||||
"properties": {
|
||||
"schemaVersion": {"const": "0.1"},
|
||||
"id": {"type": "string", "pattern": "^[a-z0-9-]+$"},
|
||||
"home": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["heading", "featuredKinds"],
|
||||
"properties": {
|
||||
"heading": {"type": "string", "minLength": 1},
|
||||
"featuredKinds": {"type": "array", "items": {"type": "string"}, "minItems": 1}
|
||||
}
|
||||
},
|
||||
"navigation": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["label", "kinds"],
|
||||
"properties": {
|
||||
"label": {"type": "string"},
|
||||
"kinds": {"type": "array", "items": {"type": "string"}, "minItems": 1}
|
||||
}
|
||||
}
|
||||
},
|
||||
"kindViews": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["columns", "facets"],
|
||||
"properties": {
|
||||
"columns": {"type": "array", "items": {"type": "string"}, "minItems": 1},
|
||||
"facets": {"type": "array", "items": {"type": "string"}}
|
||||
}
|
||||
}
|
||||
},
|
||||
"panels": {
|
||||
"type": "array",
|
||||
"items": {"enum": ["summary", "relations", "evidence", "claims"]}
|
||||
},
|
||||
"relationLabels": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["forward", "inverse"],
|
||||
"properties": {
|
||||
"forward": {"type": "string"},
|
||||
"inverse": {"type": "string"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"acyclicPredicates": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"}
|
||||
},
|
||||
"factPolicy": {"enum": ["show-all", "preferred", "withhold"]},
|
||||
"theme": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["accent"],
|
||||
"properties": {"accent": {"type": "string"}}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -1,63 +1,33 @@
|
|||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"title": "Content Explorer compact snapshot v0.1",
|
||||
"$id": "https://content-explorer.local/schemas/snapshot-0.1.json",
|
||||
"title": "Content Explorer snapshot v0.1",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"schemaVersion",
|
||||
"dataspace",
|
||||
"kinds",
|
||||
"entities",
|
||||
"relations",
|
||||
"sources"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"required": ["schemaVersion", "dataspace", "kinds", "entities", "relations", "sources", "claims"],
|
||||
"properties": {
|
||||
"schemaVersion": {
|
||||
"const": "0.1"
|
||||
},
|
||||
"schemaVersion": {"const": "0.1"},
|
||||
"dataspace": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"title",
|
||||
"description"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "title", "description"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string"
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"description": {
|
||||
"type": "string"
|
||||
}
|
||||
"id": {"type": "string", "pattern": "^[a-z0-9-]+$"},
|
||||
"title": {"type": "string", "minLength": 1},
|
||||
"description": {"type": "string", "minLength": 1}
|
||||
}
|
||||
},
|
||||
"kinds": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"label",
|
||||
"plural"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "label", "plural"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string"
|
||||
},
|
||||
"label": {
|
||||
"type": "string"
|
||||
},
|
||||
"plural": {
|
||||
"type": "string"
|
||||
},
|
||||
"facets": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
"id": {"type": "string", "pattern": "^[a-z0-9-]+$"},
|
||||
"label": {"type": "string"},
|
||||
"plural": {"type": "string"}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
|
@ -65,48 +35,22 @@
|
|||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"kindId",
|
||||
"title",
|
||||
"tldr",
|
||||
"summary",
|
||||
"sourceRefs"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "kindId", "title", "tldr", "summary", "sourceRefs"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string"
|
||||
},
|
||||
"kindId": {
|
||||
"type": "string"
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"tldr": {
|
||||
"type": "string"
|
||||
},
|
||||
"summary": {
|
||||
"type": "string"
|
||||
},
|
||||
"tags": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"properties": {
|
||||
"type": "object"
|
||||
},
|
||||
"sourceRefs": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"asOf": {
|
||||
"type": "string",
|
||||
"format": "date"
|
||||
"id": {"type": "string", "pattern": "^urn:ce:[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+$"},
|
||||
"kindId": {"type": "string"},
|
||||
"title": {"type": "string"},
|
||||
"tldr": {"type": "string"},
|
||||
"summary": {"type": "string"},
|
||||
"aliases": {"type": "array", "items": {"type": "string"}},
|
||||
"tags": {"type": "array", "items": {"type": "string"}},
|
||||
"properties": {"type": "object"},
|
||||
"sourceRefs": {"type": "array", "items": {"type": "string"}},
|
||||
"claimRefs": {"type": "array", "items": {"type": "string"}},
|
||||
"asOf": {"type": "string", "format": "date"},
|
||||
"state": {
|
||||
"enum": ["present", "missing", "unknown", "redacted", "stale", "contradicted", "not-applicable"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -115,63 +59,52 @@
|
|||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"predicate",
|
||||
"from",
|
||||
"to"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "predicate", "from", "to", "sourceRefs"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string"
|
||||
},
|
||||
"predicate": {
|
||||
"type": "string"
|
||||
},
|
||||
"from": {
|
||||
"type": "string"
|
||||
},
|
||||
"to": {
|
||||
"type": "string"
|
||||
},
|
||||
"sourceRefs": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
"id": {"type": "string"},
|
||||
"predicate": {"type": "string", "pattern": "^[a-z0-9-]+$"},
|
||||
"from": {"type": "string"},
|
||||
"to": {"type": "string"},
|
||||
"sourceRefs": {"type": "array", "items": {"type": "string"}, "minItems": 1},
|
||||
"asOf": {"type": "string", "format": "date"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"sources": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"id",
|
||||
"uri",
|
||||
"title",
|
||||
"license"
|
||||
],
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "uri", "title", "license"],
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string"
|
||||
},
|
||||
"uri": {
|
||||
"type": "string"
|
||||
},
|
||||
"title": {
|
||||
"type": "string"
|
||||
},
|
||||
"license": {
|
||||
"type": "string"
|
||||
},
|
||||
"attribution": {
|
||||
"type": "string"
|
||||
}
|
||||
"id": {"type": "string"},
|
||||
"uri": {"type": "string"},
|
||||
"title": {"type": "string"},
|
||||
"license": {"type": "string"},
|
||||
"attribution": {"type": "string"},
|
||||
"retrievedAt": {"type": "string", "format": "date"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"claims": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "subjectId", "key", "status", "evidenceRefs"],
|
||||
"properties": {
|
||||
"id": {"type": "string"},
|
||||
"subjectId": {"type": "string"},
|
||||
"key": {"type": "string"},
|
||||
"value": {},
|
||||
"status": {"enum": ["asserted", "unknown", "contested", "withheld"]},
|
||||
"preferred": {"type": "boolean"},
|
||||
"evidenceRefs": {"type": "array", "items": {"type": "string"}, "minItems": 1},
|
||||
"observedAt": {"type": "string", "format": "date"}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue