Skip to main content

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/all lists 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, /vehicles and /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โ€‹

FieldMeaning
id, slug, nameStable definition UUID, workspace-unique selector and localized singular/plural names.
resource_typeExtensible 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.
attributesComplete effective field descriptions, including common system and owner-inherited fields.
created_at, updated_at, lock_versionDefinition timestamps and optimistic revision. Metadata reads do not advance them.
managed_by, managed_by_plugin, schema_policytenant, system or plugin ownership, optional plugin ID, and editable or locked authoring policy.
is_readonlyDefinition-level record writability metadata, independent of schema ownership.
is_relationship_targetWhether this definition supports relationship targeting.
natural_id_key, display_templateOptional identity/display settings where configured and supported by the owner.
icon, color, map_marker_fieldsOptional 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.