Campos do YAML

Referência para consulta rápida. Para aprender o formato, comece em A anatomia de uma modelagem.

Os documentos

Um arquivo .yaml do modelo declara o que carrega de duas formas, que podem conviver no mesmo arquivo separadas por ---:

• singular — kind: <tipo> no topo, e os campos logo abaixo;
• coleção — sem kind, com as listas elements:, relations:, diagrams:, flows:, notes:.

Valores de kind: project, element, relation, diagram, flow, note, folder. Um kind desconhecido faz o documento ser ignorado, com aviso.

cfour.yaml — o registro

Campo	Tipo	Obrigatório	Padrão	O que faz
version	número	não	—	a versão do formato do registro
id	texto	não	—	o identificador deste registro. Serve para escolher a chave de publicação deste repositório
active	texto	não	—	qual modelagem abre quando ninguém diz qual
modelagens	lista	sim	—	as modelagens registradas
modelagens[].id	texto	sim	—	o identificador
modelagens[].name	texto	não	o id	o nome legível; perde para o name do modelagem.yaml
modelagens[].path	texto	sim	—	a pasta da modelagem. Aceita relativo e ~
federacoes	lista	não	—	leituras conjuntas nomeadas
federacoes[].id	texto	sim	—	o identificador
federacoes[].name	texto	não	o id	o rótulo
federacoes[].modelagens	lista de texto	sim	—	os membros
federacoes[].curador	texto	não	o primeiro membro	de quem vale a configuração

Um id de modelagem repetido é erro. Uma federação citando modelagem não registrada é aviso.

modelagem.yaml — a identidade

Campo	Tipo	Obrigatório	Padrão	O que faz
version	número	não	—
id	texto	não	—	tem de bater com o do registro; discordar é aviso
name	texto	não	o do registro	o nome legível
description	texto	não	—	para que ela existe
status	texto	não	active	active, reference ou archived. Só active é publicado
federacao	texto	não	—	a leitura conjunta de que ela participa

project.yaml — um projeto

Campo	Tipo	Obrigatório	Padrão	O que faz
id	texto	não	o nome da pasta	discordar da pasta é aviso, e a pasta vence
name	texto	não	o id	o nome exibido
order	número	não	500	a posição entre os projetos
tags	lista de texto	não	[]
meta	mapa	não	{}

folder.yaml — o nome de uma pasta

Campo	Tipo	Obrigatório	O que faz
name	texto	não	o nome da pasta na árvore de navegação
order	número	não	a posição dela

Elemento

Campo	Tipo	Obrigatório	Padrão	O que faz
id	texto	sim	—	[A-Za-z0-9][A-Za-z0-9._-]*. A barra é reservada
name	texto	não	o id
shape	texto	não	system	chave em shapes. Desconhecida: caixa neutra + aviso
parent	referência	não	—	decide o nível C4
description	texto	não	—
technology	texto	não	—
level	texto	não	derivado	context, container, component, code. Discordar da árvore é aviso, e a árvore vence
tags	lista de texto	não	[]
meta	mapa	não	{}	valores de texto, número ou booleano
bind	mapa	não	—	espelho de um elemento de outra modelagem
bind.modelagem	texto	sim, dentro de bind	—
bind.ref	texto	sim, dentro de bind	—	tem de ser qualificado
relations	lista	não	—	só em documento singular; from implícito
notes	lista	não	—	só em documento singular; target implícito

Relação

Campo	Tipo	Obrigatório	Padrão	O que faz
from	referência	sim	—	implícito num documento singular de elemento
to	referência	sim	—
kind	texto	não	sync	chave em relationKinds. Desconhecida: linha cheia + aviso
label	texto	não	—
description	texto	não	—
bidirectional	booleano	não	—	true põe ponta também na origem
route	texto	não	o padrão do diagrama	straight, orthogonal, bezier
tags	lista de texto	não	[]
meta	mapa	não	{}
id	texto	não	<from>~<kind>~<to>	duplicatas recebem #2, #3…

Uma relação de uma caixa para ela mesma é ignorada, com aviso.

Diagrama

Campo	Tipo	Obrigatório	Padrão	O que faz
id	texto	não	o nome do arquivo
title	texto	não	o id
level	texto	não	derivado	em que nível o leitor o abre
scope	referência	não	—	a caixa detalhada; vira a fronteira
order	número	não	500
include	lista de seletores	não	[{children: scope}] quando há scope	quem entra
exclude	lista de seletores	não	—	quem sai
where	seletor de predicado	não	—	filtra o que include trouxe
neighbors	número	não	0	saltos de contexto mudo
relations	vários	não	auto	auto, none, lista de ids, {exclude: [ids]}
groups	lista	não	—	grupos escritos à mão
groupBy	texto	não	—	meta.<chave>, level, shape, project
subject	referência ou lista	não	—	quem está em foco
tags	lista de texto	não	[]
meta	mapa	não	{}
notes	lista	não	—	notas confinadas a este diagrama

groupBy: tag:<prefixo> não existe, e escrevê-lo é erro.

Grupo

Campo	Tipo	Obrigatório	Padrão	O que faz
id	texto	sim	—	único dentro do diagrama
name	texto	não	o id
orientation	texto	não	empilha	row ou column
include	lista de seletores	não	—
match	seletor de predicado	não	—	atalho para um include de uma cláusula
groups	lista	não	—	grupos aninhados

Nota

Campo	Tipo	Obrigatório	Padrão	O que faz
text	texto	sim	—
target	referência	não	—	a caixa. Implícito em documento singular de elemento
scope	referência de diagrama	não	—	o diagrama. Implícito em documento de diagrama
kind	texto	não	info	chave em noteKinds. Desconhecida: neutro + aviso
meta	mapa	não	{}

Sem target e sem scope, a nota é descartada com aviso.

Fluxo

Campo	Tipo	Obrigatório	Padrão	O que faz
id	texto	não	o nome do arquivo	divide o espaço de nomes com diagramas
title	texto	não	o id
scope	referência	não	—	onde o caso de uso mora. Não escolhe participantes
level	texto	não	o mais fino que os passos citam
order	número	não	500
main.name	texto	não	Principal	o nome do caminho principal
main.outcome	texto	não	success	chave em flowOutcomes
participants	lista de referências	não	ordem de aparição	fixa as primeiras colunas
steps	lista	sim	—	os passos do caminho principal
paths	lista	não	—	os caminhos alternativos
tags	lista de texto	não	[]
meta	mapa	não	{}

Passo

Campo	Tipo	Obrigatório	Padrão	O que faz
to	referência	sim	—
from	referência	não	o to do passo anterior	no primeiro passo, omitir é erro
kind	texto	não	o da seta declarada, ou sync
label	texto	não	o rótulo da seta declarada
description	texto	não	—
reply	texto	não	—	resposta curta, tracejada
id	texto	não	—	necessário só para ser ponto de desvio

Caminho alternativo

Campo	Tipo	Obrigatório	Padrão	O que faz
id	texto	sim	—
name	texto	não	o id
outcome	texto	não	alternate	chave em flowOutcomes
from	id de passo	não	—	de onde ele desvia, inclusive
steps	lista	sim	—

Referências

Como está escrito	Como resolve
com barra, reservas/api	absoluta: projeto e identificador
sem barra, api	o projeto que declara; depois shared/

Todo campo que cita uma caixa segue essa regra: parent, from, to, scope, subject, target, os seletores e os participantes de fluxo.

.layout/ — a arrumação

Escrita pelo leitor, nunca lida como modelo. Um arquivo JSON por diagrama, em <projeto>/.layout/<id>.json, com as posições das caixas e das notas soltas, o estado dos grupos, as arestas ajustadas e o estilo de linha. Fluxos não têm arquivo de arrumação.

workspace.yaml

Está em Configuração da aparência.