Formatos de Dados

Convenções de formato de dados — nomenclatura, datas, números, Title Case e restrições de campos.

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.

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 para comportamento idempotente em retentativas.

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 sensible: true nos metadados para que a plataforma aplique mascaramento em superfícies públicas.
Consulte Privacidade e Mascaramento para controles de visibilidade.

Referências relacionadas: