Organizing documents with an ontology

Context212's Ontology lets you model real-world things as concepts (organizations, people, incidents, …) and link documents to them with typed relations. You define the schema once, create concept instances, connect files into the graph, then filter Search and Ask by those connections.

"Find incident reports that involve a resident at the Casablanca site."

"Show contracts that reference an EU organization and were signed by a nurse."

Those queries don't rely on finding those exact words in the document body. They walk graph edges: a relation type (involves, references, signed_by) to a concept that carries attributes (facility, region, role).

Workspaces, tags, or ontology?

Ontology isn't the only way to organise documents. Workspaces are containers that isolate a team's or customer's files, and tags are flat labels that group files into collections (even across workspaces) with zero schema to design. The three compose: a file lives in one workspace, can carry several tags, and can be linked into an ontology graph.

Only workspaces are a permission boundary. Reach for the simplest layer that solves your problem. The rest of this tutorial covers ontology.

How it works

Ontology has three kinds of building blocks — not a depth limit on your schema. You can define as many concept types, concepts, and relations as you need.

Schema (define once per workspace ontology)
  Concept types: organization { region }, person { role }
  Relation types: references (document → organization), signed_by (document → person)

Concept instances (per workspace)
  Organization "Acme Corp" with region=EU
  Person "Alex" with role=nurse

Relations (per file or concept)
  File #42 --references--> Acme Corp
  File #42 --signed_by--> Alex

Typical workflow:

1. Adopt or define the schema: browse templates (GET /api/v1/ontology/templates), adopt into a workspace (POST /api/v1/ontology/templates/{id}/adopt), then manage concept/relation types under /api/v1/ontologies/{id}/…
2. Create concepts & link files: POST /api/v1/ontology/concepts, POST /api/v1/ontology/relations, inspect with GET /api/v1/files/{id}/ontology
3. Query by graph: filter Search/Ask with relation (and optional include_relations)

Glossary

Ontology

A named, versioned bundle of concept types and relation types. Templates (is_template=true) are starters. After adopt, the ontology is workspace-owned (workspace_id set) and fully editable. Schema edits that need a clean break use POST /api/v1/ontologies/{id}/new-version.

Concept type

A class of thing that can exist in the graph (organization, person, incident). Types are flat (not a display tree) — there is no maximum hierarchy depth for the schema. An optional parent_id exists only for attribute inheritance, not for UI hierarchy.

Each concept type carries attribute definitions:

• key — machine name (region)
• label — human-readable name
• data_type — text | number | boolean | date | select | multi_select
• select_options — required for select types
• required — whether the attribute must be set on instances

Concept

An instance of a concept type in a workspace: a concrete Organization, Person, etc., with a label and validated attributes. Concepts are first-class objects — not tied to a single file.

Relation type

A typed, directional edge definition:

• key / label / optional inverse_label
• source_concept_type_id — null means the source is a document (file); otherwise a concept of that type
• target_concept_type_id — required target concept type
• cardinality — one_to_one | one_to_many | many_to_many

Relation

A concrete edge: exactly one of source_document_id or source_concept_id, plus target_concept_id. The first relation from a document under an ontology writes an immutable document_ontology_version audit row.

Next steps