Como Definir uma Ontologia

Guia prático para criar vocabulários conceituais estruturados

1 Como Definir uma Ontologia

Este guia mostra como criar e organizar ontologias (.syno) para estruturar seu vocabulário conceitual de forma sistemática e auditável.

Você deve usar este guia se:

Precisa definir códigos conceituais reutilizáveis
Quer organizar códigos por grupos temáticos
Quer garantir consistência terminológica no projeto

1.1 Estrutura Básica de uma Ontologia

Uma ontologia Synesis é um conjunto de blocos ONTOLOGY, cada um definindo um conceito. Os campos disponíveis em cada bloco dependem do template do projeto — tipicamente descricao (definição textual) e grupo (categoria temática).

1.1.1 Exemplo Mínimo

ONTOLOGY conceito_a
    descricao: "Descrição clara do que significa este conceito"
    grupo: tema_principal
END ONTOLOGY

Cada bloco define um único conceito, identificado por um nome em snake_case (sem espaços ou acentos).

1.2 Como Adicionar Conceitos

1.2.1 Conceitos Simples

Para adicionar conceitos ao vocabulário do projeto:

ONTOLOGY custo
    descricao: "Fatores relacionados a preço, orçamento e viabilidade econômica"
    grupo: barreiras_a_adocao
END ONTOLOGY

ONTOLOGY complexidade_tecnica
    descricao: "Percepção de dificuldade de uso ou necessidade de expertise"
    grupo: barreiras_a_adocao
END ONTOLOGY

1.2.2 Conceitos com Variações Terminológicas

Quando diferentes fontes usam termos diferentes para o mesmo conceito, documente isso no campo descricao e unifique sob um único nome canônico:

ONTOLOGY resistencia_organizacional
    descricao: "Oposição cultural ou estrutural à mudança. Também referida como 'inércia institucional' ou 'resistência à mudança' nas fontes."
    grupo: fatores_contextuais
END ONTOLOGY

Quando usar: Quando colaboradores ou fontes diferentes usam termos distintos para o mesmo fenômeno. O nome canônico é o que aparece em code: e chain: nas anotações.

1.2.3 Conceitos Hierárquicos

Para expressar relações “é-um-tipo-de”, use o campo grupo para agrupar subcategorias e nomeie os conceitos de forma que a hierarquia seja legível:

ONTOLOGY infraestrutura
    descricao: "Recursos técnicos disponíveis para operação do sistema"
    grupo: fatores_tecnologicos
END ONTOLOGY

ONTOLOGY infraestrutura_hardware
    descricao: "Equipamentos físicos necessários"
    grupo: fatores_tecnologicos
END ONTOLOGY

ONTOLOGY infraestrutura_software
    descricao: "Aplicações e sistemas de suporte"
    grupo: fatores_tecnologicos
END ONTOLOGY

ONTOLOGY infraestrutura_conectividade
    descricao: "Capacidade de rede e banda larga"
    grupo: fatores_tecnologicos
END ONTOLOGY

Quando usar: Quando há relação de subtipo entre conceitos. O prefixo compartilhado (infraestrutura_) torna a hierarquia explícita sem exigir nesting sintático.

1.3 Como Organizar Conceitos por Grupos

O campo grupo é o mecanismo central de organização. Use valores consistentes para agrupar conceitos relacionados.

1.3.1 Por Dimensão Analítica

ONTOLOGY custo_inicial
    descricao: "Investimento necessário para implementação"
    grupo: dimensao_economica
END ONTOLOGY

ONTOLOGY roi_esperado
    descricao: "Expectativa de retorno sobre investimento"
    grupo: dimensao_economica
END ONTOLOGY

ONTOLOGY aceitacao_da_equipe
    descricao: "Grau de adesão dos colaboradores à mudança"
    grupo: dimensao_social
END ONTOLOGY

ONTOLOGY pressao_de_pares
    descricao: "Influência de colegas na decisão de adotar"
    grupo: dimensao_social
END ONTOLOGY

Exemplo de ontologia complexa:

ONTOLOGY Public_Acceptance
    topic: Social
    aspect: 10 Social
    dimension: 1 Social-Political
    confidence: HIGH

    reasoning: Aspect 10 (Social) reflects community and collective dynamics central to acceptance. Primarily enables deployment and constrains policy/CCS implementation, functioning as facilitator and barrier. Co-occurs with stakeholder engagement, transparency, and trust-building. Dimension 1 (Community Acceptance) reflects residents and local stakeholders requiring transparent communication. High frequency (20) across 11 sources indicates robust centrality.

    description: The degree to which local communities, residents, and stakeholders support or oppose energy transition technologies and infrastructure projects. Shaped by transparent communication, environmental impact assessments, and trust-building efforts. Critical for technology deployment, requiring careful stakeholder engagement and alignment with sustainability values to overcome resistance and enable implementation.

    rgt_element_a: High_Public_Acceptance
    rgt_element_b: Low_Public_Acceptance
    theoretical_significance: 0
END ONTOLOGY

Quando usar: Para análises multi-dimensionais (econômico, social, técnico, político).

1.3.2 Por Fase do Processo

ONTOLOGY conscientizacao
    descricao: "Conhecimento sobre existência da tecnologia"
    grupo: pre_adocao
END ONTOLOGY

ONTOLOGY avaliacao_de_alternativas
    descricao: "Comparação entre opções disponíveis"
    grupo: decisao
END ONTOLOGY

ONTOLOGY satisfacao
    descricao: "Percepção de atendimento de expectativas após adoção"
    grupo: pos_adocao
END ONTOLOGY

Quando usar: Para análises processuais ou longitudinais.

1.3.3 Por Stakeholder

ONTOLOGY alinhamento_estrategico
    descricao: "Compatibilidade com objetivos organizacionais"
    grupo: perspectiva_gestores
END ONTOLOGY

ONTOLOGY usabilidade
    descricao: "Facilidade de operação cotidiana"
    grupo: perspectiva_usuarios_finais
END ONTOLOGY

Quando usar: Para análises multi-perspectiva ou estudos de stakeholders.

1.4 Como Definir Relações Causais

Relações usadas em chain: são declaradas no template do projeto (.synt), não na ontologia. Veja Como Criar Chains para detalhes.

No template:

FIELD chain TYPE CHAIN
    SCOPE ITEM
    DESCRIPTION Cadeia causal entre conceitos
    RELATIONS
        CAUSA: X é causa direta de Y
        INIBE: X reduz ou impede Y
        FAVORECE: X promove ou facilita Y
        MEDIA: X é intermediário entre A e Y
    END RELATIONS
END FIELD

Nas anotações, use as relações declaradas:

chain: custo_alto -> INIBE -> adocao
chain: treinamento -> MEDIA -> usabilidade -> FAVORECE -> adocao

1.5 Como Validar Sua Ontologia

Após criar ou modificar .syno, sempre valide:

synesis check ontology/minha_ontologia.syno

Erros comuns:

Erro	Causa	Solução
`Concept 'X' already defined`	Conceito duplicado	Remova a duplicata ou escolha nome diferente
`descricao required`	Falta definição	Adicione `descricao: "..."` ao bloco
`Invalid concept name`	Nome com espaços ou acentos	Use snake_case: `nome_do_conceito`

1.6 Como Referenciar Conceitos nas Anotações

Após definir na ontologia, use em .syn:

ITEM @fonte_01
    quote: "O preço é muito alto"
    code: custo  # Deve estar definido na ontologia
END ITEM

Regra: Todo conceito usado em code: ou chain: deve existir na ontologia. O compilador rejeitará conceitos não definidos.

1.7 Como Evoluir Ontologias ao Longo do Projeto

1.7.1 Adicionar Novo Conceito

Abra ontology/codes.syno
Adicione um novo bloco ONTOLOGY conceito / descricao: / grupo: / END ONTOLOGY
Valide: synesis check ontology/codes.syno
Re-compile o projeto

1.7.2 Renomear Conceito Existente

Não há mecanismo automático de alias — renomear exige atualização manual:

Renomeie o bloco ONTOLOGY na ontologia
Use “Find & Replace” em todos os arquivos .syn para atualizar code: e chain:
Valide tudo: synesis check analysis.synp

Estratégia de renomeação segura

Antes de renomear, compile e exporte para CSV. O arquivo codes.csv lista todas as ocorrências do conceito — use-o para identificar quais anotações precisam ser atualizadas.

1.7.3 Dividir Conceito Amplo

Se um conceito se tornou ambíguo, crie conceitos mais específicos:

# Antes: um único conceito amplo
ONTOLOGY custo
    descricao: "Todos os fatores econômicos"
    grupo: fatores_economicos
END ONTOLOGY

# Depois: dois conceitos específicos
ONTOLOGY custo_de_aquisicao
    descricao: "Preço de compra inicial"
    grupo: fatores_economicos
END ONTOLOGY

ONTOLOGY custo_de_manutencao
    descricao: "Despesas recorrentes de operação"
    grupo: fatores_economicos
END ONTOLOGY

Atenção: Revise manualmente as anotações que usavam o conceito original e decida qual dos novos conceitos mais específicos se aplica a cada caso.

1.8 Exemplos de Ontologias por Área

1.8.1 Pesquisa Qualitativa (Análise Temática)

ONTOLOGY experiencia_vivida
    descricao: "Relatos diretos de vivências pessoais"
    grupo: temas_descritivos
END ONTOLOGY

ONTOLOGY contexto_social
    descricao: "Fatores socioculturais envolvidos na experiência relatada"
    grupo: temas_descritivos
END ONTOLOGY

ONTOLOGY padrao_emergente
    descricao: "Regularidade identificada entre casos"
    grupo: temas_analiticos
END ONTOLOGY

ONTOLOGY contradicao_aparente
    descricao: "Tensão entre perspectivas diferentes sobre o mesmo fenômeno"
    grupo: temas_analiticos
END ONTOLOGY

1.8.2 Análise de Políticas Públicas

ONTOLOGY formulador
    descricao: "Agente que propõe ou desenha a política"
    grupo: atores
END ONTOLOGY

ONTOLOGY implementador
    descricao: "Agente responsável por executar a política"
    grupo: atores
END ONTOLOGY

ONTOLOGY beneficiario
    descricao: "População-alvo da política"
    grupo: atores
END ONTOLOGY

ONTOLOGY eficacia
    descricao: "Grau de alcance dos objetivos declarados"
    grupo: dimensoes_de_avaliacao
END ONTOLOGY

ONTOLOGY eficiencia
    descricao: "Relação entre recursos empregados e resultados obtidos"
    grupo: dimensoes_de_avaliacao
END ONTOLOGY

ONTOLOGY equidade
    descricao: "Distribuição justa dos benefícios entre grupos"
    grupo: dimensoes_de_avaliacao
END ONTOLOGY

1.8.3 Análise de Requisitos (Engenharia de Software)

ONTOLOGY funcionalidade_core
    descricao: "Capacidade essencial do sistema"
    grupo: requisitos_funcionais
END ONTOLOGY

ONTOLOGY integracao
    descricao: "Comunicação com sistemas externos"
    grupo: requisitos_funcionais
END ONTOLOGY

ONTOLOGY performance
    descricao: "Tempo de resposta e throughput"
    grupo: requisitos_nao_funcionais
END ONTOLOGY

ONTOLOGY seguranca
    descricao: "Proteção de dados e autenticação"
    grupo: requisitos_nao_funcionais
END ONTOLOGY

Relações de dependência entre requisitos

Relações como REQUER e CONFLITA_COM são declaradas no template, não na ontologia. Veja Como Criar Chains.

1.9 Como Documentar Decisões Ontológicas

Use comentários (#) diretamente nos arquivos .syno:

# DECISÃO 2026-02-04: Separamos "custo" em dois conceitos após
# identificar ambiguidade nas anotações das entrevistas 15-20

ONTOLOGY custo_de_aquisicao
    descricao: "Investimento inicial para implementar"
    grupo: fatores_economicos
END ONTOLOGY

ONTOLOGY custo_operacional
    # NOTA: Inclui treinamento, suporte técnico e licenças recorrentes
    descricao: "Despesas recorrentes de manutenção e operação"
    grupo: fatores_economicos
END ONTOLOGY

1.10 Quando Criar Múltiplas Ontologias

Para projetos grandes, divida por domínio em arquivos separados:

ontology/
├── codes_actors.syno          # Atores sociais
├── codes_processes.syno       # Processos organizacionais
└── codes_outcomes.syno        # Resultados e impactos

No arquivo .synp:

PROJECT my_analysis

TEMPLATE "template.synt"
INCLUDE BIBLIOGRAPHY "references.bib"
INCLUDE ANNOTATIONS "annotations/"
INCLUDE ONTOLOGY "ontology/codes_actors.syno"
INCLUDE ONTOLOGY "ontology/codes_processes.syno"
INCLUDE ONTOLOGY "ontology/codes_outcomes.syno"

END PROJECT

Quando usar: Quando há mais de 50 conceitos ou equipes trabalhando em domínios diferentes.

1.11 Referências

Para sintaxe completa de ontologias, consulte:

Referência da Linguagem — Especificação formal de .syno
Tutorial Getting Started — Criar primeira ontologia
Como criar chains — Declarar relações no template

Ficou com dúvidas? Consulte GitHub Discussions ou abra uma issue específica.