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
| Typ | Schreibwert | Kanonischer Lesewert | Erforderliche Konfiguration | GraphQL-Ausgabe |
|---|---|---|---|---|
select | Options-UUID/-Wert oder bei Mehrfachauswahl ein Array | Options-UUID oder UUID-Array | Optionen; optional is_multiselect, min_items, max_items | Enum bei Einzelauswahl; [String] bei Mehrfachauswahl |
state | Status-UUID oder -Wert | Status-UUID | Statuswerte mit Farbe | Generiertes Enum |
capacity | JSON-Zahl | JSON-Zahl | unit_kind, unit_ref | Float |
measure | JSON-Zahl | JSON-Zahl | unit_ref | Float |
currency | JSON-Zahl | JSON-Zahl | currency_code | Float |
rating | JSON-Zahl | JSON-Zahl | Positives max | Float |
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-
iderhä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.