Display Name Rules
Display name rules let a Construction Kit type declare how instances of that type should be labeled for humans. When a rule is defined, the engine computes the read-only system fields rtDisplayName and rtDisplayDescription for every entity on save, so all consumers — GraphQL queries, Refinery Studio lists, MeshBoard entity selectors and pickers — show a consistent, meaningful label without duplicating naming logic in each application.
Display name rules replace the earlier practice of using rtWellKnownName as a human-readable label. rtWellKnownName remains a purely technical identifier (e.g. for blueprint and migration targeting).
Defining Rules
Two optional type-level properties are available on a Construction Kit type:
| Property | Description |
|---|---|
displayNameRule | Rule for computing the entity display name (rtDisplayName) |
displayDescriptionRule | Rule for computing the entity display description (rtDisplayDescription) |
Example
$schema: https://schemas.meshmakers.cloud/construction-kit-elements.schema.json
types:
- typeId: NamedEntity
displayNameRule: "${Name}"
displayDescriptionRule: "${Description}"
Rule Dialect
A rule is a string template with attribute interpolation:
${attributePath}inserts the value of one of the type's own attributes. Record paths are supported (e.g.${Contact.LastName}); association navigation is not supported.??inside a placeholder coalesces to the first non-empty value:${Name ?? GlobalId}usesGlobalIdwhenNameis empty.- Literal text outside placeholders is kept verbatim.
- A rule must contain at least one placeholder.
Example combining literals and coalescing
types:
- typeId: Room
displayNameRule: "${RoomNumber} - ${Name ?? GlobalId}"
Inheritance
Rules are inherited along derivedFromCkTypeId: for an entity, the nearest non-empty rule in the inheritance chain wins. Each rule is resolved independently — a derived type can override displayNameRule while still inheriting displayDescriptionRule from its base type.
Compile-Time Validation
Rules are validated by the Construction Kit compiler; invalid rules fail the model compile and are reported at the declaring type:
| Message | Meaning |
|---|---|
| 67 | The rule could not be parsed (syntax error, or no placeholder present) |
| 68 | A placeholder references an attribute path that does not exist on the type |
Versioning
Changing a displayNameRule or displayDescriptionRule is a PATCH-level model change under the Construction Kit versioning rules — no attribute, type, or association contract changes.
Runtime Behavior
On every save (insert, replace, and smart partial updates) the engine evaluates the effective rules and stores the results in the system fields rtDisplayName and rtDisplayDescription:
- Both fields are read-only. They are absent from all mutation input types and cannot be set via API or import.
- When a type has no effective rule, or all referenced attributes are empty, the stored value is
null. On the GraphQL read layer,rtDisplayName(non-null in the schema) then returns the fallback<ckTypeId>@<rtId>;rtDisplayDescriptionstays nullable. - Filtering and sorting operate on the stored value, not on the synthesized fallback. Both fields are available as system attribute paths for field filters and sort orders (e.g.
attributePath: "rtDisplayName") and appear as query columns.
See Retrieve for query examples.
Backfill on Model Import
When a Construction Kit model import changes the declared display rules, existing entities of the affected type subtrees are updated by an automatic background sweep. The sweep is durable and retried; its state is tracked in the system collection display_rule_sweep. No manual action is required — labels of existing entities converge to the new rules shortly after the import completes.