4. O contrato¶

English | Português (Brasil)

_{Tradução do original em inglês; quando os dois divergirem, vale o inglês.}

← Referência do formato · Índice · Ferramentas →

Dois níveis: MUST e SHOULD¶

Os dois são JSON Schema 2020-12 escritos à mão. Além deles, o contrato tem as regras de perfil YAML (um documento só, chave duplicada, chave on) e as de integridade (ids, pontas, órfãos), que o JSON Schema não vê. Por isso, um validador de JSON Schema sozinho não é um leitor completo: o leitor de referência aplica as três camadas, e a suíte cobra as três de todo leitor.

O format: date do schema é asserção: a data tem de existir no calendário (2026-02-30 reprova). Muitos validadores tratam format como anotação por padrão, e por isso a suíte tem casos para isso.

Códigos¶

Toda violação tem um código estável, com a forma da camada:

<tipo> é um de required, enum, type, pattern, range, const ou unknown-key. <escopo> é um de top, meta, node ou edge. Num campo aninhado, o caminho leva ponto: form.required.node.provenance.locator. Nas external_edges, o escopo é top e o campo leva o nome da lista (form.enum.top.external_edges.edge_type). Uma data fora do calendário (format: date) reprova como form.pattern.<escopo>.<campo>.

A lista completa, com o que cada código pega, está em spec/conformance/README.pt-BR.md.

Onde na fonte (v4.17)¶

O locator era texto livre: "linhas 10 a 12", "a seção License". Uma pessoa lê; uma ferramenta não confere. Desde o v4.17, o nó pode dizer como lê-lo e guardar o hash do que leu. Os dois são opcionais e só alertam: nada que passava reprova.

provenance:
  source: "https://github.com/acme/brain/blob/9f2c1e0/docs/payments.md"
  locator: "line=41,44"
  method: "reading: a seção de retentativa"
  scheme: text
  sha256: "3f1d…"   # 64 dígitos hex minúsculos: o SHA-256 do arquivo naquele commit

As URIs do conformsTo do modelo Web Annotation do W3C valem como alias, inclusive a da RFC 3778, que a tabela dele ainda usa para PDF. O hash vai num campo próprio: o md5= da RFC 5147 não é usado, porque o MD5 não resiste a colisão (RFC 6151). Avisos: form.enum.node.provenance.scheme, form.pattern.node.provenance.locator (o locator não cabe no esquema) e form.pattern.node.provenance.sha256. O kg_trace check então abre a fonte e confere o locator e o hash (capítulo 5). O que as normas deixam em aberto é decisão deste contrato, escrita como tal: o JSON Pointer que não resolve numa fonte JSON reprova no kg_trace, o char conta code points em todo leitor, linhas e colunas do CSV contam a partir de 1 e se escrevem sem zero à esquerda (a RFC 7111 aceita 0 e 01), e o intervalo de mídia exclui o fim. A forma não confere o que só a fonte diz, como o início depois do fim ou a linha que não existe: isso é do kg_trace.

O hash de um nó citado (v4.18)¶

Uma ponte para outro grafo (scheme: kg-node) aponta um nó dentro de um arquivo. O sha256 do arquivo cai assim que qualquer nó do arquivo muda, mesmo um que a ponte não cita. Desde o v4.18, o provenance.node_sha256 faz o hash só do nó citado: o SHA-256 da forma canônica dele pela RFC 8785 (JCS, JSON Canonicalization Scheme), sobre o modelo que o leitor extrai do grafo, com as chaves em ordem UTF-16 e números e strings na forma do ECMAScript.

provenance:
  source: "https://github.com/acme/core/blob/9f2c1e0/docs/graph/seals.kg.yaml#D_RETRY_POLICY"
  locator: "#D_RETRY_POLICY"
  method: "testimony: o selo do core"
  scheme: kg-node
  node_sha256: "d4d7…"   # kg_trace.py digest docs/graph/seals.kg.yaml#D_RETRY_POLICY

Ele vai só com scheme: kg-node e só alerta: form.pattern.node.provenance.node_sha256 fora da forma, form.required.node.provenance.scheme sem scheme, form.const.node.provenance.scheme com outro. O kg_trace check o compara com o nó citado (capítulo 5).

O que mudou do v3 para o v4¶

O v4 é uma versão maior: o que alertava passou a reprovar.

As versões menores da linha 4.x acrescentaram recursos sem mudar o veredito MUST de um grafo bem escrito, com uma exceção registrada: a 4.11.0, a 4.12.0 e a 4.13.0 passaram a reprovar construções raras do YAML (o perfil estrito). Foram menores porque nenhum dos grafos reais medidos em quatro repositórios adotantes mudou de veredito. Mesmo assim, contam como MUST novo para o critério de estável, e cada uma zerou o relógio de 30 dias. Desde a 4.11.0, o contrato tem rótulo de versão próprio (v4.4 na 4.11.0, v4.5 na 4.12.0, v4.6 na 4.13.0, v4.7 na 4.14.0, v4.8 na 4.15.0, v4.9 na 4.15.1 e na 4.16.0, v4.10 da 4.16.1 à 4.18.0, v4.11 na 4.19.0 e na 4.20.0, v4.12 na 4.21.0, v4.13 na 4.22.0, v4.14 da 4.23.0 à 4.26.0, v4.15 da 4.27.0 à 4.31.1, v4.16 da 4.32.0 à 4.36.0, v4.17 na 4.37.0, v4.18 desde a 4.38.0), que não é o número da release.

Versões e tags¶

A release é uma tag kg-ssot-vX.Y.Z (até a 4.3.0, o nome era contract-vX.Y.Z; as tags antigas seguem existindo). Pelo histórico das releases:

O gate guarda o sha256 dos dois schemas como a identidade do contrato. Uma tag que muda os bytes dos schemas, mesmo que só no texto das descrições (a 4.7.2) ou no $id (a 4.7.3), muda a identidade. Desde a 4.16.0, a identidade é composta: o gate acusa a troca numa linha · identidade, mas quem decide o rc é a comparação, feita com o contrato novo. A troca que não muda veredito nenhum passa com rc 0, e o --update grava a identidade nova quando você escolher. A regra nova que piora um grafo reprova pela comparação. --strict-identity volta ao rc 1 em toda troca, como antes da 4.16.0. Rodando de um vendor, o gate confere o sha256 dos dois schemas contra o carimbo e reprova o schema editado à mão. Uma regra que só o leitor vê (o perfil YAML, a quebra de linha) também entra na descrição do schema MUST, numa linha que começa com "No v4.6 ..." (as descrições do schema estão em português): desde a 4.13.1, a higiene da release cobra essa linha para a versão que o leitor declara, e assim toda versão do contrato move a identidade.

Um aviso SHOULD novo pode subir a dívida medida pelo gate. Isso é intencional: a rampa de um contrato é alertar numa versão e reprovar na seguinte, e assim você vê a dívida antes de ela virar erro.

A superfície que viaja em cada tag está listada em spec/release.json. Você não customiza o contrato no seu repositório: o vendor reprova edição local, e uma mudança necessária volta ao produto como issue no repositório público.

Os contratos antigos¶

O repositório do produto guarda o v1, o v2 e o v3 em spec/ como histórico; a release leva só o v4, o vigente, que é o que o leitor usa sem --schema.