Versioning

Products are independently versioned: one draft (editable) and zero or more published versions (immutable). Publishing uses Change Requests to choose which draft changes go into the new version. This page focuses on how the database and API handle versioning: deltas, stable IDs, and the fields you use for matching.

​

Delta Storage

The database does not store a full copy of all items and properties per version. It stores only deltas (changes): new, updated, or removed items/properties for that version. Unchanged data is shared across versions.

• On publish: Only the changes you included in the Change Request are written for the new version. Nothing else is copied.
• On read: The API returns the full view for a version (base + deltas applied); under the hood only changes are stored.

Items and properties are stored per version only when they are new or modified in that version. Unchanged entities are reused.

​

Draft ID: The Stable Reference

The draft ID of an item or property never changes. It is the stable reference for the logical entity. The API exposes this as optional draft_item_id and draft_property_id on item and property responses. Use these for matching the same logical item or property across versions (e.g. “this item in v1” = “this item in v2”).

​

Item-IDs and Property-IDs

When you modify an item or property and publish, the system takes the draft entity, copies it for that version, assigns a new id to the copy, and sets draft_item_id / draft_property_id to the original draft id. So for that version the API returns the duplicated item (with the new version-specific id and the stable draft_item_id for matching). When you request the draft, you always get the same draft item.

• Same entity, unchanged across versions → Same record, same id in all versions; nothing is copied.
• Same entity, modified and published → A copy is stored for that version with a new id; draft_item_id / draft_property_id is set to the draft id. Use these fields to match the same logical entity across versions.
• New entity → New id.

​

Summary

Use stable IDs and draft_item_id / draft_property_id to correlate entities across versions. The draft ID never changes and is the reference for matching.