Data Formats

Data format conventions — naming, dates, numbers, Title Case, and field constraints.

Use these conventions to reduce validation errors and keep data interoperable.

Metadata attribute names

Use Title Case for metadata attribute names (e.g. Vehicle License Plate, Gross Weight, Issue Date). Do not use kebab-case or lowercase-concatenated names in event metadata. The one exception is reason on a CANCEL event, which the platform matches in lowercase.

Date and time

Use ISO 8601 UTC timestamps (YYYY-MM-DDTHH:mm:ss.sssZ) for date-time fields.
For date-only fields, use ISO 8601 date format and, when required by the API, include a format attribute (e.g. DATE).
Preserve source chronology across event submissions.

Identifiers

Keep IDs stable and deterministic across retries.
Use deduplicationId as a create-once idempotency key on retryable writes; a replay is rejected rather than replayed — see Error Handling.
externalId is stored for your own correlation and is not used for deduplication.

Naming conventions

Use consistent attribute names and avoid synonymous duplicates.
Prefer structured metadata over free-form string blobs.

Numeric values and units

Send numeric fields as numbers, not localized strings.
When the API requires a unit or scale, use the format attribute with the appropriate value (e.g. KILOGRAM, LITER, CUBIC_METER for mass/volume).
Keep unit choice consistent within a document lifecycle.

Sensitive data

For attributes that contain sensitive or personal data (e.g. license plates, driver identifiers):

Send the full value in your payload — do not pre-mask or redact.
Set sensitive: true in the metadata. It governs masking on the public document page; it is a signal you send, not the mechanism that keeps an attribute off Carrot's own public MassID surfaces, which publish a fixed set of attributes maintained in Carrot's code.
See Privacy & Masking for visibility controls.

Participant identity on ACTOR events

Carrot's public MassID surface names participants from ACTOR events only — a participant attached to a CUSTOM or other event is never named there, whatever its flags say. On an ACTOR event, publishing the name takes two independent flags:

isPublic: true on the event. This field is required, so omitting it fails validation rather than changing what is published.
preserveSensitiveData: false — set explicitly. This one is optional, and that is the trap: the check is !== false, so leaving it out is treated the same as true and the identity is withheld with no error.

Even with both flags set, some roles are never named on Carrot's public MassID surface — Waste Generator, Hauler, and Bin Custodian are withheld regardless. Do not assume that setting both flags publishes any participant name.

Related references: