Use when designing a central in-memory data model / object database for a tool, editor, or engine: typed objects with properties, stable cross-references and sub-object ownership, change notification, undo/redo, and serialization. Triggers on prompts about a runtime object/property schema, referencing objects by stable id/GUID, observing/notifying changes, transactional edits and undo history, save/load with versioning/migration, or copy-on-write snapshots — even when the user doesn't name a specific model.
Use when designing a central in-memory data model / object database for a tool, editor, or engine: typed objects with properties, stable cross-references and sub-object ownership, change notification, undo/redo, and serialization. Triggers on prompts about a runtime object/property schema, referencing objects by stable id/GUID, observing/notifying changes, transactional edits and undo history, save/load with versioning/migration, or copy-on-write snapshots — even when the user doesn't name a specific model.
Data-Model Guidelines
Essentials
One central model - Route tool/editor state through a single typed object store, not scattered structs, see references/object-model.md
Identity vs role - A GUID names a fixed identity; a name/path names a role that late-binds — default to GUIDs, see references/references-and-ownership.md
Prototypes & overrides
Any object can be a prototype - Instances inherit all properties and store only overrides; resolve a property by walking the prototype chain, see references/prototypes.md
Per-property override bitmask - One bit per property marks local-vs-inherited; sub-object sets track inherited / instantiated / removed children, see references/prototypes.md
Serialize only deltas - Persist the prototype reference plus overrides; reconstruct inherited values on load, see references/prototypes.md
Deterministic output - Stable ordering for diff/version control; choose text vs binary, see references/serialization.md
Save changes or re-spawn from assets - Persist member-level deltas for runtime state, asset references for content; POD serializes by default, see references/serialization.md
ABI-stable struct evolution - Append fields at the end, add a leading size, never reorder/retype; semantic-version the API, see references/serialization.md
A weak reference must resolve to null after its target is deleted; never leave it pointing at a recycled id.
Reusing a freed object id lets a stale reference silently alias a different object — bump a generation or never reuse.
Firing a notification synchronously inside a setter can re-enter the model mid-edit; queue and flush at transaction end.
An undo entry that captured a pointer/index breaks once storage moves — capture ids and values, not addresses.
External side effects (file writes, network) are not undoable; keep them out of the transactional journal.
A loader that rejects unknown fields cannot open older OR newer files — migrate forward and ignore-or-preserve unknowns.
Overriding a sub-object in an instance gives it a new id, so references to the prototype's original silently miss — resolve references through the override, don't store the new id everywhere.
Allowing computed overrides (a property defined as an expression over the prototype's value) drags evaluation order and cycles into the data model — keep overrides concrete values.
Progressive Disclosure
Read references/object-model.md - Load when defining typed objects, property kinds, or data-driven schemas
