Skip to content

Criar validações para o elemento <sec> #1109

Open
#1137
Open
Criar validações para o elemento <sec>#1109
#1137
Assignees
robertatakenakaRossi-Lucianocopilot-swe-agent
@Rossi-Luciano

Description

@Rossi-Luciano
Rossi-Luciano
opened on Feb 14, 2026

Objetivo

Implementar validações para o elemento <sec> conforme a especificação SPS 1.10, aumentando a conformidade de X% para 70% (7 de 10 regras).

Nota: Algumas validações para <sec> podem já estar parcialmente implementadas no repositório. Este Issue visa reavaliar, complementar e garantir cobertura completa das regras SPS 1.10.

Contexto

O elemento <sec> representa seções de texto do documento. Para acessibilidade, cada seção deve obrigatoriamente conter <title>. Seções de primeiro nível que correspondem a tipos específicos (métodos, resultados, etc.) devem ter o atributo @sec-type. Alguns tipos de documentos requerem obrigatoriamente seção de disponibilidade de dados (@sec-type="data-availability"). Validações corretas garantem acessibilidade, presença de elementos obrigatórios, e conformidade com requisitos de tipos de documentos.

Conformidade atual: X de 10 regras implementadas (X%)
Meta após implementação: 7 de 10 regras (70%)

Documentação SPS

Referência oficial: https://docs.google.com/document/d/1GTv4Inc2LS_AXY-ToHT3HmO66UT0VAHWJNOIqzBNSgA/edit?tab=t.0#heading=h.sec

Regras principais conforme SPS 1.10:

  1. Ocorrência:

    • <sec> pode aparecer zero ou mais vezes em: <abstract>, <app>, <back>, <bio>, <body>, <boxed-text>, <sec>, <trans-abstract>

  2. Elemento obrigatório (Acessibilidade):

    • <title> é mandatório em <sec> para criar títulos acessíveis

  3. Atributo @sec-type:

    • Obrigatório apenas para seções de primeiro nível que correspondem aos valores da lista
    • Caso haja seção de primeiro nível diferente, o atributo não deve ser inserido

  4. Valores permitidos para @sec-type:

    • cases - Relatos/casos/estudos de caso
    • conclusions - Conclusões/considerações finais/comentários
    • data-availability - Declaração de Disponibilidade de Dados
    • discussion - Discussões/interpretações
    • intro - Introdução/sinopse
    • materials - Materiais
    • methods - Metodologias/métodos/procedimentos
    • results - Resultados/descobertas
    • subjects - Participantes/Pacientes
    • supplementary-material - Material suplementar/material adicional
    • transcript - Transcrição de vídeo ou áudio

  5. Seções combinadas:

    • Quando título é composto por mais de um item, usar pipe | como separador
    • Exemplo: materials|methods
    • Exceção: supplementary-material, transcript e data-availability não podem ser combinados

  6. @sec-type="data-availability" obrigatório:

    • Mandatório para tipos de documentos: data-article, brief-report, case-report, rapid-communication, research-article, review-article
    • Deve também ter @specific-use

  7. @sec-type="transcript" exige @id:

    • Seções de transcrição devem ter atributo @id obrigatório

  8. Estrutura:

    • Título (<title>) seguido de um ou mais parágrafos (<p>)

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

# Regra Nível Descrição
1 Validar presença de <title> CRITICAL O elemento <title> é mandatório em <sec> (requisito de acessibilidade)
2 Validar valores permitidos de @sec-type ERROR Quando presente, @sec-type deve ter valor da lista permitida
3 Validar presença de @id em transcript ERROR Seção com @sec-type="transcript" deve ter atributo @id
4 Validar presença de data-availability em documentos indexáveis ERROR Documentos indexáveis (research-article, case-report, etc.) devem ter seção @sec-type="data-availability"

P1 – Importantes (implementar se possível)

# Regra Nível Descrição
5 Validar formato de seções combinadas WARNING Seções combinadas devem usar pipe `
6 Validar que transcript, supplementary-material e data-availability não são combinados WARNING Tipos especiais não devem aparecer em seções combinadas (sem pipe)
7 Validar presença de conteúdo WARNING Seção deve conter pelo menos um parágrafo <p> após <title>

P2 – Futuras (fora do escopo deste Issue)

# Regra Motivo de exclusão
8 Validar que @sec-type só é usado em seções de primeiro nível Média complexidade - requer análise de hierarquia de elementos
9 Validar presença de @specific-use quando @sec-type="data-availability" Baixa prioridade - validação específica de data-availability
10 Validar ordem lógica de seções (intro, methods, results, discussion, conclusions) Baixa prioridade - ordem é recomendação, não regra rígida

Arquivos a Criar/Modificar

Avaliar existentes (podem ter validações parciais):

  • packtools/sps/models/sec.py ou similar – Verificar se modelo existe
  • packtools/sps/validation/sec.py – Verificar validações existentes
  • packtools/sps/validation/rules/sec_rules.json ou similar – Verificar configuração

Criar (se não existirem):

  • packtools/sps/models/sec.py – Modelo de extração de dados
  • packtools/sps/validation/sec.py – Validações
  • packtools/sps/validation/rules/sec_rules.json – Configuração de níveis de erro
  • tests/sps/validation/test_sec.py – Testes unitários

Referenciar (implementações similares):

  • packtools/sps/validation/article_and_subarticles.py – Validação condicional por article-type
  • packtools/sps/validation/utils.py – Funções auxiliares (build_response)

Exemplos de XML

XML Válido (deve passar sem erros):

<!-- Exemplo 1: Seção simples de métodos -->
<body>
    <sec sec-type="methods">
        <title>Métodos de Pesquisa</title>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent ornare magna a enim dapibus.</p>
    </sec>
</body>

<!-- Exemplo 2: Seção combinada (materiais e métodos) -->
<body>
    <sec sec-type="materials|methods">
        <title>Materials and Methods</title>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
    </sec>
</body>

<!-- Exemplo 3: Seção de material suplementar -->
<body>
    <sec sec-type="supplementary-material" id="sec1">
        <title>Supplementary Materials</title>
        <supplementary-material id="suppl1">
            <label>Supplementary material 1</label>
            <caption>
                <title>Video 1</title>
            </caption>
            <media mimetype="video" mime-subtype="mp4" xlink:href="video.mp4"/>
        </supplementary-material>
    </sec>
</body>

<!-- Exemplo 4: Seção de transcrição com @id -->
<body>
    <sec sec-type="transcript" id="TR1">
        <title>Interview with Gabriel and Denise</title>
        <p>Nam convallis dolor sed ligula mollis vulputate.</p>
        <speech>
            <speaker>Gabriel</speaker>
            <p>Etiam ac arcu at nunc lacinia fermentum.</p>
        </speech>
        <speech>
            <speaker>Denise</speaker>
            <p>Pellentesque at bibendum nibh.</p>
        </speech>
    </sec>
</body>

<!-- Exemplo 5: Seção de disponibilidade de dados -->
<body>
    <sec sec-type="data-availability" id="sec-data" specific-use="data-available-on-request">
        <title>Data Availability Statement</title>
        <p>The data that support the findings of this study are available on request from the corresponding author.</p>
    </sec>
</body>

<!-- Exemplo 6: Seção com subseção -->
<body>
    <sec sec-type="methods">
        <title>Methodology</title>
        <sec>
            <title>Methodology in Science</title>
            <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
        </sec>
    </sec>
</body>

<!-- Exemplo 7: Seção sem @sec-type (título livre) -->
<body>
    <sec>
        <title>Biologia Marinha</title>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
    </sec>
</body>

<!-- Exemplo 8: Todas as seções principais de um artigo -->
<article article-type="research-article">
    <front>
        <!-- metadados -->
    </front>
    <body>
        <sec sec-type="intro">
            <title>Introduction</title>
            <p>Introduction content.</p>
        </sec>
        <sec sec-type="materials|methods">
            <title>Materials and Methods</title>
            <p>Methods content.</p>
        </sec>
        <sec sec-type="results">
            <title>Results</title>
            <p>Results content.</p>
        </sec>
        <sec sec-type="discussion">
            <title>Discussion</title>
            <p>Discussion content.</p>
        </sec>
        <sec sec-type="conclusions">
            <title>Conclusions</title>
            <p>Conclusions content.</p>
        </sec>
        <sec sec-type="data-availability" specific-use="data-available-on-request">
            <title>Data Availability</title>
            <p>Data available on request.</p>
        </sec>
    </body>
</article>

<!-- Exemplo 9: Seção de casos -->
<body>
    <sec sec-type="cases">
        <title>Case Studies</title>
        <p>Case description.</p>
    </sec>
</body>

<!-- Exemplo 10: Seção de participantes -->
<body>
    <sec sec-type="subjects">
        <title>Participants</title>
        <p>Participant information.</p>
    </sec>
</body>

XML Inválido – Caso 1: Sem <title> (CRITICAL)

<body>
    <sec sec-type="methods">
        <p>Lorem ipsum dolor sit amet.</p>
    </sec>
</body>

Erro esperado: Elemento <title> é mandatório em <sec> (requisito de acessibilidade)

XML Inválido – Caso 2: <title> vazio (CRITICAL)

<body>
    <sec sec-type="methods">
        <title></title>
        <p>Lorem ipsum dolor sit amet.</p>
    </sec>
</body>

Erro esperado: Elemento <title> não pode estar vazio

XML Inválido – Caso 3: <title> apenas espaços (CRITICAL)

<body>
    <sec sec-type="methods">
        <title>   </title>
        <p>Lorem ipsum dolor sit amet.</p>
    </sec>
</body>

Erro esperado: Elemento <title> não pode conter apenas espaços

XML Inválido – Caso 4: @sec-type com valor inválido (ERROR)

<body>
    <sec sec-type="methodology">
        <title>Methodology</title>
        <p>Lorem ipsum dolor sit amet.</p>
    </sec>
</body>

Erro esperado: Valor "methodology" não está na lista de valores permitidos para @sec-type. Use methods para metodologias.

XML Inválido – Caso 5: @sec-type="transcript" sem @id (ERROR)

<body>
    <sec sec-type="transcript">
        <title>Interview</title>
        <p>Interview content.</p>
    </sec>
</body>

Erro esperado: Seção com @sec-type="transcript" deve ter atributo @id

XML Inválido – Caso 6: research-article sem data-availability (ERROR)

<article article-type="research-article">
    <front>
        <!-- metadados -->
    </front>
    <body>
        <sec sec-type="intro">
            <title>Introduction</title>
            <p>Content.</p>
        </sec>
        <sec sec-type="methods">
            <title>Methods</title>
            <p>Content.</p>
        </sec>
        <!-- falta sec sec-type="data-availability" -->
    </body>
</article>

Erro esperado: Artigo com @article-type="research-article" deve conter seção @sec-type="data-availability" (Critério SciELO Brasil)

XML Inválido – Caso 7: Seção combinada com formato incorreto (WARNING)

<body>
    <sec sec-type="materials methods">
        <title>Materials and Methods</title>
        <p>Content.</p>
    </sec>
</body>

Erro esperado: (WARNING) Seções combinadas devem usar pipe | como separador. Use materials|methods ao invés de materials methods

XML Inválido – Caso 8: transcript combinado (WARNING)

<body>
    <sec sec-type="transcript|discussion" id="TR1">
        <title>Interview Discussion</title>
        <p>Content.</p>
    </sec>
</body>

Erro esperado: (WARNING) @sec-type="transcript" não deve ser combinado com outros tipos (sem pipe)

XML Inválido – Caso 9: data-availability combinado (WARNING)

<body>
    <sec sec-type="data-availability|supplementary-material">
        <title>Data and Materials</title>
        <p>Content.</p>
    </sec>
</body>

Erro esperado: (WARNING) @sec-type="data-availability" não deve ser combinado com outros tipos (sem pipe)

XML Inválido – Caso 10: Seção vazia (sem conteúdo) (WARNING)

<body>
    <sec sec-type="methods">
        <title>Methods</title>
    </sec>
</body>

Erro esperado: (WARNING) Seção deve conter pelo menos um parágrafo <p> ou outro conteúdo após <title>

XML Inválido – Caso 11: @sec-type vazio (ERROR)

<body>
    <sec sec-type="">
        <title>Title</title>
        <p>Content.</p>
    </sec>
</body>

Erro esperado: Atributo @sec-type não pode estar vazio

XML Inválido – Caso 12: @sec-type com uppercase (ERROR)

<body>
    <sec sec-type="Methods">
        <title>Methods</title>
        <p>Content.</p>
    </sec>
</body>

Erro esperado: Valor de @sec-type deve estar em minúsculas. Use methods ao invés de Methods

XML Inválido – Caso 13: case-report sem data-availability (ERROR)

<article article-type="case-report">
    <front>
        <!-- metadados -->
    </front>
    <body>
        <sec sec-type="intro">
            <title>Introduction</title>
            <p>Content.</p>
        </sec>
        <!-- falta data-availability -->
    </body>
</article>

Erro esperado: Artigo com @article-type="case-report" deve conter seção @sec-type="data-availability"

XML Inválido – Caso 14: Combinação com três tipos (WARNING)

<body>
    <sec sec-type="materials|methods|results">
        <title>Materials, Methods and Results</title>
        <p>Content.</p>
    </sec>
</body>

Erro esperado: (WARNING) Seções combinadas normalmente usam apenas dois tipos. Verifique se materials|methods|results é apropriado.

XML Inválido – Caso 15: @id vazio em transcript (ERROR)

<body>
    <sec sec-type="transcript" id="">
        <title>Interview</title>
        <p>Content.</p>
    </sec>
</body>

Erro esperado: Atributo @id não pode estar vazio em seção @sec-type="transcript"

Padrão de Implementação

Diretrizes Gerais:

  1. Seguir padrões existentes no repositório:

    • Consultar implementações similares como article_and_subarticles.py (validação condicional)
    • Usar estrutura de classes já estabelecida no packtools
    • IMPORTANTE: Verificar se já existem validações parciais para <sec> e integrá-las ou complementá-las

  2. Internacionalização (i18n):

    • OBRIGATÓRIO: Todas as mensagens devem suportar internacionalização
    • Usar advice_text e advice_params em build_response()
    • Consultar conversas anteriores sobre implementação de i18n no packtools
    • Referência: validações em article_contribs.py que já implementam i18n completo

  3. Validações condicionais:

    • Validações que dependem de contexto devem retornar None quando não aplicável
    • Exemplo: validação de data-availability só se aplica para tipos específicos de artigos
    • Exemplo: validação de @id só se aplica quando @sec-type="transcript"
    • Usar filter_results() nos testes para remover None

  4. Uso de build_response():

    • Sempre usar parent=self.data (dict completo, nunca string)
    • Campo response deve conter: "OK", "WARNING", "ERROR", "CRITICAL"
    • Sempre fornecer advice_text e advice_params para i18n

  5. Modelo de dados:

    • Criar propriedade que retorna lista de dicionários (um para cada <sec>)
    • Cada dict deve conter: sec_type, has_title, title_text, id, has_content, level, parent, parent_id, parent_lang

  6. Lista de valores permitidos:

    • Criar constante: SEC_TYPES = ["cases", "conclusions", "data-availability", "discussion", "intro", "materials", "methods", "results", "subjects", "supplementary-material", "transcript"]
    • Tipos que não podem ser combinados: ["transcript", "supplementary-material", "data-availability"]

  7. Detecção de article-type:

    • Tipos que requerem data-availability: ["data-article", "brief-report", "case-report", "rapid-communication", "research-article", "review-article"]
    • Usar XPath ou navegação DOM para acessar elemento raiz <article>

  8. Validação de seções combinadas:

    • Detectar presença de pipe | no valor de @sec-type
    • Validar que cada parte da combinação é um valor válido
    • Alertar se tipos especiais aparecem combinados

  9. Detecção de nível de seção:

    • Seção de primeiro nível: <body>/<sec>, <back>/<sec>, etc.
    • Subseção: <sec>/<sec>
    • Validação de @sec-type normalmente só se aplica a primeiro nível

  10. Validação de conteúdo:

    • Verificar presença de pelo menos um elemento após <title>
    • Elementos aceitos: <p>, <sec>, <supplementary-material>, etc.

Testes Esperados

Casos de teste obrigatórios:

Presença de <title>:

  • <sec> com <title> (OK)
  • <sec> sem <title> (CRITICAL)
  • <title> vazio (CRITICAL)
  • <title> apenas espaços (CRITICAL)
  • <title> com conteúdo válido (OK)

Valores de @sec-type:

  • Sem @sec-type (OK - opcional)
  • Todos os valores permitidos (OK para cada um)
  • cases (OK)
  • conclusions (OK)
  • data-availability (OK)
  • discussion (OK)
  • intro (OK)
  • materials (OK)
  • methods (OK)
  • results (OK)
  • subjects (OK)
  • supplementary-material (OK)
  • transcript (OK)
  • Valor inválido "methodology" (ERROR)
  • Valor inválido "introduction" (ERROR - use intro)
  • Valor inválido "conclusion" (ERROR - use conclusions)
  • Uppercase "Methods" (ERROR)

Seções combinadas:

  • materials|methods (OK)
  • results|discussion (OK)
  • materials|methods|results (WARNING - três tipos)
  • materials methods (WARNING - falta pipe)
  • materials-methods (ERROR - usar pipe não hífen)

Tipos não combináveis:

  • transcript sozinho (OK)
  • transcript|discussion (WARNING - não combinar)
  • data-availability sozinho (OK)
  • data-availability|methods (WARNING - não combinar)
  • supplementary-material sozinho (OK)
  • supplementary-material|results (WARNING - não combinar)

Atributo @id em transcript:

  • transcript com @id (OK)
  • transcript sem @id (ERROR)
  • transcript com @id vazio (ERROR)
  • Outros tipos sem @id (OK - opcional)

data-availability obrigatório:

  • research-article com data-availability (OK)
  • research-article sem data-availability (ERROR)
  • case-report com data-availability (OK)
  • case-report sem data-availability (ERROR)
  • brief-report sem data-availability (ERROR)
  • rapid-communication sem data-availability (ERROR)
  • data-article sem data-availability (ERROR)
  • review-article sem data-availability (ERROR)
  • editorial sem data-availability (OK - não requerido)
  • letter sem data-availability (OK - não requerido)

Presença de conteúdo:

  • <sec> com <title> e <p> (OK)
  • <sec> com <title> e subseção (OK)
  • <sec> com <title> e <supplementary-material> (OK)
  • <sec> apenas com <title> (WARNING - sem conteúdo)

Hierarquia:

  • Seção de primeiro nível (OK)
  • Subseção (OK)
  • Seção aninhada em três níveis (OK)

Casos de borda:

  • <sec> vazio completo (CRITICAL - falta title)
  • Múltiplas seções (OK)
  • @sec-type vazio (ERROR)
  • @sec-type apenas espaços (ERROR)
  • Seção em diferentes contextos (body, back, abstract) (OK)

Total esperado: ~60 testes unitários

Estrutura de testes:

  • Usar filter_results() para remover None dos resultados
  • Asserções devem usar campo response (não is_valid)
  • Testes devem ser autocontidos e descritivos
  • Agrupar testes por categoria (title, sec-type, combinadas, data-availability, conteúdo)

Critérios de Aceite

O PR será aceito quando:

  • Verificação de validações existentes: Código existente para <sec> foi analisado e integrado ou substituído adequadamente
  • Todas as regras P0 implementadas (4 validações CRITICAL/ERROR)
  • Todas as regras P1 implementadas (3 validações WARNING)
  • Testes unitários passando com cobertura mínima de ~60 casos
  • Nenhum teste existente quebrado
  • Arquivo sec_rules.json criado com todos os níveis de erro
  • Internacionalização completa em todas as mensagens (i18n obrigatório)
  • Código seguindo padrões do packtools (build_response, filter_results, validações condicionais)
  • Modelo de dados criado com extração adequada de todas as seções
  • Validação condicional de data-availability por article-type funcionando
  • Validação de valores permitidos de @sec-type funcionando
  • Validação de @id obrigatório em transcript funcionando
  • Validação de seções combinadas funcionando
  • Validação de tipos não combináveis funcionando
  • Documentação inline clara (docstrings)

Referências

Documentação SPS:

Padrões JATS:

Acessibilidade:

Referências internas packtools:

  • Internacionalização: Consultar conversas anteriores sobre implementação de i18n
  • Implementações similares: article_and_subarticles.py (validação condicional por article-type)
  • Funções auxiliares: utils.py (build_response)

Labels Sugeridas

enhancement validation SPS-1.10 accessibility scielo-brasil

Impacto Esperado

Antes:

  • Conformidade SPS 1.10 para <sec>: X% (verificar validações existentes)
  • <title> pode estar ausente (problema de acessibilidade)
  • Valores incorretos de @sec-type podem passar
  • Seção data-availability pode estar ausente em documentos que a requerem
  • @id pode estar ausente em transcrições
  • Seções combinadas podem ter formato incorreto
  • Tipos especiais podem ser combinados inadequadamente

Depois:

  • Conformidade SPS 1.10 para <sec>: 70% (7 de 10 regras)
  • Validação CRITICAL de <title> obrigatório (acessibilidade)
  • Validação ERROR de valores permitidos de @sec-type
  • Validação ERROR de presença de data-availability em documentos indexáveis
  • Validação ERROR de @id obrigatório em transcrições
  • Validação WARNING de formato de seções combinadas
  • Validação WARNING de tipos não combináveis
  • ~60 testes unitários garantindo qualidade
  • Internacionalização completa (PT/EN/ES)

Benefícios:

  • Garante acessibilidade com títulos obrigatórios em seções
  • Melhora conformidade com Critérios SciELO Brasil (data-availability)
  • Detecta valores incorretos de @sec-type antes da publicação
  • Assegura identificação adequada de transcrições (com @id)
  • Promove estruturação correta de seções combinadas
  • Facilita navegação e compreensão do documento
  • Melhora experiência para usuários com tecnologias assistivas
  • Garante presença de declaração de disponibilidade de dados
  • Facilita processamento automatizado de seções
  • Facilita manutenção e depuração de XMLs

Observações importantes:

  • Implementar internacionalização ajustando as respostas das validações ao formato da função build_response em packtools/sps/validation/utils.py;
  • Verificar e adicionar as validações no orquestrador: packtools/sps/validation/xml_validations.py e packtools/sps/validation/xml_validator.py
  • Verificar a corretude dos testes exsitentes para a validação e complementar caso necessário;
  • Realizar ajustes, caso necessário, nos modelos que são utilizados pelas validações, garantindo que o ajuste não interfira em possíveis usos atuais desses modelos.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions