Referência do Projeto YAML

project.yaml descreve como um grupo de contratos ContractForge é entregue como um projeto de ingestão. Não é um contrato de ingestão e não deve conter semântica do conjunto de dados, como colunas de origem, modo de gravação, regras de qualidade ou acesso policies.

Use-o para questões de nível de repositório:

• quais ambientes existem;
• onde residem os YAMLs de conexão reutilizável;
• como as etapas do contrato dependem umas das outras;
• como um projeto é programado;
• quais artefatos de plataforma devem ser implantados;
• quais comandos de validação e verificações de evidências comprovam a entrega.

O objetivo é o desvio mínimo da plataforma: os campos do projeto portátil permanecem no topo nível; as diferenças do adaptador residem em blocos adaptadores explícitos.

Canonical Shape

name: usgs_geojson_medallion
description: Real USGS GeoJSON medallion ingestion across stable adapters.

source_system:
  name: usgs_earthquake_feed
  type: rest_api

environments:
  databricks: environments/databricks.environment.yaml
  aws: environments/aws.environment.yaml
  snowflake: environments/snowflake.environment.yaml
  fabric: environments/fabric.environment.yaml
  gcp: environments/gcp.environment.yaml
  snowflake: environments/snowflake.environment.yaml
  fabric: environments/fabric.environment.yaml
  gcp: environments/gcp.environment.yaml

connections:
  usgs_geojson: connections/usgs.yaml

deployment:
  databricks:
    bundle_name: contractforge_usgs_geojson_medallion
    job_key: usgs_geojson_medallion
    job_name: contractforge_usgs_geojson_medallion
    workspace_root_path: /Workspace/Shared/contractforge-examples/USGS_GeoJSON_Medallion
  aws:
    state_machine_name: contractforge_usgs_geojson_medallion

schedule:
  cron: "0 6 * * *"
  timezone: America/Sao_Paulo
  enabled: false
  max_concurrent_runs: 1
  queue: true
  adapters:
    databricks:
      pause_status: PAUSED
      tasks:
        bronze_usgs_geojson:
          task_key: bronze_usgs_geojson
    aws:
      state: DISABLED

execution_order:
  - name: bronze_usgs_geojson
    layer: bronze
    depends_on: []
    contracts:
      databricks: contracts/databricks/bronze/bronze_usgs_geojson/bronze_usgs_geojson.ingestion.yaml
      aws: contracts/aws/bronze/bronze_usgs_geojson/bronze_usgs_geojson.ingestion.yaml
      snowflake: contracts/snowflake/bronze/bronze_usgs_geojson/bronze_usgs_geojson.ingestion.yaml
      fabric: contracts/fabric/bronze/bronze_usgs_geojson/bronze_usgs_geojson.ingestion.yaml
      gcp: contracts/gcp/bronze/bronze_usgs_geojson/bronze_usgs_geojson.ingestion.yaml

  - name: silver_usgs_events
    layer: silver
    depends_on: [bronze_usgs_geojson]
    contracts:
      databricks: contracts/databricks/silver/silver_usgs_events/silver_usgs_events.ingestion.yaml
      aws: contracts/aws/silver/silver_usgs_events/silver_usgs_events.ingestion.yaml
      snowflake: contracts/snowflake/silver/silver_usgs_events/silver_usgs_events.ingestion.yaml
      fabric: contracts/fabric/silver/silver_usgs_events/silver_usgs_events.ingestion.yaml
      gcp: contracts/gcp/silver/silver_usgs_events/silver_usgs_events.ingestion.yaml

validation:
  databricks:
    bundle: databricks.yml
    job_name: contractforge_usgs_geojson_medallion
  aws:
    artifact_bucket_parameter: CONTRACTFORGE_AWS_ARTIFACT_BUCKET
    glue_role_parameter: CONTRACTFORGE_AWS_GLUE_ROLE_ARN

Referência de campos

Campo	Obrigatório	Responsável	Propósito
name	sim	essencial	ID do projeto estável. Usado para nomes padrão de trabalho, pacote configurável, máquina de estado e planejamento.
description	não	essencial	Descrição legível do projeto.
source_system	não	essencial	Contexto de origem no nível do projeto para documentação e dados de teste. A semântica de origem no nível do conjunto de dados ainda pertence aos contratos de ingestão.
environments	sim para implantar	essencial	Mapeia chaves de ambiente para arquivos *.environment.yaml.
connections	não	essencial	Conexões YAML reutilizáveis, nomeadas para humanos e organização de projetos. Os contratos de ingestão ainda usam source.connection_path.
deployment	não	adaptadores	Metadados de implementação do adaptador. Mantenha aqui apenas as configurações de implantação da plataforma.
schedule	não	núcleo mais adaptadores	Intenção de agendamento de propriedade principal mais substituições de agendador específicas do adaptador.
execution_order	sim para projetos	essencial	Etapas e dependências do contrato ordenadas.
validation	não	adaptadores/ferramentas	Dicas de teste, implantação e auditoria usadas pelas CLIs de adaptador e exemplos.
portability	não	documentação/ferramentas	Explica diferenças contratuais intencionais entre plataformas.

Environments

environments mapeia uma chave lógica para um contrato de ambiente:

environments:
  databricks: environments/databricks.environment.yaml
  aws: environments/aws.environment.yaml

O arquivo de ambiente escolhe o adaptador, o local da evidência e o tempo de execução/implantação parâmetros. Não deve conter semântica de ingestão.

Exemplo de ambiente AWS:

name: smoke
adapter: aws
artifacts:
  uri: s3://contractforge-artifacts/usgs-geojson/
  include_contract_bundle: true
  include_normalized_contract: true
parameters:
  aws:
    iceberg:
      warehouse: s3://contractforge-warehouse/
    glue_job:
      role_arn: arn:aws:iam::123456789012:role/ContractForgeGlueRole
    step_functions:
      role_arn: arn:aws:iam::123456789012:role/ContractForgeStepFunctionsRole
    scheduler:
      role_arn: arn:aws:iam::123456789012:role/ContractForgeSchedulerRole

Reusable Connections

connections é um inventário de projeto de arquivos de conectores compartilhados:

connections:
  supabase_postgres: connections/supabase.yaml

A herança real acontece no contrato de ingestão através source.type: connection:

source:
  type: connection
  connection_path: project://connections/supabase.yaml
  table: public.products
  read:
    partition_column: product_id
    lower_bound: 1
    upper_bound: 100000
    num_partitions: 8

Connection file:

type: connector
connector: postgres
system: supabase_inventory_demo
options:
  url: "{{ secret:supabase/jdbc_url }}"
  driver: org.postgresql.Driver
auth:
  type: username_password
  username: "{{ secret:supabase/user }}"
  password: "{{ secret:supabase/password }}"
read:
  fetchsize: 10000

O carregador de pacote principal resolve o arquivo de conexão antes do planejamento do adaptador e mescla-o profundamente com campos de origem específicos do conjunto de dados. A conexão YAML fornece padrões; o bloco source de ingestão os substitui. Isso inclui aninhados campos como read.fetchsize, read.num_partitions ou options.driver.

Para o comportamento completo de mesclagem, exemplos e regras de segurança de caminho, consulte Conexão YAML.

Regras de segurança:

• use project://connections/... para conexões centralizadas de projetos;
• use caminhos relativos do mesmo pacote somente quando o arquivo de conexão estiver sob o ingestion bundle directory;
• não use caminhos absolutos ou travessia ..;
• keep secrets as secret references;
• não coloque semântica específica de tabela no arquivo de conexão;
• use arquivos de conexão para endpoint, autenticação, driver e padrões de leitura comum.

Implantação

deployment contém apenas configurações de implementação do adaptador.

deployment:
  databricks:
    bundle_name: contractforge_usgs_geojson_medallion
    job_key: usgs_geojson_medallion
    job_name: contractforge_usgs_geojson_medallion
    workspace_root_path: /Workspace/Shared/contractforge-examples/USGS_GeoJSON_Medallion
  aws:
    state_machine_name: contractforge_usgs_geojson_medallion
  gcp:
    workflows:
      location: us-central1

Os blocos de implantação podem nomear trabalhos nativos, pacotes, máquinas de estado, espaços de trabalho caminhos ou raízes de artefatos. Eles não devem redefinir modos de escrita, semântica de origem, regras de qualidade ou política de governação.

Schedule

Use schedule de nível superior para agendamento de projetos portáteis:

schedule:
  cron: "0 6 * * *"
  timezone: America/Sao_Paulo
  enabled: false
  max_concurrent_runs: 1
  queue: true
  adapters:
    databricks:
      pause_status: PAUSED
    aws:
      state: DISABLED

Campos de propriedade principal:

Field	Significado
cron	Standard five-field cron: minute, hour, day-of-month, month, day-of-week.
timezone	Nome do fuso horário IANA, por exemplo America/Sao_Paulo.
enabled	Intenção portátil. false significa implantar o agendamento pausado/desativado.
max_concurrent_runs	Intenção de simultaneidade portátil. O suporte do adaptador varia.
queue	Intenção de fila portátil. O suporte do adaptador varia.

Traduções do adaptador:

Adaptador	Translation
Databricks	cron: "0 6 * * *" -> Trabalhos Quartz cron 0 0 6 * *?; fuso horário -> timezone_id; enabled: false ou pause_status: PAUSED -> agendamento pausado.
AWS	cron: "0 6 * * *" -> Agendador EventBridge cron(0 6 * *? *); fuso horário -> ScheduleExpressionTimezone; enabled: false ou state: DISABLED -> agendamento desabilitado.

Use schedule.adapters.<adapter> apenas para substituições específicas da plataforma:

schedule:
  cron: "0 6 * * *"
  timezone: America/Sao_Paulo
  adapters:
    aws:
      flexible_time_window: OFF
    databricks:
      pause_status: PAUSED

Não coloque definições de cron separadas em cada adaptador, a menos que o agendamento seja intencionalmente diferente e documentado como não portátil.

Ordem de Execução

execution_order é o projeto portátil DAG:

execution_order:
  - name: bronze_orders
    layer: bronze
    depends_on: []
    contracts:
      databricks: contracts/databricks/bronze/bronze_orders/bronze_orders.ingestion.yaml
      aws: contracts/aws/bronze/bronze_orders/bronze_orders.ingestion.yaml

  - name: silver_orders
    layer: silver
    depends_on: [bronze_orders]
    contracts:
      databricks: contracts/databricks/silver/silver_orders/silver_orders.ingestion.yaml
      aws: contracts/aws/silver/silver_orders/silver_orders.ingestion.yaml

Fields:

Field	Obrigatório	Propósito
name	yes	ID da etapa do projeto estável.
layer	no	Human/tooling hint such as bronze, silver, gold.
description	no	Objetivo da etapa legível.
depends_on	no	Lista de nomes de etapas que devem ser concluídas antes desta etapa.
contracts	yes	Chave do adaptador para o caminho do contrato de ingestão.
expected_result	no	Dica apenas de teste, por exemplo failed em projetos de caminho de falha.

Mapeamentos de adaptador:

• Databricks renders steps as tasks in one Databricks Asset Bundle job.
• AWS renderiza etapas como tarefas Glue e pode orquestrá-las com Step Functions.
• Adaptadores futuros devem consumir o mesmo DAG antes de adicionar adaptadores específicos da plataforma detalhes de implantação.

Referências de tabelas lógicas

Os contratos do projeto devem evitar nomes de tabelas qualificados pela plataforma ao ler tables produced by earlier ContractForge steps.

Prefer:

source:
  type: table
  ref: bronze.b_products_jdbc

ou em SQL:

FROM {{ table_ref:silver.s_product_tags }}

O núcleo preserva a referência lógica layer.table. Cada adaptador renderiza o nome da tabela nativa para sua plataforma.

Metadados de validação e portabilidade

validation armazena dicas de teste e apresentação. Documentos portability diferenças intencionais quando os contratos de plataforma não podem ser byte por byte idêntico. Nenhuma seção autoriza downgrades semânticos.

validation:
  databricks:
    bundle: databricks.yml
    job_name: contractforge_usgs_geojson_medallion
  aws:
    artifact_bucket_parameter: CONTRACTFORGE_AWS_ARTIFACT_BUCKET
  snowflake:
    connection: cfingestsvc-pat
  fabric:
    workspace: contractforge
  gcp:
    project: contractforge

portability:
  invariant_contract_intent:
    - source.type
    - target.layer
    - mode
    - schema_policy
    - quality_rules
  platform_bindings:
    databricks:
      table_format: delta
    aws:
      table_format: iceberg
    snowflake:
      table_format: native
    fabric:
      table_format: delta
    gcp:
      table_format: bigquery

Commands

Validação principal:

uv run contractforge validate-project examples/real-world/supabase-jdbc-medallion

Databricks:

uv run contractforge-databricks render-project-bundle examples/real-world/supabase-jdbc-medallion/project.yaml `
  --output databricks.yml `
  --force

uv run contractforge-databricks deploy-project examples/real-world/supabase-jdbc-medallion/project.yaml `
  --render-bundle `
  --force-render `
  --target dev

AWS:

uv run contractforge-aws deploy-project examples/real-world/supabase-jdbc-medallion/project.yaml `
  --dry-run `
  --render-orchestration `
  --summary-only

uv run contractforge-aws deploy-project examples/real-world/supabase-jdbc-medallion/project.yaml `
  --deploy-orchestration `
  --summary-only

Anti-Patterns

• Não coloque source, target, mode, regras de qualidade ou política de acesso em project.yaml.
• Não coloque um cron em schedule.adapters.aws e outro em schedule.adapters.databricks, a menos que a diferença seja intencional e documented.
• Não coloque segredos no project.yaml; usar contratos ambientais e segredos references.
• Não informe o núcleo sobre trabalhos Databricks, funções de etapa AWS, Fabric tarefas JSON ou Snowflake do pipeline. O núcleo possui a intenção do projeto; adaptadores próprios artefatos nativos.
• Não edite o código de trabalho Glue ou Databricks gerado manualmente para fazer os testes passarem. Corrija o contrato, ambiente ou adaptador.