Skip to content

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.

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

Source Description
schema Installed from a schema
custom Created directly by a developer
discovered Proposed automatically by the extraction pipeline

Terminal window
curl https://api.example.com/api/schema-registry/projects/<projectId> \
-H "Authorization: Bearer <token>"
Terminal window
curl https://api.example.com/api/schema-registry/projects/<projectId>/types/Person \
-H "Authorization: Bearer <token>"
Terminal window
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
}
]
}
Terminal window
curl https://api.example.com/api/schema-registry/projects/<projectId>/stats \
-H "Authorization: Bearer <token>"

Returns counts of total / enabled / by-source types.

Terminal window
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
}'
Terminal window
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
}'
Terminal window
curl -X DELETE https://api.example.com/api/schema-registry/projects/<projectId>/types/Company \
-H "Authorization: Bearer <token>"

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 control which objects receive vector embeddings. Each policy is scoped to a project and a type name.

Terminal window
curl https://api.example.com/api/graph/embedding-policies \
-H "Authorization: Bearer <token>"
Terminal window
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)”
Terminal window
curl -X PATCH https://api.example.com/api/graph/embedding-policies/<policyId> \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'
Terminal window
curl -X DELETE https://api.example.com/api/graph/embedding-policies/<policyId> \
-H "Authorization: Bearer <token>"
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

  1. Define the schema — create a type via the API with a JSON Schema describing your object’s properties.
  2. Set UI config — add an icon, color, and displayProperty so the admin UI renders it nicely.
  3. Set extraction config — tell the extraction pipeline what confidence threshold to use and whether to extract relationships.
  4. Create an embedding policy — decide which properties are relevant for vector search and any label/status filters.
  5. Run extraction — trigger an extraction job on a document or datasource; new objects of your type will be created.