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. A participant's visibility is decided once for the whole document, from every event that mentions it:

isPublic: true on each of those events. This field is required, so omitting it fails validation rather than changing what is published.
preserveSensitiveData on each of those events: false for Processors, Recyclers and Network Integrators, true for Waste Generators, Haulers, Waste Managers and every other supply chain role. true on any of those events keeps the participant unnamed everywhere in the document; leaving the field out applies the role's default, under which Processors, Recyclers and Network Integrators can be named and the other roles are not. A participant that is both a hauler and a processor or recycler in the same document is the exception: leave the field out on every event that mentions it, and it can be named on the public document page.

Some roles are never named on Carrot's public MassID surface, whatever the flags say. See Privacy & Masking for which roles can be named.

Related references: