An enumeration is a closed, named list of values you reuse across the system. Think of statuses ("Draft", "Published", "Archived"), priorities ("Low", "Normal", "High"), or any small vocabulary that should look the same wherever it appears.

Yellow models enumerations the same way it models everything else: as instances. An Enumeration is a regular Yellow instance, and so is each of its EnumerationItems. That gives you all the editing, versioning, and reference machinery for free — and means an enumeration behaves like any other data in the system.

The Enumeration model

An Enumeration has three properties:

Property Type What it does
Name String Display name of the enumeration.
Items Collection of references to EnumerationItem The ordered list of values that belong to this enumeration.
OrderItemsByName Boolean When true, items are sorted by name; otherwise by id.

The Items collection is the source of truth for membership. New items are created inline from the collection dialog and saved in the same batch as their parent enumeration.

The EnumerationItem model

An EnumerationItem has three properties:

Property Type What it does
Name String The label users see.
Description String Free-form description.
Id Integer A stable numeric identifier within the enumeration.

The Id matters whenever an older property still expects a numeric value (see Integer property bound to an enumeration below). For new properties, treat it as a sortable handle.

Where enumerations show up in constraints

There are three constraint shapes that anchor on an enumeration. They differ in what gets stored on the property when the user picks an item.

1. Integer property bound to an enumeration

When the underlying property is an Integer, you set an Integer constraint with its Enumeration field pointing at the enumeration. The editor renders a dropdown of the enumeration's items, and the value stored on the property is the picked item's Id (a number).

  • Property type: Integer
  • Constraint: Integer constraint with Enumeration = "Status"
  • What gets stored: the picked item's Id (a number)

This is the older shape. It works, but carries a subtle trap: the property defaults to 0, and if 0 happens to be a valid Id in the enumeration, the dropdown looks selected even though nobody picked anything. Most of the time, prefer the next shape.

2. Instance-reference property bound to an enumeration

When the underlying property is an Instance Reference, you set an Instance Reference constraint with two fields:

  • Target Model = EnumerationItem
  • Enumeration = "Status"

The editor renders the same dropdown, but the value stored is a reference to the picked EnumerationItem. "Nothing picked" and "a real selection" are now unambiguous.

  • Property type: Instance Reference
  • Constraint: Instance Reference constraint with Target Model = EnumerationItem and Enumeration = "Status"
  • What gets stored: a reference to the picked EnumerationItem

This is the recommended shape for new properties.

3. Collection of items typed via an enumeration

In a Collection constraint, the Item Type field is itself a reference to an item of the built-in Property Types enumeration. Picking "STRING" means "every entry in the collection must be a string"; picking "INSTANCE_REFERENCE" means "every entry must point to an instance" and you then set Target Model accordingly. It's the same pattern as above, applied recursively to the constraint that defines the collection itself.

Built-in enumerations

Yellow ships with a small set of system enumerations. The one you'll meet most often is Property Types — it lists every property type Yellow supports (String, Integer, Boolean, Float, Decimal, DateTime, Date, Model Reference, Model Property Reference, Instance Reference, Instance Property Reference, Collection). It's what powers the type picker in the Collection constraint editor.

Evolution: integer → enumeration item → custom model

Properties tend to grow. A field that starts as a numeric flag often becomes an enumeration, and an enumeration often becomes a full model when items need richer fields (a category isn't just a label anymore — it also has an icon, a parent category, a slug, etc.). The constraint shapes above are designed to make those hops cheap.

From Integer to EnumerationItem

You have an Integer property bound to an enumeration. You want to upgrade it so the value carries the full identity of the picked item (and so you stop worrying about the 0-as-default trap).

  1. Change the property type from Integer to Instance Reference.
  2. Replace the Integer constraint with an Instance Reference constraint on the same property, with Target Model = EnumerationItem and the same Enumeration.
  3. Migrate existing data: for each stored integer value, find the matching EnumerationItem and replace the integer with a reference to that item.

The dropdown looks the same to the end user.

From EnumerationItem to a custom model

Suppose your enumeration outgrew itself. "Status" used to be just a name; now you need to track an icon, a color, a position in a workflow, and a few permissions. Time to promote it to a dedicated model — say, Status.

This hop is almost free because the property's underlying type doesn't change — it's still an Instance Reference:

  1. Define the new model (Status) and copy each EnumerationItem into a Status instance. Preserving each item's identifier makes the migration zero-touch.
  2. Update the constraint: keep the Instance Reference constraint on the property, drop its Enumeration field, and change Target Model from EnumerationItem to Status.

Existing data already stores a reference — only the target shape changed. If you kept the same identifiers, the existing references stay valid; if you used new ones, run a one-shot pass to remap them.

This is the payoff of building every enumeration on top of references: an enumeration is the simplest possible custom model. When you outgrow it, you promote without rewriting how the property is stored.

Editing enumerations

Enumerations live in the Explorer like any other instances. Open the Enumeration model, pick or create an enumeration, and edit its Items collection — new items are created inline (the EnumerationItem form is embedded directly in the collection dialog) and saved in the same batch as the parent. Reorder by adjusting each item's Id, or flip OrderItemsByName to sort by label.