Schema Reference

Knowledge-graph schema

The knowledge graph is part of a federated composite (graphomics) with discipline-specific constituents. Discover the live schema at runtime with the get_schema and list_databases MCP tools.

The primary constituent, micromap, uses these node labels:

text

Analysis, Assertion, BodySite, Compound, Disease, Drug, DrugClass,
Experiment, Gene, Metabolite, Paper, Pathway, Protein, Study, Taxon

Metabolites are stored under the Compound label — query :Compound.

Relationship types:

text

ABOUT, ASSERTED, ASSOCIATED_WITH_DISEASE, BELONGS_TO_CLASS, EFFECTIVE_AGAINST,
ENCODED_BY, ENGAGES, HAS_ANALYSIS, HAS_PARENT, IMPLICATED_IN, INVESTIGATED_FOR,
LINKED_TO_DISEASE, MENTIONED_IN, OBJECT, PARTICIPATES_IN, PROCESSES, PRODUCES,
SUBJECT, SUPERSEDED_BY, TARGETS, UTILIZES

Provenance contracts

See Provenance & write-back for how these fit together.

Assertion

An Assertion is a subject → predicate → object claim with a confidence and an organization scope. Fields:

Field	Type	Notes
`predicate`	string	The relationship being asserted.
`subject`	`{label, key_field, value}`	The subject entity reference.
`object`	`{label, key_field, value}`	The object entity reference.
`confidence`	float	Confidence in the claim.
`direction`	string	Optional direction/sign.
`evidence_refs`	string[]	Evidence pointers (workflow ids, citations, statistics).
`asserted_at`	datetime	When the assertion was made.
`valid_from`	datetime	Start of validity window.
`valid_to`	datetime \| null	End of validity window (open if null).
`organization_id`	string	Owning organization.
`analysis_id`	string	The Analysis that produced it.
`supersedes`	string[]	Assertion ids this one replaces.

The Assertion id is deterministic — sha256(analysis_id | subject | predicate | object) — so recording the same finding twice is idempotent.

Decision

A Decision records the action that produced a finding. Fields: id, tool, action_type, occurred_at, summary, rationale, evidence_refs, actor_user, actor_org, role, organization_id, and resolution counts (resolved_count, unresolved_count, ambiguous_count).

DecisionEvent (ingest contract)

Ingest a decision over REST at POST /api/v1/provenance/decisions:

text

DecisionEvent {
  id                          string   (required)
  tool                        string   (nexus | workbench | mapforge)
  action_type                 string   (target_rationale | committee_gate |
                                         pipeline_run | hypothesis_verdict | data_contribution)
  decision_outcome            string   (supported | refuted | pass | fail | approved | merged)
  occurred_at                 string   (ISO-8601, required)
  summary                     string   (required)
  rationale                   string
  evidence_refs               string[]
  actor_user                  string
  actor_org                   string
  role                        string   (ceo | scientist | service)
  entity_tags                 string[] (Disease name_normalized or Taxon taxon_id)
  supersedes                  string[]
  recorded_by_analysis_ids    string[]
  context_snapshot            object?
  source_native_id            string
}

organization_id is not a request field — it is derived from your API key.

Ingest returns:

json

{
  "id": "...",
  "organization_id": "...",
  "entity_tags_matched": [],
  "entity_tags_unmatched": [],
  "supersedes_linked": [],
  "recorded_links_created": []
}

record-finding payload (MCP)

provenance_record_finding writes a full Experiment → Analysis → Assertion chain in one call:

text

experiment  { id, title?, nexus_ref?, started_at?, actor_user?, actor_org? }
analysis    { id, method?, occurred_at, summary?, model?, confidence? }
assertions  [ { subject:{label,key_field,value}, predicate, object:{label,key_field,value},
                confidence, direction?, asserted_at?, valid_from?, valid_to?,
                evidence_refs?, supersedes? } ]
organization_id
decision_ids?

Lineage response

POST /api/v1/provenance/lineage (and the provenance_lineage MCP tool) return:

json

{
  "entity": "...",
  "as_of": null,
  "paths": [
    {
      "experiment": {},
      "analysis":   {},
      "assertion":  {},
      "subject":    {},
      "object":     {},
      "decisions":  []
    }
  ],
  "count": 0
}