Definitionsmetadaten
Objekte, Fahrzeuge und Aufgaben verwenden eine gemeinsame effektive Definitionsdarstellung. Für denselben Aufrufer und dieselbe Revision liefern Detail-, Listen-, Erstellungs- und Änderungsantworten sowie die gemeinsame Abfrage dieselbe Definition einschließlich ihrer ressourcenspezifischen Felder.
Endpunkte und Sichtbarkeit
GET /api/v2/definitions/alllistet sichtbare konkrete Definitionen und unterstützte native Projektionen.GET /api/v2/definitions/all/{definition_ref}akzeptiert eine UUID oder einen Slug des Workspace.- Die Bearbeitung erfolgt weiterhin unter
/api/v2/definitions/objects,/vehiclesund/tasks.
Konkrete Fahrzeug- und Aufgabendefinitionen sind standardmäßig enthalten, auch geschützte integrierte
Aufgabendefinitionen. Die internen Familienwurzeln vehicle und system_task sind von beiden
Abfrageendpunkten ausgeschlossen. Die Liste akzeptiert das nullbasierte page und size (1–100).
Die Sichtbarkeitsprüfung erfolgt vor Zählung und Seitenauswahl; sortiert wird nach Slug und UUID.
Verborgene, nicht unterstützte oder unbekannte Definitionen liefern 404.
Sichtbare Metadaten gewähren keinen Datensatzzugriff. Datensatzregeln, Zugriff über Elternobjekte und Feldberechtigungen werden beim Lesen und Schreiben weiterhin geprüft. Die Eignung als Beziehungsziel ist unabhängig von der Sichtbarkeit.
Alle Leseendpunkte für Definitionen (/api/v2/definitions/all, /api/v2/definitions/objects,
/api/v2/definitions/vehicles und /api/v2/definitions/tasks) liefern ein schwaches ETag sowie
Cache-Control: private, no-cache und unterstützen bedingte Revalidierung über If-None-Match
(304 Not Modified).
Gemeinsame Felder
| Feld | Bedeutung |
|---|---|
id, slug, name | Stabile Definitions-UUID, im Workspace eindeutiger Selektor und übersetzte Namen im Singular/Plural. |
resource_type | Erweiterbare Zeichenfolge: object, vehicle, task oder ein registrierter nativer Schlüssel wie tag oder plugin:bw:tour. Ein nativer Schlüssel macht die Ressource nicht zu einem Objekt. |
attributes | Vollständige effektive Feldbeschreibungen einschließlich Systemfeldern und geerbten Feldern der Ressource. |
created_at, updated_at, lock_version | Zeitstempel und optimistische Revision der Definition; Metadatenabfragen verändern sie nicht. |
managed_by, managed_by_plugin, schema_policy | Eigentümerschaft durch tenant, system oder plugin, optionale Plugin-ID und Bearbeitungsregel editable oder locked. |
is_readonly | Schreibbarkeit der Datensätze auf Definitionsebene, unabhängig von der Schemaeigentümerschaft. |
is_relationship_target | Ob diese Definition als Beziehungsziel unterstützt wird. |
natural_id_key, display_template | Optionale Identitäts- und Anzeigeeinstellungen, soweit von der Ressource unterstützt und konfiguriert. |
icon, color, map_marker_fields | Optionales Symbol, Palettenfarbe und geordnete Feldauswahl für Kartenmarkierungen; die Auswahl ist immer ein Array. |
Aufgabenantworten enthalten zusätzlich execution_type und is_extendable. Fahrzeuge und Objekte benötigen
keinen weiteren Familiendiskriminator. Öffentliche Definitionen enthalten kein base_definition_id;
definition_id eines Datensatzes bleibt unverändert. Beim Erstellen einer Aufgabendefinition wählt
execution_type das Verhalten aus.
Felder erscheinen in der Reihenfolge System → Plugin → Benutzerdefiniert; innerhalb jeder Gruppe
bleibt die Definitionsreihenfolge erhalten. is_system_managed schützt das Attributschema,
is_readonly steuert davon unabhängig Wertänderungen. Schreibbare native Aufgabenfelder verwenden
weiterhin die typisierten Aufgabenfelder auf oberster Ebene. Strukturierte Beschreibungen wie
visit und interaction haben den ausschließlich für Antworten vorgesehenen Typ json. Sie sind
keine frei anlegbaren JSON-Attribute. Effektive Metadaten dürfen nicht ungeprüft als Schema
zurückgeschrieben werden.
Darstellung bearbeiten
Alle drei Ressourcen-APIs akzeptieren icon, color und map_marker_fields beim Erstellen,
vollständigen Ersetzen und Metadaten-PATCH. Eine nicht gesetzte Farbe ergibt einen transparenten
Hintergrund. Antworten lassen nicht gesetzte Symbole/Farben weg; eine leere Markerauswahl ist [].
{"icon":"truck","color":null,"map_marker_fields":["name","reference"]}
Dieses Beispiel setzt geeignete Felder name und reference in der effektiven Definition voraus.
Die Auswahl darf nur unterstützte Felder ohne Duplikate enthalten. Ungültige Felder oder Werttypen
führen zu feldbezogenen 422-Fehlern. Umbenennung und Löschung eines Attributs passen die Auswahl
innerhalb derselben Transaktion an.
Bei PATCH erhält ein weggelassenes Feld den bestehenden Wert. Explizites null löscht Symbol/Farbe
und setzt die Markerauswahl auf []; ein Array ersetzt die gesamte geordnete Auswahl. POST und PUT
setzen weggelassene optionale Symbole/Farben auf ungesetzt und Markerfelder auf []. Eine veraltete
mitgesendete lock_version führt zu 409. Verwaltete Definitionen erlauben ihre bestehenden
Ausnahmen für Darstellungsänderungen, während das Schema geschützt bleibt. Eine Konfiguration
schafft keine zusätzliche Karte, Seitenleiste oder Datensatzberechtigung.