Representação de grandezas físicas em JSON: valor, unidade e precisão em campos separados

Objetivo

Trocar grandezas medidas ou calculadas em JSON de modo que quem consome os dados saiba qual é o número, qual é a unidade e quanto desse número é significativo, sem precisar adivinhar a partir do nome de um campo.

Pré-requisitos

Uma lista dos tipos de grandeza que a interface transporta (comprimento, massa, duração, temperatura; dinheiro é tratado à parte), a escolha de um vocabulário de unidades e um acordo sobre se cada campo tem unidade fixa (todo produtor usa a mesma unidade) ou unidade mista (o produtor escolhe).

Passos

1. Para cada tipo de grandeza, escolha uma unidade canônica para armazenamento e cálculo, de preferência a unidade do SI ou uma unidade derivada coerente (metros, quilogramas, segundos), e faça a conversão na fronteira do sistema.
2. Campos de unidade fixa: coloque a unidade no nome do campo (duration_ms, distance_m) e use um número JSON simples. Assim o campo fica compacto e difícil de ler errado.
3. Campos de unidade mista (valores digitados pelo usuário, instrumentos com unidades próprias): use um objeto {"value": 12.5, "unit": "kg"}, com unit tirado de um vocabulário controlado. O UCUM (citado) fornece códigos de unidade legíveis por máquina em ASCII; ele define símbolos que diferenciam maiúsculas de minúsculas (kg, Cel, [in_i]) e uma variante separada que não diferencia, então declare qual variante a interface usa.
4. Informe a precisão de forma explícita quando ela importar: um campo separado uncertainty ou resolution, e não zeros à direita. A RFC 7946 (citada) estabelece essa regra para coordenadas, afirmando que o número de dígitos não deve ser interpretado como indicação de incerteza; os parsers não preservam a quantidade de dígitos, portanto a regra vale para qualquer grandeza.
5. Use uma string com a representação decimal quando o valor decimal exato for importante (uma leitura copiada de um visor, um limite regulatório); use números JSON para valores aproximados por natureza.
6. Valide no schema: uma enumeração para unit, um intervalo numérico por unidade e uma regra segundo a qual value e unit aparecem juntos ou não aparecem.
7. Trate a temperatura como caso especial: o UCUM classifica o grau Celsius como unidade especial em uma escala que não é de razão, convertida com um deslocamento (offset) e não com um fator, e excluída de multiplicação e exponenciação; armazene kelvin ou Celsius e indique qual.

Resultado esperado

Quem consome os dados consegue converter qualquer valor para a unidade canônica de forma mecânica, divergências de unidade são detectadas pela validação do schema em vez de aparecerem como resultados errados, e as afirmações sobre precisão são explícitas, não deduzidas da formatação.

Limites e base de verificação

O procedimento é uma proposta derivada das especificações citadas; não se afirma ter medido o seu efeito. Ele não cobre valores monetários, que têm regras próprias (unidades menores por moeda), nem unidades compostas cujos códigos precisam ser montados (kg.m/s2 na sintaxe do UCUM). Os vocabulários de unidades diferem (UCUM, códigos UN/CEFACT, ontologias); misturá-los em uma mesma interface anula o propósito, então escolha um e registre a escolha no schema.