docs: migrate to v1.2 ontology vocabulary

README.md

@@ -96,28 +96,28 @@ async def main():
 asyncio.run(main())
 ```
 
-### 3. Define a schema (optional)
+### 3. Define an ontology (optional)
 
 ```python
-from graphrag_sdk import GraphSchema, EntityType, RelationType
+from graphrag_sdk import Ontology, Entity, Relation
 
-schema = GraphSchema(
+ontology = Ontology(
     entities=[
-        EntityType(label="Person", description="A human being"),
-        EntityType(label="Organization", description="A company or institution"),
-        EntityType(label="Location", description="A geographic location"),
+        Entity(label="Person", description="A human being"),
+        Entity(label="Organization", description="A company or institution"),
+        Entity(label="Location", description="A geographic location"),
     ],
     relations=[
-        RelationType(label="WORKS_AT", description="Is employed by", patterns=[("Person", "Organization")]),
-        RelationType(label="LOCATED_IN", description="Is situated in", patterns=[("Organization", "Location")]),
+        Relation(label="WORKS_AT", description="Is employed by", patterns=[("Person", "Organization")]),
+        Relation(label="LOCATED_IN", description="Is situated in", patterns=[("Organization", "Location")]),
     ],
 )
 
 async with GraphRAG(
     connection=ConnectionConfig(host="localhost", graph_name="my_graph"),
     llm=LiteLLM(model="openai/gpt-5.5"),
     embedder=LiteLLMEmbedder(model="openai/text-embedding-3-large", dimensions=256),
-    schema=schema,
+    ontology=ontology,
 ) as rag:
     ...  # ingest / completion as above
 ```

docs/api-reference.mdx

@@ -11,7 +11,7 @@ Complete reference for all public classes and methods exported by `graphrag_sdk`
 - [Connection](#connection)
 - [Providers](#providers)
 - [Data Models](#data-models)
-- [Schema](#schema)
+- [Ontology](#ontology)
 - [Ingestion Strategies](#ingestion-strategies)
 - [Ingestion Pipeline](#ingestion-pipeline)
 - [Retrieval Strategies](#retrieval-strategies)
@@ -37,7 +37,7 @@ GraphRAG(
     connection: FalkorDBConnection | ConnectionConfig,
     llm: LLMInterface,
     embedder: Embedder,
-    schema: GraphSchema | None = None,
+    ontology: Ontology | None = None,
     retrieval_strategy: RetrievalStrategy | None = None,
 )
 ```
@@ -47,10 +47,10 @@ GraphRAG(
 | `connection` | `FalkorDBConnection \| ConnectionConfig` | required | Database connection or config to create one |
 | `llm` | `LLMInterface` | required | LLM provider |
 | `embedder` | `Embedder` | required | Embedding provider |
-| `schema` | `GraphSchema \| None` | `None` | Schema constraints for extraction (empty = unconstrained) |
+| `ontology` | `Ontology \| None` | `None` | Ontology constraints for extraction (empty = unconstrained) |
 | `retrieval_strategy` | `RetrievalStrategy \| None` | `None` | Default retrieval strategy (uses `MultiPathRetrieval` if None) |
 
-**Public attributes:** `llm`, `embedder`, `schema`, `graph_store`, `vector_store`
+**Public attributes:** `llm`, `embedder`, `ontology`, `graph_store`, `vector_store`
 
 ### ingest()
 
@@ -522,46 +522,46 @@ Deterministic entity ID from normalized name and optional type. When `entity_typ
 
 ---
 
-## Schema
+## Ontology
 
 ```python
-from graphrag_sdk import GraphSchema, EntityType, RelationType
+from graphrag_sdk import Ontology, Entity, Relation, Attribute
 ```
 
-### EntityType
+### Entity
 
 ```python
-class EntityType(DataModel):
+class Entity(DataModel):
     label: str                            # e.g. "Person"
     description: str | None = None        # Helps LLM understand what to extract
-    properties: list[PropertyType] = []   # Optional property definitions
+    properties: list[Attribute] = []   # Optional property definitions
 ```
 
-### RelationType
+### Relation
 
 ```python
-class RelationType(DataModel):
+class Relation(DataModel):
     label: str                            # e.g. "WORKS_AT"
     description: str | None = None
     patterns: list[tuple[str, str]] = []  # Allowed (source_label, target_label) pairs
+    properties: list[Attribute] = []      # Optional property definitions
 ```
 
-### PropertyType
+### Attribute
 
 ```python
-class PropertyType(DataModel):
+class Attribute(DataModel):
     name: str
     type: str = "STRING"                  # STRING, INTEGER, FLOAT, BOOLEAN, DATE, LIST
     description: str | None = None
-    required: bool = False
 ```
 
-### GraphSchema
+### Ontology
 
 ```python
-class GraphSchema(DataModel):
-    entities: list[EntityType] = []
-    relations: list[RelationType] = []
+class Ontology(DataModel):
+    entities: list[Entity] = []
+    relations: list[Relation] = []
 ```
 
 ---
@@ -593,7 +593,7 @@ class ChunkingStrategy(ABC):
 ```python
 class ExtractionStrategy(ABC):
     @abstractmethod
-    async def extract(self, chunks: TextChunks, schema: GraphSchema, ctx: Context) -> GraphData: ...
+    async def extract(self, chunks: TextChunks, ontology: Ontology, ctx: Context) -> GraphData: ...
 ```
 
 **Built-in:**
@@ -632,7 +632,7 @@ IngestionPipeline(
     resolver: ResolutionStrategy,
     graph_store: GraphStore,
     vector_store: VectorStore,
-    schema: GraphSchema | None = None,
+    ontology: Ontology | None = None,
     embedder: Embedder | None = None,
 )
 ```

docs/configuration.mdx

@@ -269,85 +269,84 @@ Both `LiteLLMEmbedder` and `OpenRouterEmbedder` implement binary-split error rec
 
 ---
 
-## 4. GraphSchema
+## 4. Ontology
 
-`GraphSchema` defines the structure of your knowledge graph. It constrains LLM extraction and powers the pruning step that filters non-conforming data.
+`Ontology` defines the structure of your knowledge graph. It constrains LLM extraction and powers the pruning step that filters non-conforming data.
 
 ### Components
 
-**EntityType** -- defines a node type:
+**Entity** -- defines a node type:
 
 | Field         | Type                | Default       | Description                            |
 |---------------|---------------------|---------------|----------------------------------------|
 | `label`       | `str`               | --            | The node label (e.g. `"Person"`).      |
 | `description` | `str \| None`       | `None`        | Human-readable description.            |
-| `properties`  | `list[PropertyType]` | `[]`          | Expected properties on this node type. |
+| `properties`  | `list[Attribute]` | `[]`          | Expected properties on this node type. |
 
-**RelationType** -- defines a relationship type:
+**Relation** -- defines a relationship type:
 
 | Field         | Type                | Default       | Description                              |
 |---------------|---------------------|---------------|------------------------------------------|
 | `label`       | `str`               | --            | The relationship type (e.g. `"KNOWS"`).  |
 | `description` | `str \| None`       | `None`        | Human-readable description.              |
-| `properties`  | `list[PropertyType]` | `[]`          | Expected properties on this relationship.|
+| `properties`  | `list[Attribute]` | `[]`          | Expected properties on this relationship.|
 
-**PropertyType** -- defines a property on a node or relationship:
+**Attribute** -- defines a property on a node or relationship:
 
 | Field         | Type            | Default     | Description                                                  |
 |---------------|-----------------|-------------|--------------------------------------------------------------|
 | `name`        | `str`           | --          | Property name.                                               |
 | `type`        | `str`           | `"STRING"`  | Type hint: `STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`, `DATE`, `LIST`. |
 | `description` | `str \| None`   | `None`      | Human-readable description.                                  |
-| `required`    | `bool`          | `False`     | Whether the property is required.                            |
 
-### Example Schema Definition
+### Example Ontology Definition
 
 ```python
 from graphrag_sdk.core.models import (
-    EntityType, RelationType, PropertyType, GraphSchema,
+    Entity, Relation, Attribute, Ontology,
 )
 
-schema = GraphSchema(
+ontology = Ontology(
     entities=[
-        EntityType(
+        Entity(
             label="Person",
             description="A character or real person",
             properties=[
-                PropertyType(name="name", type="STRING", required=True),
-                PropertyType(name="age", type="INTEGER"),
-                PropertyType(name="occupation", type="STRING"),
+                Attribute(name="name", type="STRING", required=True),
+                Attribute(name="age", type="INTEGER"),
+                Attribute(name="occupation", type="STRING"),
             ],
         ),
-        EntityType(
+        Entity(
             label="Location",
             description="A geographical place or setting",
             properties=[
-                PropertyType(name="name", type="STRING", required=True),
-                PropertyType(name="country", type="STRING"),
+                Attribute(name="name", type="STRING", required=True),
+                Attribute(name="country", type="STRING"),
             ],
         ),
-        EntityType(
+        Entity(
             label="Organization",
             description="A company, institution, or group",
         ),
     ],
     relations=[
-        RelationType(
+        Relation(
             label="LIVES_IN",
             description="Person resides at location",
             patterns=[("Person", "Location")],
         ),
-        RelationType(
+        Relation(
             label="WORKS_FOR",
             description="Person is employed by organization",
             patterns=[("Person", "Organization")],
         ),
-        RelationType(
+        Relation(
             label="LOCATED_IN",
             description="Organization is located at a place",
             patterns=[("Organization", "Location")],
         ),
-        RelationType(
+        Relation(
             label="KNOWS",
             description="Two people know each other",
             patterns=[("Person", "Person")],
@@ -356,12 +355,12 @@ schema = GraphSchema(
 )
 ```
 
-Each `RelationType.patterns` entry is a `(source_label, target_label)` tuple.
+Each `Relation.patterns` entry is a `(source_label, target_label)` tuple.
 An empty `patterns` list means the relation is allowed between any entity types.
 
-### Open Schema Mode
+### Open Ontology Mode
 
-If no entity types or relation types are defined (empty `GraphSchema()`), the extraction operates in open-schema mode and the pruning step is skipped. This lets the LLM extract any entities and relationships it finds.
+If no entity types or relation types are defined (empty `Ontology()`), the extraction operates in open-ontology mode and the pruning step is skipped. This lets the LLM extract any entities and relationships it finds.
 
 ---
 
@@ -395,7 +394,7 @@ Larger chunks provide more context per extraction call but increase LLM token us
 | `llm`              | `LLMInterface`  | required       | LLM provider for step 2 (verify + relationship extraction). |
 | `entity_extractor` | `EntityExtractor \| None` | `None` (`GLiNERExtractor()`) | Pluggable NER backend for step 1. |
 | `coref_resolver`   | `CorefResolver \| None` | `None` | Optional coreference resolution (e.g. `FastCorefResolver()`). |
-| `entity_types`     | `list[str] \| None` | `None` (11 default types) | Custom entity types. Overridden by `schema.entities` if set. |
+| `entity_types`     | `list[str] \| None` | `None` (11 default types) | Custom entity types. Overridden by `ontology.entities` if set. |
 | `max_concurrency`  | `int \| None`   | `None` (uses LLM default) | Maximum parallel LLM calls during step 2. |
 
 **Built-in entity extractors:**
@@ -437,18 +436,18 @@ extractor = GraphExtraction(
     entity_types=["Gene", "Protein", "Disease", "Drug", "Pathway"],
 )
 
-# Or define them in the schema (takes priority)
-from graphrag_sdk import GraphSchema, EntityType
+# Or define them in the ontology (takes priority)
+from graphrag_sdk import Ontology, Entity
 
-schema = GraphSchema(entities=[
-    EntityType(label="Gene", description="A gene or genetic locus"),
-    EntityType(label="Protein", description="A protein or enzyme"),
-    EntityType(label="Disease", description="A disease or condition"),
+ontology = Ontology(entities=[
+    Entity(label="Gene", description="A gene or genetic locus"),
+    Entity(label="Protein", description="A protein or enzyme"),
+    Entity(label="Disease", description="A disease or condition"),
 ])
-rag = GraphRAG(connection=conn, llm=llm, embedder=embedder, schema=schema)
+rag = GraphRAG(connection=conn, llm=llm, embedder=embedder, ontology=ontology)
 ```
 
-Priority: `schema.entities` > `entity_types` param > defaults (Person, Organization, Technology, Product, Location, Date, Event, Concept, Law, Dataset, Method).
+Priority: `ontology.entities` > `entity_types` param > defaults (Person, Organization, Technology, Product, Location, Date, Event, Concept, Law, Dataset, Method).
 
 ### LLM Concurrency
 

docs/extraction.mdx

@@ -204,15 +204,15 @@ Entities that don't match any type (or fall below the confidence threshold) are
 
 There are three ways to define entity types, listed by priority:
 
-**1. GraphSchema entities (highest priority):**
+**1. Ontology entities (highest priority):**
 ```python
-from graphrag_sdk import GraphSchema, EntityType
+from graphrag_sdk import Ontology, Entity
 
-schema = GraphSchema(entities=[
-    EntityType(label="Gene", description="A gene or genetic locus"),
-    EntityType(label="Disease", description="A disease or condition"),
+ontology = Ontology(entities=[
+    Entity(label="Gene", description="A gene or genetic locus"),
+    Entity(label="Disease", description="A disease or condition"),
 ])
-rag = GraphRAG(connection=conn, llm=llm, embedder=embedder, schema=schema)
+rag = GraphRAG(connection=conn, llm=llm, embedder=embedder, ontology=ontology)
 # Extraction uses: ["Gene", "Disease"]
 ```
 

docs/getting-started.mdx

@@ -64,23 +64,23 @@ If you use a `.env` file, load it yourself before importing the SDK (e.g., via `
 
 ---
 
-## 5. Define a Schema
+## 5. Define an Ontology
 
-A `GraphSchema` tells the extraction pipeline which entity and relationship types to look for in your documents.
+An `Ontology` tells the extraction pipeline which entity and relationship types to look for in your documents.
 
 ```python
-from graphrag_sdk import GraphSchema, EntityType, RelationType
+from graphrag_sdk import Ontology, Entity, Relation
 
-schema = GraphSchema(
+ontology = Ontology(
     entities=[
-        EntityType(label="Person", description="A human being"),
-        EntityType(label="Organization", description="A company or institution"),
-        EntityType(label="Place", description="A geographic location"),
+        Entity(label="Person", description="A human being"),
+        Entity(label="Organization", description="A company or institution"),
+        Entity(label="Place", description="A geographic location"),
     ],
     relations=[
-        RelationType(label="WORKS_AT", description="Employment relationship"),
-        RelationType(label="LOCATED_IN", description="Geographic location"),
-        RelationType(label="KNOWS", description="Personal acquaintance"),
+        Relation(label="WORKS_AT", description="Employment relationship"),
+        Relation(label="LOCATED_IN", description="Geographic location"),
+        Relation(label="KNOWS", description="Personal acquaintance"),
     ],
 )
 ```
@@ -91,7 +91,7 @@ You can add as many entity and relationship types as your domain requires. Descr
 
 ## 6. Initialize GraphRAG
 
-Create a `GraphRAG` instance by providing a connection, LLM, embedder, and schema:
+Create a `GraphRAG` instance by providing a connection, LLM, embedder, and ontology:
 
 ```python
 from graphrag_sdk import GraphRAG, ConnectionConfig, LiteLLM, LiteLLMEmbedder
@@ -100,7 +100,7 @@ rag = GraphRAG(
     connection=ConnectionConfig(host="localhost", graph_name="my_graph"),
     llm=LiteLLM(model="azure/gpt-4.1"),
     embedder=LiteLLMEmbedder(model="azure/text-embedding-3-large", dimensions=256),
-    schema=schema,
+    ontology=ontology,
     embedding_dimension=256,  # must match your embedding model's output dimension
 )
 ```