# `runner manifest schema` (2.182.0+)

Imprime o JSON Schema do .deploy.yml que este runner lê. O schema sai das mesmas structs do parser, então descreve o que a versão instalada aceita. É só leitura: não carrega config, app nem state, e responde em qualquer servidor com o binário.

# Sintaxe

runner manifest schema

Sem argumentos. A saída é sempre JSON, com exit 0. O comando manifest tem outros subcomandos: veja `runner manifest`.

# Saída

{
  "runner_version": "2.182.0",
  "schema_id": "sha256:8e5f3a45bca691f25a3687ddf2b8d036c4a4de51f16673871dc56f0875667b00",
  "dialeto": "https://json-schema.org/draft/2020-12/schema",
  "schema": {}
}

O schema_id só muda quando o schema muda. O JSON canônico tem as chaves ordenadas em todos os níveis e nenhum espaço. Para conferir o id por fora:

runner manifest schema | python3 -c "import hashlib,json,sys; s=json.load(sys.stdin)['schema']; print('sha256:'+hashlib.sha256(json.dumps(s,sort_keys=True,separators=(',',':'),ensure_ascii=False).encode()).hexdigest())"

# Como saber se o runner tem o comando

O runner anuncia a capability manifest.schema.v1:

runner --capabilities

Runner sem a capability não tem o comando. Nesse caso, use o schema de uma versão mais nova só como referência. Não valide contra ele.

# Pelo GitHub Release

Cada release publica o arquivo manifest-schema.json como asset. Ele traz o envelope inteiro, inclusive o schema_id. O comando continua sendo a fonte primária: responde pela versão instalada na app.

# Como o editor deve usar o schema

1. Chame runner manifest schema no servidor da app.
2. Guarde o schema em cache pelo schema_id. Se o id não mudou, reuse.
3. Use o schema do runner da app, não o de outro servidor. Em frota com versões diferentes, cada app tem o seu.
4. Campo que o schema não conhece aparece em vermelho, com a versão do runner ("este runner (2.182.0) não aceita …"). Nunca remova o campo sozinho: o usuário decide.
5. O schema não substitui o veredito do servidor. Antes de salvar, chame `manifest validate`, que cobre o que o schema não expressa.

# Extensões `x-runner-*`

O schema acrescenta chaves que o JSON Schema não tem. Um validador comum as ignora. O editor as usa para sugerir valores e avisar.

A chave deprecated: true marca o que é obsoleto: image_mode, github, type: docker-build, source.type: dist e o notify em formato de mapa. Marca também as grafias antigas de image_mode e de env_sync (sync, local, e Remote/Skip, que o runner escrevia até a 2.181.0). Só o notify em mapa leva também x-runner-obsoleto.

# Aliases

type, environment (dentro da instância) e tag_pattern existem no schema como propriedades, com x-runner-alias-de. Assim um manifesto que usa type: valida. O canônico (app_type, environment_overrides, tag) lista o alias em x-runner-aliases. O editor pode esconder o alias e mostrar só o canônico. Declarar os dois juntos não vale: o runner recusa o campo duplicado.

# Vocabulário do `x-runner-ref`

O valor é uma string, ou uma lista quando o campo aceita mais de uma coisa (volumes, labels). Em lista, o x-runner-ref vale para cada item. Em mapa, vale para as chaves, como em environment (app.env). Em labels é diferente: o ref cobre os valores das labels traefik.* que citam middleware ou entrypoint.

Exemplos reais do schema:

"ports": { "x-runner-ref": "porta" }
"volumes": { "x-runner-ref": ["docker.volume", "host.path"] }

Em volumes, a origem é volume Docker na forma volume:<nome>:… e pasta do host nas demais. A regra vem em x-runner-regra. O `manifest context` lista os valores que existem no servidor para cada ref.

# O que o schema aceita de diferente

• Número, booleano e nulo em campo de texto. Todo campo de texto livre (sem lista fechada de valores), inclusive item de lista e valor de mapa como environment, labels e hosts, aceita texto, número, booleano e nulo. O runner grava tudo como texto: PORT: 8000 vira "8000", interval: 30 vira "30" e file: null vira o texto "null". A regra vem em x-runner-regra. Exceções, em que o runner recusa e o schema também: os campos de notify, o command e o release.command, e os itens de networks.
• Vazio em lista, mapa ou bloco. volumes:, environment:, healthcheck: ou production: sem nada valem como vazio (ou padrão), e o schema aceita o nulo. Campo numérico, booleano ou de lista fechada vazio continua inválido.
• networks. Lista de nomes, lista com objetos ou mapa de nome para opções. O schema descreve a entrada. O nome da rede não se repete, e um item em texto conta como o próprio nome.
• notify. Lista de subscrições. O formato de mapa antigo é aceito, mas não envia notificação. Está marcado como obsoleto.
• command. Texto ou lista de textos.
• Chaves que começam com x- são aceitas no topo, em cada instância e em healthcheck.

# Divergências conhecidas entre o schema e o runner

O schema e o parser dão o mesmo veredito em todos os manifestos testados, com as exceções abaixo. Nelas, o editor deve confiar no `manifest validate`.

O schema recusa, mas o runner aceita:

Blocos em que o runner descarta chave desconhecida:

• github, version, build, routing e network_specs;
• assets e seus itens;
• notify[] e notify[].request;
• logging, security, resources e config_templates;
• routes[], depends_on[] e os objetos de networks;
• canary e canary.auto_promote;
• source e source.signature;
• config e config.vault.

Um github.user antigo cai neste caso. O campo github é obsoleto. O editor mostra user em vermelho e não o remove.

O schema aceita, mas o runner recusa:

# Veja também

• `runner manifest`: ler, gravar, fixar, contexto e validação
• Anatomia do .deploy.yml