Governance and change safety

Governance in VegaGraph is stored as evidence-backed graph facts, not a colored badge detached from its source.

Labels and classification

Labels are hierarchical workspace objects. Assignments can target an entity or field reference and carry source, confidence, evidence and review state.

governance
└── sensitivity
    ├── public
    ├── internal
    ├── confidential
    └── restricted
        └── pii

Automated classification should begin as a proposed or lower-confidence assignment. Confirmation, rejection and removal are explicit actions. The latest assignment and its evidence remain inspectable so a user can answer why customer.email is marked as PII.

Provenance

Entities, aspects and edges carry source_system, a source run identity, observation times and confidence where applicable. Connectors should keep source-native IDs and locations as provenance, not use them as a reason to leak credentials or raw payloads into the search index.

Type Studio

Authorized workspace users can define entity types, aspect schemas and relationship contracts. Built-in system types are locked. Before a risky change, call the impact preview endpoint:

POST /api/v1/vegagraph/orgs/{org_id}/workspaces/{workspace_id}/type-impact:preview

The preview identifies affected surfaces and, for persisted type IDs, returns bounded counts and samples across entities, search documents, aspects/history, field refs, active edges, traversal/cycle review and required-aspect validation.

It is a preview, not a write token. The service validates the real mutation again inside its transaction.

PATCH and clearing fields

Generic PATCH routes use partial merge semantics. Omitted fields remain unchanged. Nullable fields are cleared through an explicit clear_fields list, and setting and clearing the same field in one request is rejected.

Metadata object replacement is whole-object replacement unless a resource says otherwise. Do not assume recursive JSON merge for fields such as label metadata.

Deletion

Generic deletes for entities, fields, edges, contexts, labels, assignments and search documents return 204 No Content with an empty body. Clients should not attempt to parse JSON. Built-in types and aspects cannot be deleted by workspace users.

Search documents

Search documents are derived, replaceable projections attached to an entity. The entity and aspects remain the authority. Rebuilding search does not rewrite governance evidence, and deleting a search document does not delete its entity.

Natural-language or AI-assisted discovery should point back to graph entities and evidence. It should not become a second undocumented store of organizational truth.