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

1. Compilação determinística: mesma entrada produz mesma saída
2. Erros reportados com arquivo, linha, coluna e contexto
3. Compilação parcial pode emitir apenas diagnósticos e/ou AST parcial (não exporta JSON/CSV/Excel)
4. Artefatos finais (JSON, CSV) gerados apenas mediante compilação completa
5. Validação de referências bibliográficas é obrigatória
6. 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"

# 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
• METADATA: Bloco opcional com metadados do projeto
• DESCRIPTION: Bloco opcional com descrição livre do projeto

---

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]
    
    # 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 Pipeline de Compilação

1.11.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.11.2 Ordem de Dependência

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

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

---

1.12 Error Handling Pedagógico

1.12.1 Princípio de Design

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

1.12.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.12.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.13 Referência Rápida de Palavras-Chave

1.13.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.13.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

1.13.3 Modificadores de Campo

Modificador	Descrição
REQUIRED	Campo obrigatório
OPTIONAL	Campo opcional
BUNDLE	Grupo de campos obrigatórios como unidade

1.13.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)

---

1.14 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.14.1 Validação de Referências Bibliográficas

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

1.14.2 Normalização e Canonicalização

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

1.14.3 Exportação para JSON

Estrutura do JSON gerado, incluindo campos location para rastreabilidade.

1.14.4 Exportação para CSV

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

1.14.5 Exportação para Excel

Organização de abas por tipo de bloco.

1.14.6 Integração com Lark Parser

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

1.14.7 Exemplos Completos de Projetos

Projetos exemplo demonstrando uso integrado de todos os componentes.

1.14.8 Boas Práticas de Anotação

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

---

1.15 Apêndice A: Sintaxe Consolidada

1.15.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

[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.15.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] ...
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

    [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.15.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.15.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.15.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