Schema Registry
The schema registry defines the schema of objects that can live in your project’s knowledge graph. Every object has a type name, and the registry stores the JSON Schema, display config, and extraction hints for each type.
Concepts
Section titled “Concepts”| Concept | Description |
|---|---|
| Type | A named schema: what properties an object can have and how it behaves |
| Source | Where the type came from: schema, custom, or discovered |
| Embedding policy | Controls whether and how objects of this type are embedded for vector search |
Type sources
Section titled “Type sources”| Source | Description |
|---|---|
schema |
Installed from a schema |
custom |
Created directly by a developer |
discovered |
Proposed automatically by the extraction pipeline |
Managing types via API
Section titled “Managing types via API”List types
Section titled “List types”curl https://api.example.com/api/schema-registry/projects/<projectId> \ -H "Authorization: Bearer <token>"Get a specific type
Section titled “Get a specific type”curl https://api.example.com/api/schema-registry/projects/<projectId>/types/Person \ -H "Authorization: Bearer <token>"Get type version history
Section titled “Get type version history”curl https://api.example.com/api/schema-registry/projects/<projectId>/types/Person/versions \ -H "Authorization: Bearer <token>"Returns the persisted version history for a type, newest first. Each schema_version has one snapshot, and active is true on the version matching the current registry row. Existing types are backfilled at their current version, and a DB trigger keeps the history current automatically. Returns 404 if the type does not exist.
{ "project_id": "<projectId>", "type_name": "Person", "current_version": 3, "versions": [ { "registry_id": "<uuid>", "schema_version": 3, "json_schema": { "...": "..." }, "ui_config": { "...": "..." }, "extraction_config": { "...": "..." }, "enabled": true, "description": "A person", "namespace": null, "created_by": "<uuid>", "created_at": "2026-01-01T00:00:00Z", "active": true } ]}Get type stats
Section titled “Get type stats”curl https://api.example.com/api/schema-registry/projects/<projectId>/stats \ -H "Authorization: Bearer <token>"Returns counts of total / enabled / by-source types.
Create a custom type
Section titled “Create a custom type”curl -X POST https://api.example.com/api/schema-registry/projects/<projectId>/types \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "typeName": "Company", "description": "A business entity", "jsonSchema": { "type": "object", "properties": { "name": { "type": "string" }, "industry": { "type": "string" }, "founded": { "type": "integer" }, "headquarters":{ "type": "string" } }, "required": ["name"] }, "uiConfig": { "icon": "building", "color": "#4f46e5", "displayProperty": "name" }, "extractionConfig": { "extractRelationships": true, "confidenceThreshold": 0.7 }, "enabled": true }'Update a type
Section titled “Update a type”curl -X PUT https://api.example.com/api/schema-registry/projects/<projectId>/types/Company \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "description": "A business entity (updated)", "enabled": true }'Delete a type
Section titled “Delete a type”curl -X DELETE https://api.example.com/api/schema-registry/projects/<projectId>/types/Company \ -H "Authorization: Bearer <token>"Entity reference
Section titled “Entity reference”ProjectObjectTypeRegistry — table kb.project_object_type_registry
| Field | Type | Description |
|---|---|---|
id |
UUID | Primary key |
projectId |
UUID | Owning project |
typeName |
string | Unique within the project |
source |
string | schema | custom | discovered |
schemaId |
UUID | Set when source = "schema" |
schemaVersion |
int | Incremented on schema changes |
jsonSchema |
object | JSON Schema for object properties |
uiConfig |
object | Display hints for the admin UI |
extractionConfig |
object | Hints for the extraction pipeline |
enabled |
bool | Disabled types are skipped during extraction |
discoveryConfidence |
float | Set when source = "discovered" |
description |
string | Human-readable description |
createdBy |
UUID | User who created the type |
createdAt |
timestamp | |
updatedAt |
timestamp |
Embedding policies
Section titled “Embedding policies”Embedding policies control which objects receive vector embeddings. Each policy is scoped to a project and a type name.
List policies
Section titled “List policies”curl https://api.example.com/api/graph/embedding-policies \ -H "Authorization: Bearer <token>"Create a policy
Section titled “Create a policy”curl -X POST https://api.example.com/api/graph/embedding-policies \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "objectType": "Company", "enabled": true, "maxPropertySize": 4096, "requiredLabels": ["verified"], "excludedLabels": ["draft"], "relevantPaths": ["$.name", "$.industry", "$.description"], "excludedStatuses": ["archived"] }'Update a policy (PATCH — all fields optional)
Section titled “Update a policy (PATCH — all fields optional)”curl -X PATCH https://api.example.com/api/graph/embedding-policies/<policyId> \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"enabled": false}'Delete a policy
Section titled “Delete a policy”curl -X DELETE https://api.example.com/api/graph/embedding-policies/<policyId> \ -H "Authorization: Bearer <token>"Embedding policy fields
Section titled “Embedding policy fields”| Field | Description |
|---|---|
objectType |
Matches a type name in the schema registry |
enabled |
Master on/off switch for this type |
maxPropertySize |
Max bytes of any single property passed to the embedding model |
requiredLabels |
Object must have all of these labels to be embedded |
excludedLabels |
Object must have none of these labels |
relevantPaths |
JSON paths to include in the embedding text (e.g. $.name) |
excludedStatuses |
Object status values that skip embedding |
Workflow: adding a new entity type
Section titled “Workflow: adding a new entity type”- Define the schema — create a type via the API with a JSON Schema describing your object’s properties.
- Set UI config — add an icon, color, and
displayPropertyso the admin UI renders it nicely. - Set extraction config — tell the extraction pipeline what confidence threshold to use and whether to extract relationships.
- Create an embedding policy — decide which properties are relevant for vector search and any label/status filters.
- Run extraction — trigger an extraction job on a document or datasource; new objects of your type will be created.