Os contratos são a fonte da verdade.
ContractForge separa movimentação de dados, metadados de catálogo, propriedade operacional, regras de segurança e opções de ambiente de plataforma em contratos dedicados. Use um único arquivo de ingestão para pequenas cargas de trabalho ou um pacote quando diferentes equipes precisarem de diferentes fluxos de trabalho de revisão e aplicação.
Arquivos de contrato
Os contratos ContractForge são intencionalmente divididos por responsabilidade. A divisão não é obrigatória para todas as pequenas cargas de trabalho, mas torna-se importante quando a engenharia de dados, a governação, as operações e a segurança têm proprietários, ciclos de revisão ou privilégios de tempo de execução diferentes.
Ingestão
Origem executável, destino, modo de gravação, transformações, regras de qualidade, política de esquema, janelas de execução e comportamento de tempo de execução.
Anotações
Descrições, aliases, tags, classificação PII e metadados de ciclo de vida voltados para o catálogo para tabelas e colunas.
Operações
Propriedade, grupos de suporte, criticidade, frequência esperada, atualização SLA, tags de runbook e painel.
Acesso
Concessões, filtros de linha, máscaras de coluna e política de desvio de acesso, aplicadas por um fluxo de trabalho com os privilégios de catálogo corretos.
Ambiente
Seleção de adaptador, localização de evidências, dicas de tempo de execução e configurações de implantação de propriedade do adaptador.
Projeto YAML
Ambientes em nível de repositório, conexões reutilizáveis, cronogramas, ordem de execução e blocos de implantação do adaptador.
O contrato de ingestão é o único arquivo necessário para mover dados. Os outros arquivos tornam explícitos os metadados do catálogo, a propriedade operacional, a política de segurança e as opções de ambiente de tempo de execução, sem forçar a reescrita da tabela.
YAMLs de conexão reutilizável e referências de tabela lógica reduzem o desvio de plataforma entre
adaptadores. Um conjunto de dados JDBC bronze pode herdar configurações de endpoint/autenticação/driver de
source.type: connection, enquanto os contratos downstream de prata e ouro podem ler
tabelas ContractForge anteriores por meio de source.ref: bronze.table_name ou SQL
{{ table_ref:layer.table }} placeholders.
O arquivo de ingestão é a raiz do pacote configurável e possui a identidade da tabela física. Os arquivos complementares normalmente omitem target; ContractForge aplica anotações, operações e acesso ao destino de ingestão correspondente. Se um arquivo complementar declarar target, ele será tratado como uma declaração de compatibilidade explícita e deverá corresponder exatamente ao destino de ingestão.
Bundle layout
contracts/
silver/
s_customers.ingestion.yaml
s_customers.annotations.yaml
s_customers.operations.yaml
s_customers.access.yaml
s_customers.environment.yaml
Um pacote configurável é carregado por prefixo de caminho. Por exemplo, contracts/silver/s_customers pode resolver a ingestão, anotações, operações e arquivos de acesso mostrados acima. Isso mantém as decisões relacionadas próximas ao controle de origem, ao mesmo tempo que permite que cada arquivo seja revisado e aplicado de forma independente.
Quando dividir contratos
| Change type | Contrato | Reason |
|---|---|---|
| Origem, destino, modo, chaves, qualidade, transformação ou comportamento de execução | ingestion | Ele muda a forma como os dados são lidos, modelados, validados ou gravados. |
| Descrição, aliases, tags, PII ou metadados de descontinuação | annotations | Descreve a tabela ou os campos sem alterar o pipeline de dados. |
| Proprietário, grupo de suporte, criticidade, SLA, runbook ou intenção de alerta | operations | Ele muda a forma como a mesa é operada e monitorada. |
| Privilégios, filtros de linha ou máscaras | access | Requer revisão orientada para a segurança e, muitas vezes, privilégios de catálogo elevados. |
| Adaptador, tempo de execução, localização de evidência ou dica de implantação | environment | Ele seleciona onde e como o contrato é planejado ou executado sem alterar a semântica origem/destino. |
Modelo de aplicação
Ingestion
Validado antes do início do trabalho do Spark. Ele define o que é lido, como as linhas são preparadas, quais barreiras de qualidade se aplicam e como o destino é gravado.
Anotações
Aplicado depois que o caminho de gravação criou ou atualizou o esquema de destino. Comentários de coluna, tags e metadados PII exigem que as colunas físicas existam.
Operações
Registrado com evidências de execução para que os painéis possam mostrar o proprietário, a criticidade, o grupo de suporte, o SLA e o contexto do runbook sem analisar o YAML manualmente.
Acesso
Projetado para um fluxo de trabalho dedicado porque concessões, filtros de linha e máscaras geralmente exigem privilégios de catálogo mais fortes do que trabalhos de ingestão normais.
Environment
Mantém a seleção da plataforma, o armazenamento de evidências e as dicas de tempo de execução separadas da ingestão, das anotações, das operações e da semântica de acesso.
Escolhendo o modo de arquivo único ou pacote
Use um único contrato de ingestão quando uma equipe possuir a origem, o destino, as regras de qualidade e a resposta operacional. Use um pacote quando alterações de contrato precisarem de aprovações diferentes ou quando metadados/segurança precisarem ser atualizados sem executar novamente uma ingestão pesada.
Shared metadata
Cada arquivo de contrato pode incluir _metadata. ContractForge o remove antes da execução e o mantém para auditoria e verificações de pacotes.
_metadata:
contract_version: 1.0.0
last_updated_by: data-platform
last_updated_at: "2026-05-17T12:00:00Z"
Fluxo de trabalho de validação
contractforge validate contracts/silver/s_customers.ingestion.yaml
contractforge validate-bundle contracts/silver/s_customers
contractforge plan contracts/silver/s_customers --adapter databricks
contractforge-databricks render contracts/silver/s_customers