Skip to main content
tckg does not guess identity. Which nodes are values of the same fact, and which value wins, are declared by you. Declarations are time-aware: resolve applies the declaration in force at as_of (or at rules_as_of).

Request

string
required
The key nodes carry in fact_key, or a key shape */<rest> that declares every key of that shape at once (see key shapes).
string[]
required
The fields that identify one instance of the fact.
string
default:"latest_valid"
latest_valid (latest validity start wins), latest_observed (latest asserted_at wins), source_priority (first match in source_order wins), strict (two candidates is a refusal), most_specific (candidates superseded by an edge in force at valid_at are dropped, then the ones with the most applies_if conditions are the finalists: unconditional finalists answer when they agree, a conditional finalist is needs_facts until a read can pass facts).
string[]
Required for source_priority.

Response

timestamp
When the declaration took effect. Use it as rules_as_of when resolving past knowledge under this rule.
A node written with a fact_key that is not declared yet is still stored, with an undeclared_fact warning. Declare first when you can; otherwise declare later and resolve with rules_as_of.

Key shapes

When every subject has the same attribute (s_1/language, s_2/language, …), declare the shape once instead of one key per subject:
  • * stands for one leading segment, non-empty and without /. The rest after */ is matched literally and must be non-empty; it may contain /. So */language covers s_1/language but not language, /language or s_1/language/old.
  • Any other use of * (a/*, */*, *, **/x, */) is refused with TCKG_BAD_FACT_PATTERN. In the {"facts": [...]} form that item is refused with the reason in why. A single-declaration request that is refused currently returns 500 without the reason, as for every other refusal, so prefer the facts form when you need the reason.
  • For a key K at an instant T, an exact declaration of K in force at T wins, whenever it was declared. Otherwise the declaration of K’s shape in force at T applies. Otherwise K is undeclared, as before. resolve reports the policy it applied.
  • Each key is still its own fact: s_1/language and s_2/language resolve separately. The shape only shares the rule.
  • A shape is stored as written (*/language). Export writes it out under each concrete key the bundle’s nodes use, so a FactBlock reader that knows only exact keys sees the same declaration.
  • Writing a node whose key is covered by a shape gives no undeclared_fact warning.

Several at once

Send {"facts": [...]} with up to 1000 declarations (more is 400 TCKG_TOO_MANY_FACTS). They go in one transaction, so every new declaration gets the same declared_at. The response has one item per fact, in order, and the counts. Sending a declaration that is already in force changes nothing, as with a single request.
object[]
fact_key, status and, for declared and unchanged, declared_at. status is declared (new), unchanged (the same declaration was already in force) or refused (why carries the reason, such as a source_priority without source_order). A refused item leaves the others in.
integer
How many items got each status.