1 Synesis: Guia de Referência da Linguagem

Versão 1.1

1.1 Introdução

1.1.1 Definição

Synesis é uma Domain-Specific Language (DSL) declarativa para formalização, validação e compilação de corpora analíticos de pesquisas qualitativas. O compilador transforma anotações interpretativas em estruturas canônicas, assegurando inteligibilidade humana e rigor formal.

1.1.2 O que o Compilador Faz

Valida sintaxe e semântica de anotações
Gera AST (Abstract Syntax Tree)
Produz formatos estruturados básicos (JSON, CSV, Excel)
Normaliza conceitos via templates configuráveis

1.1.3 O que o Compilador NÃO Faz

Não é runtime ou sistema de execução
Não realiza análise estatística
Não gerencia interface de usuário
Não persiste estado entre execuções
Não cria a estrutura dos dados para você

1.1.4 Fronteiras Rígidas

O compilador processa arquivos de texto, produz artefatos estruturados e termina. Não há estado persistente, loops condicionais ou side-effects além da escrita de arquivos de saída.

1.2 Arquivos e Formatos

1.2.1 Arquivos de Entrada

Extensão	Descrição
`.synp`	Arquivo de projeto (ponto de entrada único)
`.syn`	Arquivos de anotação (SOURCE + ITEM)
`.syno`	Arquivos de ontologia (ONTOLOGY)
`.synt`	Arquivo de template (FIELD definitions)
`.bib`	Referências BibTeX/BibLaTeX

1.2.2 Arquivos de Saída

Formato	Descrição
JSON	Representação serializada completa (inclui `location` em todos os nós)
CSV	Tabelas planas por tipo de bloco (inclui colunas `source_file`, `source_line`, `source_column`)
Excel	Tabelas planas como abas
MS-Word	Corpora em forma MS-Word
REFI-QDA	Formato padrão de interoperabilidade em softwares CAQDAS
Diagnósticos	Relatório de erros com localização precisa

1.2.3 Rastreabilidade em CSV

Cada linha CSV de ITEM, CHAIN ou ONTOLOGY inclui colunas de localização:

bibref,from_code,relation,to_code,source_file,source_line,source_column
ashworth2019,Gender,INFLUENCES,CCS Support,annotations/ccs.syn,367,11

1.2.4 Invariantes do Compilador

Compilação determinística: mesma entrada produz mesma saída
Erros reportados com arquivo, linha, coluna e contexto
Compilação parcial pode emitir apenas diagnósticos e/ou AST parcial (não exporta JSON/CSV/Excel)
Artefatos finais (JSON, CSV) gerados apenas mediante compilação completa
Validação de referências bibliográficas é obrigatória
Vocabulário controlado: todo CODE e todo conceito referenciado em CHAIN deve existir como ONTOLOGY (exceto se o projeto ativar explicitamente um modo exploratório).

1.3 Estrutura do Projeto (.synp)

O arquivo de projeto orquestra os componentes da análise e serve como ponto de entrada único para o compilador.

1.3.1 Sintaxe

PROJECT project_name

TEMPLATE "filename.synt"
INCLUDE BIBLIOGRAPHY "filename.bib"
INCLUDE ANNOTATIONS "filename.syn"
INCLUDE ONTOLOGY "filename.syno"

# Ontologia compartilhada entre projetos — alvo FORA da pasta do projeto
[INCLUDE SHARED ONTOLOGY "../compartilhado/vocabulario.syno"]

# Colchetes indicam que todo o bloco METADATA é opcional
[METADATA
    version: 1.0
    author: string
    [created: date]    # Campo individual opcional
    [modified: date]   # Campo individual opcional
    [dataset: string]
END METADATA]

# Colchetes indicam que todo o bloco DESCRIPTION é opcional
[DESCRIPTION
    Texto livre descrevendo o projeto...
END DESCRIPTION]

END PROJECT

1.3.2 Semântica

PROJECT: Palavra-chave obrigatória que inicia a definição do projeto
TEMPLATE: Referência ao arquivo .synt que define as regras de validação
INCLUDE BIBLIOGRAPHY: Caminho para arquivo .bib com referências
INCLUDE ANNOTATIONS: Caminho para arquivo(s) .syn com anotações
INCLUDE ONTOLOGY: Caminho para arquivo(s) .syno com definições ontológicas
INCLUDE SHARED ONTOLOGY: Ontologia compartilhada entre projetos, localizada fora da pasta do projeto
METADATA: Bloco opcional com metadados do projeto
DESCRIPTION: Bloco opcional com descrição livre do projeto

Todos os caminhos são resolvidos relativos à pasta onde está o arquivo .synp. Por segurança, o compilador só lê arquivos contidos nessa pasta ou em suas subpastas — um caminho que escape produz o erro 75.

1.3.3 Ontologia compartilhada

INCLUDE SHARED ONTOLOGY é a única exceção à regra de contenção. Ela permite que vários projetos de um mesmo estudo usem um único vocabulário conceitual sem duplicá-lo:

INCLUDE SHARED ONTOLOGY "../compartilhado/vocabulario.syno"
INCLUDE SHARED ONTOLOGY "Z:/estudo/ontologia.syno"
INCLUDE SHARED ONTOLOGY "\\servidor\equipe\ontologia.syno"

A autorização mora na declaração — a palavra SHARED, versionada e auditável no .synp — e não na geometria do caminho. É por isso que aceita rede, outro drive ou ..: nenhuma âncora de pasta conseguiria autorizar esses casos.

SHARED vale apenas para ONTOLOGY

INCLUDE SHARED BIBLIOGRAPHY ou INCLUDE SHARED ANNOTATIONS produzem o erro 84. A exceção existe para compartilhar vocabulário conceitual; estendê-la a outros tipos abriria a contenção para casos que a motivação não pediu.

1.4 Definição de Template (.synt)

O template define a estrutura e regras de validação para anotações.

1.4.1 Cabeçalho do Template

TEMPLATE name 
[version: "string"]
[author: "string"]

1.4.2 Blocos de Campos

SOURCE FIELDS
    [REQUIRED | BUNDLE | OPTIONAL] field_name [,field_name] ...
END SOURCE FIELDS

ITEM FIELDS
    [REQUIRED | BUNDLE | OPTIONAL] field_name [,field_name] ...
END ITEM FIELDS

ONTOLOGY FIELDS
    [REQUIRED | OPTIONAL | BUNDLE] field_name [,field_name] ...
END ONTOLOGY FIELDS

1.4.3 Exemplo Completo

TEMPLATE qualitative_analysis
version: "1.0"
author: "Researcher"

# ============================================
# CAMPOS DE SOURCE
# ============================================

SOURCE FIELDS
    OPTIONAL access_date
END SOURCE FIELDS

FIELD access_date TYPE DATE
    SCOPE SOURCE
    DESCRIPTION Data de acesso a fonte
END FIELD

# ============================================
# CAMPOS DE ITEM
# ============================================

ITEM FIELDS
    REQUIRED quote
    REQUIRED BUNDLE note, chain
    OPTIONAL code
END ITEM FIELDS

FIELD quote TYPE QUOTATION
    SCOPE ITEM
    DESCRIPTION Excerto textual extraído da fonte bibliográfica
END FIELD

FIELD note TYPE MEMO
    SCOPE ITEM
    DESCRIPTION Memo analítico explicando a interpretação e mecanismo causal identificado
END FIELD

FIELD chain TYPE CHAIN
    SCOPE ITEM
    ARITY >= 2
    DESCRIPTION Cadeia causal/relacional entre conceitos da ontologia
    RELATIONS
        ENABLES: Condição necessária ou facilitadora (A permite que B ocorra)
        INFLUENCES: Efeito causal direto (A afeta ou muda B)
        CONSTRAINS: Limita ou restringe (A reduz opções ou viabilidade de B)
        CONTESTED-BY: Oposição ativa (A é contestado ou desafiado por B)
        RELATES-TO: Associação significativa genérica (A está relacionado a B)
    END RELATIONS
END FIELD

# ============================================
# CAMPOS DE ONTOLOGY
# ============================================

ONTOLOGY FIELDS
    REQUIRED description
    OPTIONAL topic
END ONTOLOGY FIELDS

FIELD description TYPE TEXT
    SCOPE ONTOLOGY
    DESCRIPTION Definição textual do conceito
END FIELD

FIELD topic TYPE TOPIC
    SCOPE ONTOLOGY
    DESCRIPTION Tópico ou domínio temático do conceito (categoria hierárquica superior dinâmica)
END FIELD

1.5 Definição de Campos (FIELD)

A declaração FIELD especifica o tipo, escopo e restrições de cada campo.

1.5.1 Sintaxe

FIELD field_name TYPE [TEXT | QUOTATION | MEMO | CHAIN | CODE | TOPIC | ORDERED | ENUMERATED | SCALE | DATE]
    SCOPE [SOURCE | ITEM | ONTOLOGY]
    [DESCRIPTION description text]

    # Modificadores de ligação entre projetos — exclusivos de SCOPE SOURCE
    [IDENTIFIES entity_label]    # chave primária da entidade
    [REFERS TO entity_label]     # chave estrangeira para a entidade

    # Propriedade exclusiva para TYPE CHAIN
    [ARITY operator number] 
    [RELATIONS
        relation_name: description
    END RELATIONS]

    # Propriedade exclusiva para TYPE ORDERED ou ENUMERATED
    [VALUES
        [index] value_name: description  # Para ORDERED
        value_name: description          # Para ENUMERATED
    END VALUES]

    # Propriedade exclusiva para TYPE SCALE
    [FORMAT [min..max]]

    # Disponível para qualquer tipo — instrução para agentes de IA
    [GUIDELINES
        Texto livre com instruções de preenchimento para o anotador ou agente de IA.
        Múltiplas linhas são permitidas. Recuo é ignorado.
    END GUIDELINES]

END FIELD

1.5.2 Exemplo Completo de FIELD

FIELD chain TYPE CHAIN
    SCOPE ITEM
    DESCRIPTION Cadeia causal entre conceitos
    ARITY >= 2
    RELATIONS
        INFLUENCES: Relação de influência causal
        ENABLES: Relação de habilitação
        INHIBITS: Relação de inibição
    END RELATIONS
END FIELD

FIELD aspect TYPE ORDERED
    SCOPE ONTOLOGY
    DESCRIPTION Aspecto modal de Dooyeweerd
    VALUES
        1 quantitative: Aspecto numérico
        2 spatial: Aspecto espacial
        3 kinematic: Aspecto cinético
        4 physical: Aspecto físico
        5 biotic: Aspecto biótico
    END VALUES
END FIELD

FIELD sentiment TYPE ENUMERATED
    SCOPE ITEM
    DESCRIPTION Sentimento expresso no excerto
    VALUES
        positive: Sentimento positivo
        negative: Sentimento negativo
        neutral: Sentimento neutro
    END VALUES
END FIELD

FIELD confidence TYPE SCALE
    SCOPE ITEM
    DESCRIPTION Nível de confiança da interpretação
    FORMAT [1..5]
END FIELD

FIELD quote TYPE QUOTATION
    SCOPE ITEM
    DESCRIPTION Excerto textual extraído da fonte
    GUIDELINES
        Extract the exact verbatim quote from the source text.
        Do not paraphrase or summarize — preserve the original wording.
        Include enough context for the quote to be self-explanatory.
        Omit only if the passage is not quotable (e.g., tables, figures).
    END GUIDELINES
END FIELD

1.5.3 Bloco GUIDELINES

O bloco GUIDELINES é um especificador opcional disponível em qualquer definição FIELD. Seu conteúdo é texto livre com instruções precisas sobre como o campo deve ser preenchido — destinado a agentes de IA ou anotadores humanos.

1.5.3.1 Propósito

GUIDELINES transforma o template de um esquema de dados em um playbook executável: em vez de instruções genéricas fornecidas separadamente à IA, cada campo carrega suas próprias regras de extração. Isso permite:

Prompt atômico por campo: A IA recebe instruções específicas para cada entidade, reduzindo ambiguidade
Rastreabilidade de decisões: As regras de extração estão codificadas no template, junto à estrutura, versionadas e auditáveis
Ciclo de feedback estruturado: A IA gera código Synesis → o compilador valida → erros de validação servem como instrução de correção automática

1.5.3.2 Sintaxe

FIELD field_name TYPE type
    SCOPE scope
    GUIDELINES
        Linha 1 de instrução.
        Linha 2 de instrução.
        Linha N de instrução.
    END GUIDELINES
END FIELD

1.5.3.3 Semântica

O conteúdo é texto livre — qualquer caractere é permitido
Múltiplas linhas são preservadas com suas quebras de linha
Recuo interno é ignorado (as linhas são dedentadas automaticamente)
Um bloco vazio (GUIDELINES imediatamente seguido de END GUIDELINES) resulta em valor null no JSON exportado
O valor compilado é exportado no campo "guidelines" do JSON de cada FieldSpec
O compilador não interpreta nem valida o conteúdo — é tratado como dado opaco

1.5.3.4 Exemplo de uso com IA

FIELD note TYPE MEMO
    SCOPE ITEM
    DESCRIPTION Memo analítico do mecanismo causal identificado
    GUIDELINES
        Identify the causal mechanism linking the quote to the research question.
        State the mechanism in one sentence: "[Factor] [verb] [outcome] because [reason]."
        Ground the interpretation in the text — do not infer beyond what is stated.
        If causality is ambiguous, describe the relationship as associative.
    END GUIDELINES
END FIELD

FIELD chain TYPE CHAIN
    SCOPE ITEM
    ARITY >= 2
    RELATIONS
        INFLUENCES: Efeito causal direto
        ENABLES: Condição necessária ou facilitadora
        INHIBITS: Limitação ou restrição
    END RELATIONS
    GUIDELINES
        Map the causal structure identified in the note field as a formal chain.
        Use only concepts that exist in the ontology (ONTOLOGY blocks).
        Chain elements at odd positions must be concept names; even positions must be RELATIONS.
        Prefer specific relations (ENABLES, INHIBITS) over generic ones (INFLUENCES).
    END GUIDELINES
END FIELD

1.6 Tipos de Campo

1.6.1 Tabela de Tipos

Tipo	Escopo	Semântica
QUOTATION	ITEM	Excerto textual da fonte
MEMO	ITEM	Anotação analítica do pesquisador
CODE	ITEM	Rótulo conceitual (categorização)
CHAIN	ITEM	Relação qualificada entre códigos
TEXT	qualquer	Texto livre genérico
DATE	SOURCE	Data com formato especificado
SCALE	qualquer	Valor numérico em intervalo [min..max]
ENUMERATED	qualquer	Valor de lista fechada sem hierarquia
ORDERED	qualquer	Valor de lista com hierarquia ordinal indexada
TOPIC	ONTOLOGY	Categoria hierárquica superior (agrupamento dinâmico)

1.6.2 Distinção: Linguagem vs Template

Nível	FIXO (linguagem)	CONFIGURÁVEL (template)
Palavras-chave	`SOURCE`, `ITEM`, `ONTOLOGY`, `FIELD`, `END`	Nomes de campos como `aspect`, `quote`
Tipos de dados	`QUOTATION`, `MEMO`, `CODE`, `CHAIN`, `TEXT`, etc.	Valores em listas ORDERED/ENUMERATED
Estrutura	Blocos SOURCE/ITEM/ONTOLOGY, sintaxe FIELD…END	Quais campos são REQUIRED/OPTIONAL
Modificadores	`BUNDLE`, `REQUIRED`, `OPTIONAL`, `SCOPE`, `TYPE`	Quais campos usar BUNDLE

1.7 Blocos Estruturais

1.7.1 SOURCE

Contextualiza ITEMs com referência bibliográfica. Cada SOURCE referencia exatamente uma entrada do arquivo .bib.

SOURCE @bibref                # ← Referência obrigatória ao .bib
    [field_name: value]       # ← Campos opcionais do SOURCE
    ...

END SOURCE

ITEM @bibref                  # ← Um ou mais ITEMs obrigatórios
    ...

END ITEM

Exemplo anotado:

SOURCE @smith2023             # ← Deve existir em referencias.bib
    access_date: 2025-01-15   # ← Campo opcional definido no template
END SOURCE                   # ← Fecha o bloco SOURCE

ITEM @smith2023               # ← Primeiro item de análise
    quote: "The technology shows promising results."
    note: Autor expressa otimismo sobre resultados
    chain: Technology -> INFLUENCES -> Acceptance
END ITEM

1.7.2 ITEM

Unidade analítica fundamental. Contém excerto, memos, códigos e/ou cadeias. Pertence a exatamente um SOURCE.

ITEM [@bibref]                # ← Referência ao SOURCE pai
    field_name: value         # ← Um ou mais campos obrigatórios
    [field_name: value] ...   # ← Campos adicionais conforme template
END ITEM

Exemplo anotado:

ITEM @ref2025                 # ← Referência para rastreabilidade
    quote: Texto extraído     # ← Campo obrigatório (QUOTATION)

    note: Primeira interp.    # ← Primeiro par do BUNDLE
    chain: A -> INFLUENCES -> B

    note: Segunda interp.     # ← Segundo par do BUNDLE (mesma quantidade)
    chain: C -> ENABLES -> D
END ITEM                      # ← Fecha o bloco ITEM

1.7.3 ONTOLOGY

Define conceito do vocabulário controlado. Estrutura plana com possibilidade de hierarquia.

ONTOLOGY concept_name         # ← Nome do conceito (não pode conter espaços)
    field_name: value         # ← Um ou mais campos obrigatórios
    [field_name: value] ...   # ← Campos adicionais conforme template
END ONTOLOGY

Exemplo anotado:

ONTOLOGY Cost                 # ← Nome simples (sem espaços)
    topic: Economics          # ← Agrupamento dinâmico (TOPIC)
    description: Economic factor representing financial expenditure
END ONTOLOGY

ONTOLOGY Public_Acceptance    # ← Nome sem espaços (sem aspas)
    topic: Social_Factors     # ← Mesmo topic agrupa conceitos relacionados
    description: Community-level support for technology
END ONTOLOGY

1.8 Cadeias Semânticas (CHAIN)

1.8.1 Chain Qualificada

Quando o template define RELATIONS, a cadeia usa o padrão: posições ímpares são códigos, posições pares são tipos de relação.

chain: Code -> RELATION -> Code [-> RELATION -> Code] ...
#      ^^^^    ^^^^^^^^    ^^^^
#      código  relação     código (padrão alternado)

Exemplo anotado:

chain: Climate_Belief -> INFLUENCES -> Support
#      ^^^^^^^^^^^^^    ^^^^^^^^^^    ^^^^^^^
#      código (origem)  relação       código (destino)

chain: A -> INFLUENCES -> B -> ENABLES -> C
#      ^    ^^^^^^^^^^    ^    ^^^^^^^    ^
#      cod1 rel1          cod2 rel2       cod3 (cadeia estendida)

1.8.2 Chain Simples

Quando o template NÃO define RELATIONS, apenas códigos são separados por ->. A relação é implícita.

chain: Code -> Code [-> Code] ...
#      ^^^^    ^^^^
#      origem  destino (relação implícita entre cada par)

Exemplo anotado:

chain: A -> B             # ← Relação implícita: A relaciona-se com B
chain: A -> B -> C        # ← Duas relações implícitas: A→B e B→C

1.8.3 Conceitos sem aspas

O parser captura conceitos compostos sem exigir aspas, mas é preciso evitar espaços.

Anotação incorreta:

chain: Institutional Barrier -> ENABLES -> Financial Barrier
#      ^^^^^^^^^^^^^^^^^^^^              ^^^^^^^^^^^^^^^^^^
#      conceito com espaços              conceito com espaços

Anotação correta

chain: Public_Acceptance -> INFLUENCES -> CCS_Support -> ENABLES -> Deployment
#      ^^^^^^^^^^^^^^^^^                  ^^^^^^^^^^^               ^^^^^^^^^^
#      2 palavras                         2 palavras                1 palavra

1.9 Modificador BUNDLE

O modificador BUNDLE define grupos de campos que formam unidade mínima repetível de interpretação.

1.9.1 Sintaxe

ITEM FIELDS
    REQUIRED BUNDLE field_name, field_name [,field_name] ...
    #        ^^^^^^ ^^^^^^^^^^  ^^^^^^^^^^
    #        modif. campo1      campo2 (devem aparecer juntos)
END ITEM FIELDS

1.9.2 Semântica

Campos em BUNDLE são obrigatórios como unidade indivisível
Mínimo 1 ocorrência do bundle completo
Campos do bundle nunca aparecem isoladamente
Devem aparecer em igual quantidade: len(field1) == len(field2) == len(field3) >= 1
Correspondência posicional: field1[i] relaciona-se com field2[i] e field3[i]

1.9.3 Exemplo Anotado

ITEM @ref2025
    quote: Texto extraído da fonte    # ← Campo independente

    note: Primeira interpretação      # ← bundle[0].note
    chain: A -> INFLUENCES -> B       # ← bundle[0].chain (par 1)

    note: Segunda interpretação       # ← bundle[1].note
    chain: C -> ENABLES -> D          # ← bundle[1].chain (par 2)
END ITEM
# Resultado: 2 pares note+chain, correspondência posicional garantida

1.9.4 Validação

Campo isolado de bundle: erro
Contagens diferentes: erro
Ausência completa de bundle obrigatório: erro
Violação de BUNDLE gera erro de compilação (não warning)

1.10 Tipo TOPIC

O tipo TOPIC permite definir categorias hierárquicas superiores que agrupam conceitos ontológicos de forma dinâmica, sem pré-definição no template.

1.10.1 Diferença de ENUMERATED

Característica	ENUMERATED	TOPIC
Valores permitidos	Lista fechada pré-definida	Aberto, dinâmico
Uso	Categorização controlada	Agrupamento emergente
Validação	Rejeita valores fora da lista	Aceita qualquer string

1.10.2 Exemplo Anotado

ONTOLOGY Cost
    topic: Economics              # ← Categoria emergente (não pré-definida)
    description: Economic factor representing financial expenditure
END ONTOLOGY

ONTOLOGY Public_Acceptance
    topic: Social_Factors         # ← Outra categoria emergente
    description: Community-level support for technology
END ONTOLOGY

# Resultado: dois topics criados dinamicamente (Economics, Social Factors)
# O compilador aceita qualquer string sem espaços como valor de TOPIC

1.11 Ligação entre Projetos (IDENTIFIES / REFERS TO)

Permite triangular corpora heterogêneos — currículos, abstracts, perfis institucionais — sem transformá-los numa única unidade de compilação. Cada projeto continua independente, rápido e autônomo; a ligação é declarada no template e resolvida num passo explícito na CLI.

O modelo é o do linker de C/C++: cada projeto compila isolado e expõe suas referências externas não resolvidas; um passo de linkagem (synesis compile p1.synp p2.synp) resolve as referências entre eles e produz o agregado.

1.11.1 Os dois modificadores

Modificador	Papel relacional	Semântica
`IDENTIFIES <entidade>`	Chave primária (PK)	O campo identifica a entidade. Cada valor corresponde a um único SOURCE. Cria o nó.
`REFERS TO <entidade>`	Chave estrangeira (FK)	O campo aponta para a entidade. Pode repetir. Não cria nó.

Ambos são exclusivos de campos SCOPE SOURCE — a ligação opera sobre SOURCEs, as unidades de coleta. Usá-los em SCOPE ITEM ou SCOPE ONTOLOGY produz o erro 78.

1.11.2 Sintaxe

O projeto proprietário da entidade declara a chave primária:

# lattes.synt — o corpus de currículos é dono da entidade "researcher"
FIELD lattes_id TYPE TEXT
    SCOPE SOURCE
    DESCRIPTION Identificador Lattes do pesquisador
    IDENTIFIES researcher
END FIELD

Os projetos periféricos apontam para ela:

# abstracts.synt — cada artigo aponta para o pesquisador que o escreveu
FIELD autor_id TYPE TEXT
    SCOPE SOURCE
    DESCRIPTION Identificador Lattes do autor
    REFERS TO researcher
END FIELD

Note que o projeto periférico não nomeia o projeto proprietário — apenas o rótulo da entidade. Adicionar um terceiro corpus ao estudo não exige editar nenhum template existente.

1.11.3 Origem do valor: `ON BIBLIOGRAPHY`

Alguns identificadores são metadados da fonte, não conteúdo extraível do texto. ON BIBLIOGRAPHY declara que o valor vive na entrada .bib do SOURCE:

SOURCE FIELDS
    REQUIRED lattes_id ON BIBLIOGRAPHY
    OPTIONAL orcid ON BIBLIOGRAPHY
END SOURCE FIELDS

@misc{curriculo_maria,
    author    = {Silva, Maria},
    title     = {Currículo Lattes},
    year      = {2026},
    lattes_id = {3474000000000167}
}

O sufixo só é válido em cláusula de campo único. REQUIRED a, b ON BIBLIOGRAPHY é erro de sintaxe — numa lista, seria ambíguo a qual campo o sufixo se aplica.

Campos ON BIBLIOGRAPHY são excluídos da verificação de campo obrigatório do bloco SOURCE (erro 21), já que o valor não vive no bloco. Se o valor faltar no .bib, o erro emitido é o 79.

1.11.4 Compilação isolada

Um projeto com REFERS TO compila normalmente sozinho. O compilador emite apenas uma mensagem INFO (informativo 80) registrando que há ligações a materializar — nunca erro ou aviso:

synesis compile abstracts.synp --json abstracts.json

INFO  abstracts.synp
  Este projeto referencia a entidade externa `researcher` (`REFERS TO` em `autor_id`).

1.11.5 Passo de linkagem

Com dois ou mais projetos, o comando compile resolve as ligações:

synesis compile lattes.synp abstracts.synp --json estudo.json --csv saida/

O passo de linkagem:

Compila cada membro isoladamente (validação completa, independente)
Resolve cada REFERS TO contra o IDENTIFIES proprietário, por rótulo de entidade + igualdade exata do valor
Gera uma aresta por casamento — suporta n:1 e n:n (campo multivalorado gera uma aresta por valor)
Qualifica os bibrefs por alias de membro (abstracts:@artigo_a), dissolvendo colisões entre corpora

O compilador nunca funde entidades

A comparação é por igualdade exata após remover espaços nas pontas — sem normalização de maiúsculas/minúsculas. Um valor que casaria apenas sob normalização vira aviso de quase-casamento (erro 83), com sugestão de canonizar na origem. Fundir automaticamente uniria entidades que a fonte considera distintas.

1.11.6 Saídas do agregado

Flag	Comportamento no passo de linkagem
`--json`	Agregado no schema v3.1 (aditivo): `kind: "link"`, `entity_owners`, seção `links` com arestas e órfãos
`--csv`	Gera `links.csv` com as arestas resolvidas
`--stats`	Estatísticas por membro e agregadas (ontologia compartilhada é deduplicada, não somada)
`--xls`	Sem exportador — emite aviso explícito
`--alpaca`	Sem exportador — emite aviso explícito

O schema v3.1 é aditivo: consumidores da v3.0 ignoram as chaves novas.

--xls e --alpaca não têm exportador no agregado porque SOURCE FIELDS diverge entre membros — não existe tabela única coerente. A lacuna é reportada em vez de falhar em silêncio.

O LSP nunca carrega o agregado

A linkagem é exclusiva da CLI. O servidor LSP sempre trabalha com projetos isolados — é o que mantém a edição rápida mesmo em estudos com muitos corpora grandes.

Ver o guia Ligar Projetos Independentes para o fluxo completo com exemplos.

1.12 Pipeline de Compilação

1.12.1 Etapas Obrigatórias

#	Etapa	Responsabilidade
1	Descoberta	Ler .synp, resolver caminhos, listar arquivos
2	Template Loading	Parsear e validar .synt (define regras)
3	BibTeX Loading	Carregar .bib, construir índice de referências
4	Parsing Sintático	Lark processa cada arquivo .syn e .syno
5	Transformação	Converter árvores concretas em AST tipada
6	Validação Semântica	Verificar referências, tipos, campos obrigatórios
7	Normalização	Aplicar defaults, canonicalização de valores
8	Vinculação	Associar ITEMs a SOURCEs, CODEs e CHAINs a ONTOLOGYs
9	Vinculação	Verificar que todo code: referencia um conceito existente na ontologia
10	Vinculação	Verificar que todo nó de chain: (códigos nas posições ímpares) referencia um conceito existente na ontologia
11	Vinculação	Verificar que toda RELATION usada na chain existe em RELATIONS do template
12	Exportação	Gerar JSON, CSV, MS-Word, REFI-QDA

1.12.2 Ordem de Dependência

Projeto = Template + BibTeX + Anotações + Ontologia

O parser lê tudo, depois valida/resolve a consistência.

1.13 Error Handling Pedagógico

1.13.1 Princípio de Design

O compilador prioriza mensagens de erro educativas que ensinam a sintaxe correta sem exigir leitura do manual.

1.13.2 Detector de “Vírgula Ausente” em Listas CODE

Erro comum:

code: Climate_Belief Risk_Perception  # ERRO: falta vírgula

Mensagem sugerida:

erro: arquivo.syn:3:26: Múltiplos códigos devem ser separados por vírgula.
    code: Climate_Belief Risk_Perception
                         ^~~~ falta vírgula antes de "Risk"

Use vírgula para separar códigos:
    code: Climate_Belief, Risk_Perception

OU especifique cada código em linha separada:
    code: Climate_Belief
    code: Risk_Perception

1.13.3 Detector de “Cadeia Malformada” em CHAIN

Erro comum:

chain: Climate_Belief INFLUENCES Support  # ERRO: falta "->"

Mensagem sugerida:

erro: arquivo.syn:2:27: Cadeia causal exige operador '->' entre elementos.
    chain: Climate_Belief INFLUENCES Support
                          ^~~~~~~~~~~ falta '->' antes de "INFLUENCES"

Use '->' para conectar elementos:
    chain: Climate_Belief -> INFLUENCES -> Support

1.14 Referência Rápida de Palavras-Chave

1.14.1 Palavras-Chave de Estrutura

Palavra-chave	Descrição
`PROJECT`	Inicia definição de projeto
`TEMPLATE`	Referência ao arquivo de template ou início de definição
`SOURCE`	Bloco de fonte bibliográfica
`ITEM`	Unidade analítica
`ONTOLOGY`	Definição de conceito
`FIELD`	Definição de campo
`END`	Encerra qualquer bloco (necessita qualificação)

1.14.2 Palavras-Chave de Inclusão

Palavra-chave	Descrição
`INCLUDE`	Inclui arquivo externo
`BIBLIOGRAPHY`	Tipo de inclusão para .bib
`ANNOTATIONS`	Tipo de inclusão para .syn
`SHARED`	Autoriza alvo fora da pasta do projeto (apenas com `ONTOLOGY`)

1.14.3 Modificadores de Campo

Modificador	Descrição
`REQUIRED`	Campo obrigatório
`OPTIONAL`	Campo opcional
`BUNDLE`	Grupo de campos obrigatórios como unidade
`ON BIBLIOGRAPHY`	O valor do campo vem da entrada `.bib`, não do texto (cláusula de campo único)

1.14.4 Especificadores de Campo

Especificador	Descrição
`TYPE`	Define o tipo do campo
`SCOPE`	Define o escopo (SOURCE, ITEM, ONTOLOGY)
`DESCRIPTION`	Texto descritivo do campo
`ARITY`	Restrição de aridade para CHAIN
`RELATIONS`	Lista de relações para CHAIN
`VALUES`	Lista de valores para ORDERED/ENUMERATED
`FORMAT`	Formato para SCALE
`GUIDELINES`	Instruções de preenchimento para o anotador ou agente de IA (qualquer tipo)
`IDENTIFIES`	Declara o campo como chave primária de uma entidade (apenas `SCOPE SOURCE`)
`REFERS TO`	Declara o campo como chave estrangeira para uma entidade (apenas `SCOPE SOURCE`)

1.15 Seções (Sugeridas para Expansão da documentação)

As seções abaixo estão indicadas como tópicos para desenvolvimento futuro do guia.

1.15.1 Validação de Referências Bibliográficas

Como o compilador valida que cada @bibref existe no arquivo .bib incluído.

1.15.2 Normalização e Canonicalização

Regras para normalização de valores e conceitos via template.

1.15.3 Exportação para JSON

Estrutura do JSON gerado, incluindo campos location para rastreabilidade.

1.15.4 Exportação para CSV

Formato das tabelas planas por tipo de bloco, colunas de rastreabilidade.

1.15.5 Exportação para Excel

Organização de abas por tipo de bloco.

1.15.6 Integração com Lark Parser

Detalhes técnicos do parser utilizado para processamento sintático.

1.15.7 Exemplos Completos de Projetos

Projetos exemplo demonstrando uso integrado de todos os componentes.

1.15.8 Boas Práticas de Anotação

Recomendações para estruturação consistente de anotações qualitativas.

1.16 Apêndice A: Sintaxe Consolidada

1.16.1 Projeto (.synp)

PROJECT project_name              # ← Nome do projeto (obrigatório)

TEMPLATE "filename.synt"          # ← Arquivo de template (obrigatório)
INCLUDE BIBLIOGRAPHY "filename.bib"   # ← Referências BibTeX
INCLUDE ANNOTATIONS "filename.syn"    # ← Arquivos de anotação
INCLUDE ONTOLOGY "filename.syno"      # ← Arquivos de ontologia

[INCLUDE SHARED ONTOLOGY "../path.syno"]  # ← Ontologia fora da pasta do projeto

[METADATA                         # ← Bloco opcional
    version: 1.0
    author: string
    [created: date]               # ← Campo opcional dentro do bloco
    [modified: date]
    [dataset: string]
END METADATA]

[DESCRIPTION                      # ← Bloco opcional
    Texto livre descrevendo o projeto...
END DESCRIPTION]

END PROJECT                        # ← Fecha o PROJECT

1.16.2 Template (.synt)

TEMPLATE name                     # ← Nome do template (obrigatório)
[version: "string"]               # ← Metadado opcional
[author: "string"]

SOURCE FIELDS                     # ← Campos válidos em blocos SOURCE
    [REQUIRED | BUNDLE | OPTIONAL] field_name [,field_name] ...
    [REQUIRED | OPTIONAL] field_name ON BIBLIOGRAPHY  # ← Valor vem do .bib (campo único)
END SOURCE FIELDS

ITEM FIELDS                       # ← Campos válidos em blocos ITEM
    [REQUIRED | BUNDLE | OPTIONAL] field_name [,field_name] ...
END ITEM FIELDS

ONTOLOGY FIELDS                   # ← Campos válidos em blocos ONTOLOGY
    [REQUIRED | OPTIONAL | BUNDLE] field_name [,field_name] ...
END ONTOLOGY FIELDS

FIELD field_name TYPE [TEXT | QUOTATION | MEMO | CHAIN | CODE | TOPIC | ORDERED | ENUMERATED | SCALE]
    SCOPE [SOURCE | ITEM | ONTOLOGY]  # ← Onde o campo pode ser usado
    [DESCRIPTION description text]
    
    [ARITY operator number]       # ← Apenas para CHAIN
    [RELATIONS                    # ← Apenas para CHAIN
        relation_name: description
    END RELATIONS]

    [VALUES                       # ← Apenas para ORDERED/ENUMERATED
        [index] value_name: description
    END VALUES]

    [FORMAT [min..max]]           # ← Apenas para SCALE

    [IDENTIFIES entity_label]     # ← Chave primária — apenas SCOPE SOURCE
    [REFERS TO entity_label]      # ← Chave estrangeira — apenas SCOPE SOURCE

    [GUIDELINES                   # ← Qualquer tipo — instrução para anotador ou IA
        Texto livre com instruções de preenchimento.
        Múltiplas linhas permitidas.
    END GUIDELINES]

END FIELD

1.16.3 Anotações (.syn)

SOURCE @bibref                    # ← Referência ao .bib (obrigatório)
    [field_name: value]           # ← Campos do SOURCE (conforme template)        
END SOURCE

ITEM @bibref                  # ← Referência ao .bib (obrigatório)
    field_name: value         # ← Campos obrigatórios
    [field_name: value] ...   # ← Campos opcionais
END ITEM

1.16.4 Ontologia (.syno)

ONTOLOGY concept_name             # ← Nome do conceito (sem espaços)
    field_name: value             # ← Campos obrigatórios
    [field_name: value] ...       # ← Campos opcionais
END ONTOLOGY

1.16.5 Cadeias (CHAIN)

# Chain qualificada (com RELATIONS definidas no template)
chain: Code -> RELATION -> Code [-> RELATION -> Code] ...
#      ^^^^    ^^^^^^^^    ^^^^
#      código  relação     código (padrão alternado obrigatório)

# Chain simples (sem RELATIONS no template)
chain: Code -> Code [-> Code] ...
#      ^^^^    ^^^^
#      origem  destino (relação implícita)

Documento gerado a partir da especificação Synesis v1.1

1 Synesis: Guia de Referência da Linguagem

1.1 Introdução

1.1.1 Definição

1.1.2 O que o Compilador Faz

1.1.3 O que o Compilador NÃO Faz

1.1.4 Fronteiras Rígidas

1.2 Arquivos e Formatos

1.2.1 Arquivos de Entrada

1.2.2 Arquivos de Saída

1.2.3 Rastreabilidade em CSV

1.2.4 Invariantes do Compilador

1.3 Estrutura do Projeto (.synp)

1.3.1 Sintaxe

1.3.2 Semântica

1.3.3 Ontologia compartilhada

1.4 Definição de Template (.synt)

1.4.1 Cabeçalho do Template

1.4.2 Blocos de Campos

1.4.3 Exemplo Completo

1.5 Definição de Campos (FIELD)

1.5.1 Sintaxe

1.5.2 Exemplo Completo de FIELD

1.5.3 Bloco GUIDELINES

1.5.3.1 Propósito

1.5.3.2 Sintaxe

1.5.3.3 Semântica

1.5.3.4 Exemplo de uso com IA

1.6 Tipos de Campo

1.6.1 Tabela de Tipos

1.6.2 Distinção: Linguagem vs Template

1.7 Blocos Estruturais

1.7.1 SOURCE

1.7.2 ITEM

1.7.3 ONTOLOGY

1.8 Cadeias Semânticas (CHAIN)

1.8.1 Chain Qualificada

1.8.2 Chain Simples

1.8.3 Conceitos sem aspas

1.9 Modificador BUNDLE

1.9.1 Sintaxe

1.9.2 Semântica

1.9.3 Exemplo Anotado

1.9.4 Validação

1.10 Tipo TOPIC

1.10.1 Diferença de ENUMERATED

1.10.2 Exemplo Anotado

1.11 Ligação entre Projetos (IDENTIFIES / REFERS TO)

1.11.1 Os dois modificadores

1.11.2 Sintaxe

1.11.3 Origem do valor: ON BIBLIOGRAPHY

1.11.4 Compilação isolada

1.11.5 Passo de linkagem

1.11.6 Saídas do agregado

1.12 Pipeline de Compilação

1.12.1 Etapas Obrigatórias

1.12.2 Ordem de Dependência

1.13 Error Handling Pedagógico

1.13.1 Princípio de Design

1.13.2 Detector de “Vírgula Ausente” em Listas CODE

1.13.3 Detector de “Cadeia Malformada” em CHAIN

1.14 Referência Rápida de Palavras-Chave

1.14.1 Palavras-Chave de Estrutura

1.14.2 Palavras-Chave de Inclusão

1.14.3 Modificadores de Campo

1.14.4 Especificadores de Campo

1.15 Seções (Sugeridas para Expansão da documentação)

1.15.1 Validação de Referências Bibliográficas

1.15.2 Normalização e Canonicalização

1.15.3 Exportação para JSON

1.15.4 Exportação para CSV

1.15.5 Exportação para Excel

1.15.6 Integração com Lark Parser

1.15.7 Exemplos Completos de Projetos

1.15.8 Boas Práticas de Anotação

1.16 Apêndice A: Sintaxe Consolidada

1.16.1 Projeto (.synp)

1.16.2 Template (.synt)

1.16.3 Anotações (.syn)

1.16.4 Ontologia (.syno)

1.16.5 Cadeias (CHAIN)

1.11.3 Origem do valor: `ON BIBLIOGRAPHY`