Type catalog reference

Entity types, aspect schemas, relationship contracts, bindings and impact previews.

The type catalog defines what the graph is allowed to mean. System types ship with VegaGraph; authorized workspaces can add constrained types for their own domain.

Entity types

POST /entity-types
GET  /entity-types
GET  /entity-types/{entity_type_id}
PUT  /entity-types/{entity_type_id}
PATCH /entity-types/{entity_type_id}
DELETE /entity-types/{entity_type_id}

Important fields include namespace, name, display name, category, source, entity schema, identity template, UI schema, status, and whether the type is built in or extensible.

An identity template should produce a stable FQN from source-native identity—not from a mutable display label.

Aspect types

POST /aspect-types
GET  /aspect-types
GET  /aspect-types/{aspect_type_id}
PUT  /aspect-types/{aspect_type_id}
PATCH /aspect-types/{aspect_type_id}
DELETE /aspect-types/{aspect_type_id}

Field	Purpose
`json_schema`	Validates aspect `data` on every write.
`merge_strategy`	Declares how context overlays combine or replace data.
`versioned`	Controls whether changes retain version history.
`searchable_fields`	Selects safe fields for derived search documents.
`scope_type`	Describes where the aspect can be applied.
`ui_schema`	Presentation guidance; not an authorization rule.

Do not define secret-bearing fields. Store a reference to a managed secret or external record when association is necessary.

Relationship types

POST /relationship-types
GET  /relationship-types
GET  /relationship-types/{relationship_type_id}
PUT  /relationship-types/{relationship_type_id}
PATCH /relationship-types/{relationship_type_id}
DELETE /relationship-types/{relationship_type_id}

A relationship type constrains source/target types or categories, field endpoint use, cardinality, cycle behavior, context inheritance, labels and evidence metadata.

Bind aspects to entity types

POST /entity-types/{entity_type_id}/aspects
GET  /entity-types/{entity_type_id}/aspects
DELETE /entity-types/{entity_type_id}/aspects/{aspect_type_id}

A binding can mark the aspect required, set cardinality and provide default data. Required aspects are a validation contract, not merely UI guidance.

Type list endpoints support bounded search and type-specific filters such as q, category, namespace, status and system/workspace kind where exposed by the response schema. Use server filtering instead of loading the complete catalog into every client.

Full update and patch

PUT replaces editable fields. PATCH preserves omitted fields and accepts only the resource's declared patch contract. Nullable fields are cleared through clear_fields when the schema exposes it; setting and clearing the same field is invalid.

Impact preview

POST /type-impact:preview

Preview before changing persisted identifiers, schemas, required bindings, endpoint constraints, cardinality or acyclic behavior. The result returns bounded counts and samples of affected entities, aspects, fields, search documents and active edges.

Preview is evidence, not a write token. The subsequent mutation revalidates current state and can fail if the graph changed.

Built-in protection

System-owned types and aspects are locked against workspace mutation/deletion. Extend the graph with workspace types or permitted extension points instead of cloning a built-in type merely to change its label.