Entities, aspects and fields

Entity identity, aliases, aspect versions, field references and write semantics.

Entity contract

An entity is a workspace-scoped typed node. Its stable identity is its ID plus workspace-unique FQN.

Field	Meaning
`entity_type_id`	Contract governing the entity.
`context_id`	Optional environment/context lens; null means canonical.
`canonical_entity_id`	Optional link from a runtime/context entity to its logical canonical entity.
`name`, `display_name`, `description`	Human-facing identity.
`fqn`	Stable workspace-unique qualified name.
`lifecycle`, `entity_status`	Lifecycle and observed state.
`source_system`, `external_id`, `source_url`, `source_hash`	Provenance and source identity.
`confidence`	Confidence in the assertion.
`version`	Resource version for change coordination.

CRUD

POST /entities
GET  /entities
GET  /entities/{entity_id}
PUT  /entities/{entity_id}
PATCH /entities/{entity_id}
DELETE /entities/{entity_id}

List with type, context, lifecycle, source and text filters supported by the endpoint schema. Delete is a soft lifecycle operation and returns 204 No Content.

Aliases

POST /entities/{entity_id}/aliases
GET  /entities/{entity_id}/aliases

Aliases preserve prior FQNs, source-native names or other durable lookup values. Upserting the same normalized alias is idempotent. An alias does not replace the canonical FQN.

Aspect writes

POST /entities/{entity_id}/aspects
GET  /entities/{entity_id}/aspects
GET  /entities/{entity_id}/aspects/{aspect_type_id}
GET  /entities/{entity_id}/aspects/{aspect_type_id}/versions

An aspect is identified by entity, aspect type, optional context and aspect key. Each accepted write validates the JSON Schema and produces current/versioned behavior declared by the aspect type.

Current reads apply the selected context overlay. Version history returns the authored assertions and should be used for audit views, not as a substitute for current resolution.

Aspect provenance

Include source_system, source run ID, observation/validity times and confidence when they exist. A connector should use a repeatable source run identity so users can trace a value to its evidence.

Do not put credentials, access tokens or unrestricted raw source payloads in aspect data.

Field references

POST   /entities/{entity_id}/field-refs
GET    /entities/{entity_id}/field-refs
GET    /field-refs/{field_ref_id}
GET    /field-refs/{field_ref_id}/lineage
DELETE /field-refs/{field_ref_id}

A field reference addresses a stable item inside an aspect using aspect_type_id, field key/path, FQN, kind, data type and ordinal. It can be an endpoint of a relationship when that relationship type permits fields.

Promote a field to an entity only when it needs independent ownership, lifecycle, aspects or relationships beyond field-level lineage/classification.

360 view

GET /entities/{entity_id}/360

The 360 response combines the entity with bounded aliases, current aspects, fields, edges and context summaries. It is designed for a detail page; use dedicated list/traversal endpoints for large graph exploration. See Entity 360 for how to interpret these fields during an investigation.