References & integrity

datadata’s model is referential: documents point at other documents (and at records within documents) by id. Schemas declare these references, which lets the engine check and repair integrity instead of leaving dangling ids to the application.

Declaring references

A schema document marks fields as references — to another document of a given type, or to a record inside the same document (for example, an edge in a diagram pointing at two nodes). Each reference declares what should happen when its target goes away: cascade the removal, or repair the orphan.

Checking and repairing

Validation can run with reference checking enabled, resolving targets across documents. Repair hooks apply the declared rules — removing edges whose nodes were deleted, clearing pointers to vanished documents — so integrity maintenance is driven by the schema rather than scattered through application code.

This matters doubly for AI agents: an agent can validate the referential consistency of its staged changes before committing, and the rules it must respect are readable from the schema documents themselves.

Gaps & open questions

Referential integrity is enforced at validation/repair time, not transactionally across documents — concurrent writers can still race a reference into dangling between check and commit within a folder. The repair-on-read patterns are still being shaped by the apps. See Open questions.