Graph model

The model in one paragraph

Schema.ai is a property graph with reified assertions. Entities are the nodes — metrics, settings, behaviors, components. Edges are typed, directed links between entities that make relationships traversable. Claims are the truth-bearing records: each one is a reified assertion about a subject entity, carrying its own evidence, applicability scope, epistemic status, and time metadata. Edges never assert anything on their own authority — every edge cites the claims that ground it (claim_refs). The corpus is an append-only event log (assert / retract / supersede), so the graph at any moment is a projection of its history, and nothing is ever silently deleted.

In knowledge-graph terms: claims are n-ary relations in the style of Wikidata statements or RDF-star — a core subject–predicate–object triple promoted to a first-class node so that qualifiers (our guards), references (our evidence), and temporal validity (our knowledge time and version applicability) can attach to the assertion itself. The graph is open-world by default — absence of a record implies nothing — except where an inventory is declared complete, which enables closed-world absence answers ("this metric does not exist in this version").

The product principle shaping all of it: Schema returns knowledge building blocks plus how to interpret them, not finished answers. Every structure below exists to keep those blocks precise, attributable, and honestly scoped.

Nodes: entities

An Entity is a stable, linkable handle for something operators name: it has an id, an entity_type, a title, alternate names (the alias surface lexical retrieval matches against), and a description. Entities carry no truth about behavior — that lives in claims about them.

Edges: typed entity relationships

An EntityEdge is a directed, typed link between two entities with a human-readable description and — critically — claim_refs: the claims that establish the relationship. Edges are for traversal ("what observes this behavior?", "what bounds this parameter?"); claims are for truth. An edge without a grounding claim is a modeling error.

The edge-type vocabulary grows as new relationship shapes are promoted; each addition must define its direction and semantics here.

Claims: reified assertions

A Claim is the unit of knowledge. Its core is a subject–predicate–object triple: the subject is an entity reference, the predicate is drawn from a controlled vocabulary, and the object is structured data (not prose) — a metric type, a default value, a formula. Around that core:

• statement — the canonical human-readable sentence. Statement fidelity is a hard rule: exact tokens, source specifics preserved, no attribution scaffolding (metadata carries attribution exactly once).
• evidence — pinned citations into snapshotted sources, each with a role, strength, kind, and extraction method, plus a locator (path and line range). Claims cite spans, not documents.
• applies_to — product, version range (tags, introduced_in/removed_in, channel), and conditions. Version applicability is deliberately distinct from freshness: a claim pinned to v0.23.0 does not decay because time passes; it stops applying when the version scope no longer matches.
• guards — structured applicability dimensions that make scope queryable rather than buried in prose.
• knowledge_time — when the fact was recorded and last verified, with explicit precision.
• freshness_policy — review and staleness windows driving the freshness state machine.
• does_not_establish — explicit negative scope: adjacent conclusions the claim must not be stretched to support. This is the anti-overreach field, and it is served, not internal.
• establishment_class, status, confidence — the epistemic triple: how the fact is established, how far verification has gotten, and how strong the evidence is.

Events: the append-only corpus log

Records enter the corpus wrapped in events. Nothing is edited in place from a consumer's point of view: corrections arrive as supersede events, withdrawals as retract events, and the serving stores are projections of the event log at a pinned corpus snapshot id.

Coverage: topics, availability, gaps

Topics are the slice objects: named groupings of entities and claims that carry coverage meaning ("prefix cache effectiveness"). Topics declare gaps — known missing knowledge is a first-class record, not silence. Availability records inventory what exists on a surface at a version, independent of which members have promoted claims.

Sources and snapshots

Every citation resolves to a pinned snapshot: a content-hashed copy of a source at a specific tag, commit, or retrieval date. Claims never cite live URLs. Source records carry type, authority, and relationship so consumers can weigh provenance.

The extraction and review pipeline

Claims are not written directly. A pinned snapshot goes through an isolated extraction run producing candidate claims — review substrate that never serves canonically. Candidates carry the same core anatomy plus a catalog_context: the extractor's categorization of what kind of claim this is and how consumers would reach it. Review decisions are recorded per candidate; accepted candidates are promoted into assertion events with full evidence locators.

Scenarios: documented question shapes

Query scenarios are product records documenting an operator question shape end to end — verbatim phrasings, the nuance targeted, what Schema does with it, and refs into the claims, topics, and eval fixtures that ground it.

Relation to standard knowledge-graph theory

For readers arriving from RDF/OWL or property-graph practice: entities and typed edges are the ordinary property-graph layer. Claims are where the model diverges from a plain triple store — a triple like prefix_cache_queries has_metric_type counter is never asserted bare; it is reified so the assertion itself can carry qualifiers (guards ≈ Wikidata qualifiers), references (evidence ≈ Wikidata references), modality (establishment class — enforced/advisory/derived is a modality distinction logic would express as necessity vs. normativity vs. reported fact), and temporal scope (version applicability, distinct from wall-clock freshness). The predicate vocabulary is deliberately small and closed at promotion time, in the spirit of a curated ontology rather than open information extraction; the extraction layer's kind/scope/register labels are a folksonomy stage that feeds ontology growth under review. Provenance follows W3C-PROV instincts (every assertion traces to a pinned snapshot span) without adopting the full vocabulary.