Formatos de Dados

Use estas convenções para reduzir erros de validação e manter a interoperabilidade dos dados.

Nomes de atributos de metadados

Use Title Case para nomes de atributos de metadados (ex: Vehicle License Plate, Gross Weight, Issue Date). Não use kebab-case ou nomes concatenados em minúsculas nos metadados de eventos. A única exceção é o reason de um evento CANCEL, que a plataforma compara em minúsculas.

Data e hora

• Use timestamps UTC no formato ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) para campos de data e hora.
• Para campos apenas de data, use o formato de data ISO 8601 e, quando exigido pela API, inclua um atributo format (ex: DATE).
• Preserve a cronologia da origem nas submissões de eventos.

Identificadores

• Mantenha os IDs estáveis e determinísticos entre retentativas.
• Use deduplicationId como chave de idempotência de criação única em escritas passíveis de retentativa; uma repetição é rejeitada, não reexecutada — veja Tratamento de Erros.
• externalId é armazenado para a sua própria correlação e não é usado para deduplicação.

Convenções de nomenclatura

• Use nomes de atributos consistentes e evite duplicatas sinônimas.
• Prefira metadados estruturados em vez de strings de texto livre.

Valores numéricos e unidades

• Envie campos numéricos como números, não como strings localizadas.
• Quando a API exigir uma unidade ou escala, use o atributo format com o valor apropriado (ex: KILOGRAM, LITER, CUBIC_METER para massa/volume).
• Mantenha a escolha de unidade consistente durante o ciclo de vida do documento.

Dados sensíveis

Para atributos que contêm dados sensíveis ou pessoais (ex: placas de veículos, identificadores de motoristas):

• Envie o valor completo no payload — não mascare ou redija previamente.
• Defina sensitive: true nos metadados. Ele governa o mascaramento na página pública do documento; é um sinal que você envia, não o mecanismo que mantém um atributo fora das superfícies públicas de MassID da própria Carrot, que publicam um conjunto fixo de atributos mantido no código da Carrot.
• Consulte Privacidade e Mascaramento para controles de visibilidade.

Identidade do participante em eventos ACTOR

A superfície pública de MassID da Carrot nomeia participantes apenas a partir de eventos ACTOR — um participante ligado a um evento CUSTOM ou outro nunca é nomeado ali, independentemente das flags. Em um evento ACTOR, publicar o nome exige duas flags independentes:

• isPublic: true no evento. Esse campo é obrigatório, então omiti-lo falha na validação em vez de mudar o que é publicado.
• preserveSensitiveData: false — definido explicitamente. Esse é opcional, e aí está a armadilha: a verificação é !== false, então deixá-lo de fora equivale a true e a identidade é retida sem gerar erro.

Mesmo com as duas flags definidas, alguns papéis nunca são nomeados na superfície pública de MassID da Carrot — Waste Generator, Hauler e Bin Custodian são retidos independentemente disso. Não presuma que definir as duas flags publica o nome de qualquer participante.

Referências relacionadas:

• Conceitos Fundamentais
• Tratamento de Erros
• Especificação de Eventos
• Privacidade e Mascaramento