Display Name Rules

Display-Name-Regeln erlauben es einem Construction-Kit-Typ zu deklarieren, wie Instanzen dieses Typs für Menschen beschriftet werden sollen. Ist eine Regel definiert, berechnet die Engine bei jedem Speichern die schreibgeschützten Systemfelder rtDisplayName und rtDisplayDescription für jede Entität, sodass alle Konsumenten — GraphQL-Abfragen, Refinery-Studio-Listen, MeshBoard-Entitätsselektoren und -Picker — ein konsistentes, aussagekräftiges Label anzeigen, ohne die Benennungslogik in jeder Anwendung zu duplizieren.

Display-Name-Regeln ersetzen die frühere Praxis, rtWellKnownName als menschenlesbares Label zu verwenden. rtWellKnownName bleibt ein rein technischer Bezeichner (z. B. für die Adressierung in Blueprints und Migrationen).

Regeln definieren

An einem Construction-Kit-Typ stehen zwei optionale typbezogene Eigenschaften zur Verfügung:

Eigenschaft	Beschreibung
displayNameRule	Regel zur Berechnung des Entitäts-Anzeigenamens (rtDisplayName)
displayDescriptionRule	Regel zur Berechnung der Entitäts-Anzeigebeschreibung (rtDisplayDescription)

Beispiel

$schema: https://schemas.meshmakers.cloud/construction-kit-elements.schema.json
types:
- typeId: NamedEntity
  displayNameRule: "${Name}"
  displayDescriptionRule: "${Description}"

Regel-Dialekt

Eine Regel ist eine Zeichenkettenvorlage mit Attribut-Interpolation:

• ${attributePath} fügt den Wert eines der eigenen Attribute des Typs ein. Record-Pfade werden unterstützt (z. B. ${Contact.LastName}); Assoziationsnavigation wird nicht unterstützt.
• ?? innerhalb eines Platzhalters bildet die Vereinigung zum ersten nicht-leeren Wert: ${Name ?? GlobalId} verwendet GlobalId, wenn Name leer ist.
• Literaler Text außerhalb von Platzhaltern wird wortwörtlich übernommen.
• Eine Regel muss mindestens einen Platzhalter enthalten.

Beispiel mit Kombination aus Literalen und Vereinigung

types:
- typeId: Room
  displayNameRule: "${RoomNumber} - ${Name ?? GlobalId}"

Vererbung

Regeln werden entlang derivedFromCkTypeId vererbt: Für eine Entität gewinnt die nächstgelegene nicht-leere Regel in der Vererbungskette. Jede Regel wird unabhängig aufgelöst — ein abgeleiteter Typ kann displayNameRule überschreiben und dabei displayDescriptionRule weiterhin von seinem Basistyp erben.

Validierung zur Kompilierzeit

Regeln werden vom Construction-Kit-Compiler validiert; ungültige Regeln lassen die Modellkompilierung fehlschlagen und werden am deklarierenden Typ gemeldet:

Meldung	Bedeutung
67	Die Regel konnte nicht geparst werden (Syntaxfehler oder kein Platzhalter vorhanden)
68	Ein Platzhalter verweist auf einen Attributpfad, der am Typ nicht existiert

Versionierung

Das Ändern einer displayNameRule oder displayDescriptionRule ist gemäß den Construction-Kit-Versionierungsregeln eine Modelländerung auf PATCH-Ebene — keine Änderung an Attribut-, Typ- oder Assoziationsverträgen.

Laufzeitverhalten

Bei jedem Speichern (Insert, Replace und intelligente partielle Updates) wertet die Engine die effektiven Regeln aus und speichert die Ergebnisse in den Systemfeldern rtDisplayName und rtDisplayDescription:

• Beide Felder sind schreibgeschützt. Sie fehlen in allen Mutation-Input-Typen und können nicht über die API oder den Import gesetzt werden.
• Wenn ein Typ keine effektive Regel hat oder alle referenzierten Attribute leer sind, ist der gespeicherte Wert null. Auf der GraphQL-Leseschicht gibt rtDisplayName (im Schema non-null) dann den Fallback <ckTypeId>@<rtId> zurück; rtDisplayDescription bleibt nullable.
• Filterung und Sortierung arbeiten auf dem gespeicherten Wert, nicht auf dem synthetisierten Fallback. Beide Felder stehen als System-Attributpfade für Feldfilter und Sortierreihenfolgen zur Verfügung (z. B. attributePath: "rtDisplayName") und erscheinen als Abfragespalten.

Abfragebeispiele finden Sie unter Retrieve.

Backfill beim Modellimport

Wenn ein Construction-Kit-Modellimport die deklarierten Anzeigeregeln ändert, werden vorhandene Entitäten der betroffenen Typ-Teilbäume durch einen automatischen Hintergrunddurchlauf aktualisiert. Der Durchlauf ist dauerhaft und wird wiederholt; sein Zustand wird in der Systemcollection display_rule_sweep verfolgt. Es ist kein manuelles Eingreifen erforderlich — die Labels vorhandener Entitäten konvergieren kurz nach Abschluss des Imports zu den neuen Regeln.