Definition metadata
Objects, Vehicles and Tasks share one effective definition representation. For the same caller and revision, owner detail, list items, creation/update results and aggregate discovery return the same definition, including owner-specific fields.
Routes and visibilityโ
GET /api/v2/definitions/alllists visible concrete definitions and supported native projections.GET /api/v2/definitions/all/{definition_ref}accepts a workspace-local UUID or slug.- Authoring remains under
/api/v2/definitions/objects,/vehiclesand/tasks.
Discovery includes concrete Vehicle and Task definitions by default, including protected built-in
Task execution definitions. Internal vehicle and system_task family roots are excluded from
both discovery operations. The list accepts zero-based page and size (1โ100). Visibility is
applied before totals and pagination; ordering is by slug, then UUID. A hidden, unsupported or
unknown definition returns 404.
Metadata visibility does not grant record access. Record-specific rules, parent traversal and field permissions still apply when records are read or changed. Relationship eligibility is independent of visibility.
All definition read endpoints (/api/v2/definitions/all, /api/v2/definitions/objects,
/api/v2/definitions/vehicles, and /api/v2/definitions/tasks) emit a weak ETag and
Cache-Control: private, no-cache, and support conditional revalidation via If-None-Match
(304 Not Modified).
Shared fieldsโ
| Field | Meaning |
|---|---|
id, slug, name | Stable definition UUID, workspace-unique selector and localized singular/plural names. |
resource_type | Extensible string: object, vehicle, task, or a registered native key such as tag or plugin:bw:tour. A native key does not make the resource an Object. |
attributes | Complete effective field descriptions, including common system and owner-inherited fields. |
created_at, updated_at, lock_version | Definition timestamps and optimistic revision. Metadata reads do not advance them. |
managed_by, managed_by_plugin, schema_policy | tenant, system or plugin ownership, optional plugin ID, and editable or locked authoring policy. |
is_readonly | Definition-level record writability metadata, independent of schema ownership. |
is_relationship_target | Whether this definition supports relationship targeting. |
natural_id_key, display_template | Optional identity/display settings where configured and supported by the owner. |
icon, color, map_marker_fields | Optional icon/palette color and ordered marker-popup field selection; the selection is always an array. |
Task responses additionally expose execution_type and is_extendable. Vehicle and Object responses need no
extra family discriminator. Public definitions do not expose base_definition_id; record-level
definition_id remains unchanged. Creating a Task definition selects its behavior with
execution_type.
Fields appear in System โ Plugin โ Custom order, retaining definition order within each group.
is_system_managed on an attribute protects its schema; is_readonly separately controls value
writes. Native writable Task fields still use typed top-level Task payloads. Structured Task
descriptors such as visit and interaction use response-only type: json; they are not authorable
custom JSON attributes. Effective metadata must not be copied blindly into an authored schema.
Presentation writesโ
All three owner APIs accept icon, color and map_marker_fields on create, full replacement and
metadata PATCH. An unset color renders transparently. Reads omit unset icon/color; an unconfigured
marker selection is [].
{"icon":"truck","color":null,"map_marker_fields":["name","reference"]}
This example requires eligible name and reference fields in the effective definition. Marker
selections may only contain supported fields, without duplicates. Invalid fields or value types
produce field-level 422 errors. Attribute rename/removal adjusts the selection transactionally.
PATCH omission preserves a setting; explicit null clears icon/color and resets marker fields to
[]. An array replaces the complete ordered selection. POST and PUT default omitted optional
icon/color to unset and marker fields to []. A supplied stale lock_version returns 409.
Managed definitions allow their existing presentation-edit exceptions while authored schemas remain
protected. Configuring presentation does not create a new map, sidebar or record-access capability.