Modelo de validação

A validação não é apenas o comando validate. Todo comando que lê uma especificação — plan, apply, verify, status, doctor, fingerprint — faz o parse e a valida antes de qualquer coisa, e para em caso de falha. Não há como chegar ao sistema de arquivos com uma especificação que não valida.

Uma especificação pode falhar em dois lugares distintos, e eles reportam de formas diferentes.

parse      arquivo ausente, vazio, YAML malformado
           ou uma raiz que não é um mapping         → saída 4

validate   regras de esquema e de caminho abaixo    → saída 1

Falhas de parse são sobre o arquivo. Falhas de validação são sobre o que o arquivo diz.

• A raiz precisa ser um mapping.
• O version precisa estar presente. Seu valor é registrado, mas não passa por verificação de faixa.
• O structure precisa estar presente e precisa ser um mapping.
• O structure.name precisa estar presente.
• O structure.directories precisa estar presente, precisa ser uma lista e não pode ser vazio.
• O style, se presente, precisa ser um entre enterprise, technical hybrid. O padrão é enterprise.
• O conjunto de chaves de raiz é fechado. Só version, structure, style policy são aceitas; qualquer outra é reportada como campo desconhecido.

Cada entrada em structure.directories é verificada individualmente, após a normalização.

• Precisa ser uma string, e não pode ser vazia nem só espaços.
• Precisa ser relativa. Caminhos absolutos são rejeitados, para que uma especificação não alcance fora do workspace.
• Não pode conter ... A travessia de caminho é rejeitada pelo mesmo motivo.
• Não pode conter os caracteres < > : " \ | ? *. Barras são permitidas.
• Duas entradas não podem normalizar para o mesmo caminho. Duplicatas são rejeitadas.

A validação junta todos os problemas que encontra e os reporta de uma vez, um por linha, em vez de parar no primeiro. Uma única execução mostra tudo o que está errado no arquivo.

Validation failed:
Missing required field 'structure.name'.
'structure.directories' cannot be empty.
Unknown field at root level: 'relationships'.

As mensagens nomeiam o campo e a falha. Elas não trazem número de linha, posição de caractere nem sugestão de correção, então localize o campo pelo nome no seu arquivo.

A validação lê apenas a especificação. Ela nunca olha o sistema de arquivos, então não pode dizer se a estrutura existe, se está completa ou se sofreu desvio.

Não há motor de regras, verificação de referências cruzadas, análise de dependências ou de ciclos, nem imposição de convenções de nomenclatura além das regras de caracteres acima. Uma especificação que valida está bem formada — não necessariamente é a estrutura que você pretendia.

Cada chave e regra enumeradas acima estão listadas campo a campo na Referência da especificação, e cada mensagem é explicada na Solução de problemas.

Para perguntas sobre o workspace, e não sobre o arquivo, use verify, status doctor. Regras de policy declaradas em policy.forbid são verificadas pelo comando policy separado, não pela validação.