Skip to main content
Every entity in Poelis (products, items, properties, and versions) has a readable ID. A readable ID is a stable, human-readable identifier used to reference an entity. While names are meant for display and can change freely, readable IDs act as the canonical reference. Readable IDs are used consistently in:
  • the Poelis web interface
  • the Python SDK and browser-style dot notation

​
Why readable IDs exist

Readable IDs provide a bridge between human-friendly modeling and machine-friendly access. They allow you to:
  • reference entities reliably in scripts and integrations
  • navigate data programmatically using dot notation with the Python SDK
  • avoid ambiguity when names change
  • maintain stable references across versions
For example, in the Python SDK, dot notation directly reflects readable IDs:
This notation works because each level is identified by its readable ID, not by its display name.

​
Behavior and guarantees

Readable IDs:
  • are unique within a scope that depends on the entity:
    • a product readable ID is unique within its workspace
    • an item readable ID is unique within its parent scope (the product for a root item, or the parent item when nested)
    • a property readable ID is unique within its item
  • are preserved when data is versioned or baselined
  • can be copied directly from the UI
  • can be edited manually when needed
When duplicating entities, Poelis automatically adjusts readable IDs to avoid collisions, typically by appending an index.

​
Names vs readable IDs

It is important to distinguish between the two:
  • Name: A human-facing label used for display and discussion. It can change freely.
  • Readable ID: A stable identifier used for references, integrations, and programmatic access.
In practice, names help people understand what something is, while readable IDs define which thing it is.