Zum Hauptinhalt springen

Auswahlwerte, Größen und Bewertungen

Diese Typen legen Bedeutung im Schema ab. Eine Auswahl besitzt einen verwalteten Katalog, eine Größe eine festgelegte Einheit und eine Bewertung eine festgelegte Skala. Clients können einen reinen Datensatzwert dadurch interpretieren, ohne seine Bedeutung zu erraten.

Typmatrix​

TypSchreibwertKanonischer LesewertErforderliche KonfigurationGraphQL-Ausgabe
selectOptions-UUID/-Wert oder bei Mehrfachauswahl ein ArrayOptions-UUID oder UUID-ArrayOptionen; optional is_multiselect, min_items, max_itemsEnum bei Einzelauswahl; [String] bei Mehrfachauswahl
stateStatus-UUID oder -WertStatus-UUIDStatuswerte mit FarbeGeneriertes Enum
capacityJSON-ZahlJSON-Zahlunit_kind, unit_refFloat
measureJSON-ZahlJSON-Zahlunit_refFloat
currencyJSON-ZahlJSON-Zahlcurrency_codeFloat
ratingJSON-ZahlJSON-ZahlPositives maxFloat

Einheit, Währung und Bewertungsmaximum gehören zur Attributdefinition und werden nicht in jedem Datensatz wiederholt. Benötigt ein Feld gemischte Einheiten oder Währungen, ist es kein einheitliches Attribut: Normalisieren Sie Werte vor dem Schreiben oder modellieren Sie getrennte Felder.

Select​

Verwenden Sie select für eine kontrollierte Klassifikation. Jede Option hat eine unveränderliche id, einen veränderlichen technischen Wert, einen Anzeigetitel und eine Position.

{
"slug": "category",
"type": "select",
"name": {"en": "Category", "de": "Kategorie"},
"options": [
{"value": "hvac", "title": "HVAC"},
{"value": "elevator", "title": "Elevator"},
{"value": "lighting", "title": "Lighting"}
]
}

Ein Schreibzugriff kann "hvac" oder die UUID dieser Option verwenden. Ein Lesezugriff liefert die UUID. Dadurch kann der Schemaeigentümer den Wert umbenennen, ohne jeden Datensatz umzuschreiben oder eine Integration zu brechen, die die ID gespeichert hat.

Bei deklarativen Objektänderungen gilt:

  • Eine Options-id erhält die Identität bei einer Wertumbenennung.
  • Eine Option ohne ID und mit demselben aktuellen Wert behält ebenfalls ihre Identität.
  • Eine ausgelassene Option wird gelöscht und kann bestehende Werte ungültig machen; behandeln Sie die Entfernung als Datenmigration.

Mehrfachauswahl​

Setzen Sie is_multiselect: true, wenn ein Datensatz mehrere Werte tragen kann:

{
"slug": "certifications",
"type": "select",
"name": {"en": "Certifications", "de": "Zertifizierungen"},
"config": {
"is_multiselect": true,
"min_items": 1,
"max_items": 5
},
"options": [
{"value": "tuv", "title": "TÜV"},
{"value": "iso_9001", "title": "ISO 9001"}
]
}

Der Datensatzwert ist ein Array. Merge Patch ersetzt die vollständige Auswahl: Schlüssel auslassen, um sie zu erhalten; das gewünschte vollständige Array senden, um sie zu ändern; und, soweit zulässig, mit [] oder null leeren.

GraphQL macht aus einem einzelnen Select ein Enum. Mehrfachauswahl bleibt [String]. Werden zwei Optionswerte zum selben GraphQL-Symbol normalisiert, ergänzt Tourfold einen stabilen Suffix aus der unveränderlichen Options-ID. Laden Sie das Workspace-Schema herunter, statt Kollisionsnamen abzuleiten.

Status​

Verwenden Sie state, wenn ein Wert eine Position im Lebenszyklus und keine neutrale Kategorie darstellt. Ein Status benötigt neben Identität, Wert, Titel und Position auch eine Farbe.

{
"slug": "lifecycle",
"type": "state",
"name": {"en": "Lifecycle", "de": "Lebenszyklus"},
"states": [
{"value": "in_service", "title": "In service", "color": "#16A34A"},
{"value": "maintenance", "title": "Maintenance", "color": "#F59E0B"},
{"value": "retired", "title": "Retired", "color": "#64748B"}
]
}

Tourfold validiert die Zugehörigkeit, erfindet aber keine Übergangsregeln zwischen eigenen Statuswerten. Wenn nur true und false relevant sind, verwenden Sie Boolean. Können Benutzer mehrere unabhängige Labels wählen, verwenden Sie Multi-Select.

Status-Schreibzugriffe akzeptieren UUID oder aktuellen Wert; Lesezugriffe liefern die UUID. Senden Sie wie bei Optionen bestehende IDs bei deklarativen Schemaänderungen mit, um die Identität bei einer Umbenennung zu erhalten. GraphQL stellt aktuelle Statuswerte über ein generiertes Enum dar.

Kapazität​

Verwenden Sie capacity für eine Menge, deren Einheit entweder ein physisches Maß oder ein gezähltes Tourfold-Objekt ist.

Physische Kapazität:

{
"slug": "tank_capacity",
"type": "capacity",
"name": {"en": "Tank capacity", "de": "Tankkapazität"},
"config": {
"unit_kind": "measure",
"unit_ref": "00000000-0000-4000-8000-000000000701"
}
}

Eine Kapazität für gezählte Objekte nutzt unit_kind: "object" und die UUID des Zielobjekts als unit_ref – etwa die maximale Zahl an Technikern für eine Ressource. Der Datensatz speichert trotzdem nur eine Zahl; er legt keine Beziehungen zu entsprechend vielen Datensätzen an.

Messwert​

Verwenden Sie measure für einen physischen Messwert mit einer Maßeinheiten-Identität:

{
"slug": "cooling_output",
"type": "measure",
"name": {"en": "Cooling output", "de": "Kühlleistung"},
"config": {
"unit_ref": "00000000-0000-4000-8000-000000000702"
}
}

Die Zahl wird ohne zweites Einheitenfeld gespeichert. Konvertieren Sie Eingangswerte vor dem Schreiben in die deklarierte Einheit und für die Anzeige erst am Rand Ihrer Anwendung.

Währung​

Verwenden Sie currency für Geld in einer ISO-4217-Währung:

{
"slug": "replacement_cost",
"type": "currency",
"name": {"en": "Replacement cost", "de": "Ersatzkosten"},
"config": {"currency_code": "EUR"}
}

Der Datensatz enthält nur den Zahlenbetrag. Der dreistellige großgeschriebene Währungscode gehört zur Definition. Mischen Sie keine Beträge verschiedener Währungen in einem Attribut, ohne sie nach einer ausdrücklichen Fachregel umzurechnen.

Bewertung​

Verwenden Sie rating für einen begrenzten Wert mit einer gemeinsamen Skala:

{
"slug": "condition_rating",
"type": "rating",
"name": {"en": "Condition rating", "de": "Zustandsbewertung"},
"config": {"max": 5}
}

max muss positiv sein. Datensatzwerte reichen von 0 (nicht bewertet) bis zum festgelegten Maximum. Eine fehlende optionale Bewertung unterscheidet sich weiterhin von 0.

Anzeige​

Anzeigevorlagen geben einen Select- oder Status-Platzhalter als Titel der Auswahl aus, eine Mehrfachauswahl als ihre Titel, getrennt durch , . Das Ergebnis ist der display_name des Datensatzes; ein geänderter Titel benennt bestehende Datensätze also um, ohne sie zu aktualisieren.

Abfrage- und Integrationsverhalten​

Select- und Statusfilter akzeptieren, wo dokumentiert, aktuelle Werte; REST-Lesezugriffe liefern stabile IDs. Zahlenfamilien unterstützen Vergleich und Sortierung wie Zahlen. GraphQL liefert den Zahlenwert ohne die Einheitenmetadaten des Schemas. Behalten Sie daher die Objektdefinition, wenn ein Verbraucher den Wert beschriften oder umrechnen muss.

Änderungen an Auswahlen, Einheiten, Währung oder Skala können Validierung und generierte Clienttypen verändern. Planen Sie sie mit dem Leitfaden zur Schemaentwicklung.