Skip to content

Criar validações para o elemento <ref-list> #1104

New issue
New issue
Open
Open
Criar validações para o elemento <ref-list>#1104
Assignees
robertatakenakaRossi-Luciano
@Rossi-Luciano

Description

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

Objetivo

Implementar validações para o elemento <ref-list> conforme a especificação SPS 1.10 e Critérios SciELO Brasil, aumentando a conformidade de X% para 70% (14 de 20 regras).

Nota: Algumas validações para <ref-list> podem já estar parcialmente implementadas no repositório. Este Issue visa reavaliar, complementar e garantir cobertura completa das regras SPS 1.10 e Critérios SciELO Brasil.

Contexto

O elemento <ref-list> representa o conjunto de referências bibliográficas de um documento. Para SciELO Brasil, é obrigatório em todos os documentos indexáveis (exceto errata, retratação, adendo, manifestação de preocupação e parecer). Cada referência deve conter <mixed-citation> (apresentação) e <element-citation> (dados estruturados para métricas). Validações corretas garantem conformidade com critérios SciELO Brasil, presença de elementos obrigatórios, e qualidade dos metadados bibliográficos.

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

Documentação SPS

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

Regras principais conforme SPS 1.10 e Critérios SciELO Brasil:

  1. Ocorrência:

    • <ref-list> aparece em <back> uma ou mais vezes
    • Pode aparecer aninhado dentro de <ref-list>

  2. Obrigatoriedade (Critério SciELO Brasil):

    • <ref-list> é obrigatório em documentos indexáveis
    • Exceções: errata, retratação, adendo, manifestação de preocupação, parecer

  3. Estrutura obrigatória:

    • <ref-list> deve conter pelo menos um <ref>
    • <ref> deve conter <mixed-citation> E <element-citation>

  4. Atributo obrigatório em <element-citation>:

    • @publication-type (obrigatório)

  5. Valores permitidos para @publication-type:

    • book - Livros, capítulos de livros
    • confproc - Atas, anais, proceedings de eventos
    • data - Dados de pesquisa (datasets)
    • database - Bases de dados
    • journal - Artigos de periódicos científicos
    • legal-doc - Normas jurídicas
    • letter - Cartas e comunicações pessoais
    • newspaper - Artigos de jornal
    • patent - Patentes
    • preprint - Preprints
    • report - Relatórios técnicos
    • software - Software
    • thesis - Monografias, dissertações, teses
    • webpage - Sites, blogs
    • other - Tipos não previstos

  6. Restrições em <element-citation>:

    • Proibido: dois ou mais <ext-link>
    • Proibido: pontuação entre elementos (ponto, vírgula, etc.)
    • Proibido: <comment> abarcando apenas <ext-link>
    • Proibido: formatação completa em <italic> ou <bold>

  7. Restrições em <mixed-citation>:

    • Proibido: dois ou mais <ext-link>
    • Permitido apenas tags de formatação: <bold>, <italic>, <sup>, <sub>

  8. Elementos esperados em <element-citation>:

    • <source> - Título da fonte (esperado em todas as referências)
    • <year> - Ano (esperado em todas as referências)

  9. Regras de elementos específicos:

    • Quando há <fpage>, <lpage> é obrigatório
    • <size> deve ter @units="pages"
    • <date-in-citation> deve ter @content-type="access-date"
    • <person-group> deve ter @person-group-type quando presente
    • <name> dentro de <person-group> deve ter <surname>

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

# Regra Nível Descrição
1 Validar presença de <ref-list> em documentos indexáveis CRITICAL <ref-list> é obrigatório em <back> para documentos indexáveis (exceto errata, retratação, adendo, manifestação de preocupação, parecer)
2 Validar presença de <ref> CRITICAL <ref-list> deve conter pelo menos um elemento <ref>
3 Validar presença de <mixed-citation> CRITICAL Cada <ref> deve conter <mixed-citation>
4 Validar presença de <element-citation> CRITICAL Cada <ref> deve conter <element-citation>
5 Validar presença de @publication-type CRITICAL O atributo @publication-type é obrigatório em <element-citation>
6 Validar valores permitidos de @publication-type ERROR O valor de @publication-type deve estar na lista de valores permitidos
7 Validar ausência de múltiplos <ext-link> em <element-citation> ERROR É proibida a ocorrência de dois ou mais <ext-link> em <element-citation>
8 Validar ausência de múltiplos <ext-link> em <mixed-citation> ERROR É proibida a ocorrência de dois ou mais <ext-link> em <mixed-citation>

P1 – Importantes (implementar se possível)

# Regra Nível Descrição
9 Validar presença de <source> em <element-citation> WARNING Espera-se que todas as referências tenham <source> (título da fonte)
10 Validar presença de <year> em <element-citation> WARNING Espera-se que todas as referências tenham pelo menos <year>
11 Validar <lpage> quando há <fpage> ERROR Quando houver <fpage>, o elemento <lpage> é obrigatório
12 Validar @units="pages" em <size> ERROR O elemento <size> deve ter obrigatoriamente @units="pages"
13 Validar @content-type="access-date" em <date-in-citation> ERROR O elemento <date-in-citation> deve ter obrigatoriamente @content-type="access-date"
14 Validar <surname> em <name> ERROR Quando <person-group> contém <name>, o elemento <surname> é obrigatório

P2 – Futuras (fora do escopo deste Issue)

# Regra Motivo de exclusão
15 Validar ausência de pontuação entre elementos em <element-citation> Alta complexidade - requer análise de texto entre tags XML
16 Validar que <comment> não abarca apenas <ext-link> Média complexidade - requer análise de estrutura de <comment>
17 Validar ausência de formatação completa em italic/bold Média complexidade - requer análise de conteúdo completo
18 Validar elementos apropriados por tipo de publicação Alta complexidade - regras específicas por tipo
19 Validar presença de @person-group-type em <person-group> Baixa prioridade - parte de validação de person-group
20 Validar tags permitidas em <mixed-citation> Baixa prioridade - schema JATS já restringe parcialmente

Arquivos a Criar/Modificar

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

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

Criar (se não existirem):

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

Referenciar (implementações similares):

  • packtools/sps/validation/article_contribs.py – Validação de person-group
  • packtools/sps/validation/utils.py – Funções auxiliares (build_response)

Exemplos de XML

XML Válido (deve passar sem erros):

<!-- Exemplo 1: Artigo de periódico -->
<back>
    <ref-list>
        <title>Referências</title>
        <ref id="B1">
            <mixed-citation>Benchimol M, Souza W de. Endocytosis in anaerobic parasitic protists. Mem Inst Oswaldo Cruz. 2024;119:e240058.</mixed-citation>
            <element-citation publication-type="journal">
                <person-group person-group-type="author">
                    <name>
                        <surname>Benchimol</surname>
                        <given-names>M</given-names>
                    </name>
                    <name>
                        <surname>Souza</surname>
                        <given-names>W de</given-names>
                    </name>
                </person-group>
                <article-title>Endocytosis in anaerobic parasitic protists</article-title>
                <source>Mem Inst Oswaldo Cruz</source>
                <year>2024</year>
                <volume>119</volume>
                <elocation-id>e240058</elocation-id>
                <pub-id pub-id-type="doi">10.1590/0074-02760240058</pub-id>
            </element-citation>
        </ref>
    </ref-list>
</back>

<!-- Exemplo 2: Livro completo -->
<back>
    <ref-list>
        <ref id="B2">
            <label>2</label>
            <mixed-citation>Hamric, Ann B.; Spross, Judith A.; Hanson, Charlene M. Advanced practice nursing: an integrative approach. 3rd ed. St. Louis (MO): Elsevier Saunders; c2005. 979 p.</mixed-citation>
            <element-citation publication-type="book">
                <person-group person-group-type="author">
                    <name>
                        <surname>Hamric</surname>
                        <given-names>Ann B.</given-names>
                    </name>
                    <name>
                        <surname>Spross</surname>
                        <given-names>Judith A.</given-names>
                    </name>
                    <name>
                        <surname>Hanson</surname>
                        <given-names>Charlene M.</given-names>
                    </name>
                </person-group>
                <source>Advanced practice nursing: an integrative approach</source>
                <edition>3rd ed</edition>
                <publisher-loc>St. Louis (MO)</publisher-loc>
                <publisher-name>Elsevier Saunders</publisher-name>
                <year>c2005</year>
                <size units="pages">979 p</size>
            </element-citation>
        </ref>
    </ref-list>
</back>

<!-- Exemplo 3: Capítulo de livro com fpage e lpage -->
<back>
    <ref-list>
        <ref id="B3">
            <mixed-citation>Calkins BM, Mendeloff AI. The epidemiology of idiopathic inflammatory bowel disease. In: Kirsner JB, Shorter RG, eds. Inflammatory bowel disease, 4th ed. Baltimore: Williams &amp; Wilkins. 1995:31-68.</mixed-citation>
            <element-citation publication-type="book">
                <person-group person-group-type="author">
                    <name>
                        <surname>Calkins</surname>
                        <given-names>BM</given-names>
                    </name>
                    <name>
                        <surname>Mendeloff</surname>
                        <given-names>AI</given-names>
                    </name>
                </person-group>
                <part-title>The epidemiology of idiopathic inflammatory bowel disease</part-title>
                <person-group person-group-type="editor">
                    <name>
                        <surname>Kirsner</surname>
                        <given-names>JB</given-names>
                    </name>
                    <name>
                        <surname>Shorter</surname>
                        <given-names>RG</given-names>
                    </name>
                </person-group>
                <source>Inflammatory bowel disease</source>
                <edition>4th</edition>
                <publisher-loc>Baltimore</publisher-loc>
                <publisher-name>Williams &amp; Wilkins</publisher-name>
                <year>1995</year>
                <fpage>31</fpage>
                <lpage>68</lpage>
            </element-citation>
        </ref>
    </ref-list>
</back>

<!-- Exemplo 4: Dataset (dados de pesquisa) -->
<back>
    <ref-list>
        <ref id="B4">
            <mixed-citation>Lucas Leão; Perobelli, Fernando Salgueiro; Ribeiro, Hilton Manoel Dias, 2024, Data for: Ação Coletiva Institucional, DOI: 10.48331/scielodata.5Z4TMP, SciELO Data, V1.</mixed-citation>
            <element-citation publication-type="data">
                <person-group person-group-type="author">
                    <name>
                        <surname>Leão</surname>
                        <given-names>Lucas</given-names>
                    </name>
                    <name>
                        <surname>Perobelli</surname>
                        <given-names>Fernando Salgueiro</given-names>
                    </name>
                    <name>
                        <surname>Ribeiro</surname>
                        <given-names>Hilton Manoel Dias</given-names>
                    </name>
                </person-group>
                <data-title>Data for: Ação Coletiva Institucional e Consórcio Públicos Intermunicipais no Brasil</data-title>
                <version>V1</version>
                <year>2024</year>
                <source>SciELO Data</source>
                <pub-id pub-id-type="doi">10.48331/scielodata.5Z4TMP</pub-id>
            </element-citation>
        </ref>
    </ref-list>
</back>

<!-- Exemplo 5: Website com data de acesso -->
<back>
    <ref-list>
        <ref id="B5">
            <mixed-citation>COB - Comitê Olímpico Brasileiro. Desafio para o corpo. Disponível em: http://www.cob.org.br/esportes/esporte.asp?id=39. (Acesso em 10 abr 2010)</mixed-citation>
            <element-citation publication-type="webpage">
                <person-group person-group-type="author">
                    <collab>COB - Comitê Olímpico Brasileiro</collab>
                </person-group>
                <source>Desafio para o corpo</source>
                <ext-link ext-link-type="uri" xlink:href="http://www.cob.org.br/esportes/esporte.asp?id=39">http://www.cob.org.br/esportes/esporte.asp?id=39</ext-link>
                <date-in-citation content-type="access-date">10 abr 2010</date-in-citation>
            </element-citation>
        </ref>
    </ref-list>
</back>

<!-- Exemplo 6: Proceedings de conferência -->
<back>
    <ref-list>
        <ref id="B6">
            <mixed-citation>Furton EJ, Dort V, editors. Addiction and compulsive behaviors. Proceedings of the 17th Workshop for Bishops; 1999; Dallas, TX. Boston: National Catholic Bioethics Center (US); 2000. 258 p.</mixed-citation>
            <element-citation publication-type="confproc">
                <person-group person-group-type="editor">
                    <name>
                        <surname>Furton</surname>
                        <given-names>EJ</given-names>
                    </name>
                    <name>
                        <surname>Dort</surname>
                        <given-names>V</given-names>
                    </name>
                </person-group>
                <source>Addiction and compulsive behaviors</source>
                <conf-name>Proceedings of the 17th Workshop for Bishops</conf-name>
                <conf-num>17</conf-num>
                <conf-date>1999</conf-date>
                <conf-loc>Dallas, TX</conf-loc>
                <publisher-loc>Boston</publisher-loc>
                <publisher-name>National Catholic Bioethics Center (US)</publisher-name>
                <year>2000</year>
                <size units="pages">258 p</size>
            </element-citation>
        </ref>
    </ref-list>
</back>

<!-- Exemplo 7: Tese -->
<back>
    <ref-list>
        <ref id="B7">
            <mixed-citation>Jones DL. The role of physical activity on the need for revision total knee arthroplasty [dissertation]. [Pittsburgh (PA)]: University of Pittsburgh; 2001. 436 p.</mixed-citation>
            <element-citation publication-type="thesis">
                <person-group person-group-type="author">
                    <name>
                        <surname>Jones</surname>
                        <given-names>DL</given-names>
                    </name>
                </person-group>
                <source>The role of physical activity on the need for revision total knee arthroplasty</source>
                <publisher-loc>Pittsburgh (PA)</publisher-loc>
                <publisher-name>University of Pittsburgh</publisher-name>
                <year>2001</year>
                <size units="pages">436 p</size>
            </element-citation>
        </ref>
    </ref-list>
</back>

<!-- Exemplo 8: Múltiplas referências -->
<back>
    <ref-list>
        <title>Referências</title>
        <ref id="B1">
            <mixed-citation>Author A. Title. Journal. 2020;1:1-10.</mixed-citation>
            <element-citation publication-type="journal">
                <person-group person-group-type="author">
                    <name>
                        <surname>Author</surname>
                        <given-names>A</given-names>
                    </name>
                </person-group>
                <source>Journal</source>
                <year>2020</year>
            </element-citation>
        </ref>
        <ref id="B2">
            <mixed-citation>Author B. Book Title. Publisher; 2021.</mixed-citation>
            <element-citation publication-type="book">
                <person-group person-group-type="author">
                    <name>
                        <surname>Author</surname>
                        <given-names>B</given-names>
                    </name>
                </person-group>
                <source>Book Title</source>
                <publisher-name>Publisher</publisher-name>
                <year>2021</year>
            </element-citation>
        </ref>
    </ref-list>
</back>

XML Inválido – Caso 1: Sem em documento indexável (CRITICAL)

<article article-type="research-article">
    <front>
        <!-- conteúdo do front -->
    </front>
    <back>
        <!-- sem ref-list -->
    </back>
</article>

Erro esperado: Elemento <ref-list> é obrigatório em <back> para documentos indexáveis (Critério SciELO Brasil)

XML Inválido – Caso 2: sem (CRITICAL)

<back>
    <ref-list>
        <title>Referências</title>
        <!-- sem ref -->
    </ref-list>
</back>

Erro esperado: <ref-list> deve conter pelo menos um elemento <ref>

XML Inválido – Caso 3: sem (CRITICAL)

<back>
    <ref-list>
        <ref id="B1">
            <element-citation publication-type="journal">
                <source>Journal</source>
                <year>2020</year>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: Elemento <ref> deve conter <mixed-citation>

XML Inválido – Caso 4: sem (CRITICAL)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Author. Title. Journal. 2020.</mixed-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: Elemento <ref> deve conter <element-citation>

XML Inválido – Caso 5: sem @publication-type (CRITICAL)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Author. Title. Journal. 2020.</mixed-citation>
            <element-citation>
                <source>Journal</source>
                <year>2020</year>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: Atributo @publication-type é obrigatório em <element-citation>

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

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Author. Title. Journal. 2020.</mixed-citation>
            <element-citation publication-type="article">
                <source>Journal</source>
                <year>2020</year>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: Valor "article" não está na lista de valores permitidos para @publication-type. Use journal para artigos de periódicos.

XML Inválido – Caso 7: Múltiplos em (ERROR)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Reference text.</mixed-citation>
            <element-citation publication-type="journal">
                <source>Journal</source>
                <year>2020</year>
                <ext-link ext-link-type="uri" xlink:href="http://example.com">http://example.com</ext-link>
                <ext-link ext-link-type="doi" xlink:href="https://doi.org/10.1234/example">https://doi.org/10.1234/example</ext-link>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: É proibida a ocorrência de dois ou mais <ext-link> em <element-citation>

XML Inválido – Caso 8: Múltiplos em (ERROR)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Reference. <ext-link xlink:href="http://example.com">http://example.com</ext-link> and <ext-link xlink:href="http://other.com">http://other.com</ext-link></mixed-citation>
            <element-citation publication-type="journal">
                <source>Journal</source>
                <year>2020</year>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: É proibida a ocorrência de dois ou mais <ext-link> em <mixed-citation>

XML Inválido – Caso 9: Sem (WARNING)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Author. Title. 2020.</mixed-citation>
            <element-citation publication-type="journal">
                <person-group person-group-type="author">
                    <name>
                        <surname>Author</surname>
                        <given-names>A</given-names>
                    </name>
                </person-group>
                <year>2020</year>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: (WARNING) Espera-se que todas as referências tenham <source> (título da fonte citada)

XML Inválido – Caso 10: Sem (WARNING)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Author. Title. Journal.</mixed-citation>
            <element-citation publication-type="journal">
                <person-group person-group-type="author">
                    <name>
                        <surname>Author</surname>
                        <given-names>A</given-names>
                    </name>
                </person-group>
                <source>Journal</source>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: (WARNING) Espera-se que todas as referências tenham pelo menos <year>

XML Inválido – Caso 11: sem (ERROR)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Author. Chapter. In: Book. 1995:31.</mixed-citation>
            <element-citation publication-type="book">
                <source>Book</source>
                <year>1995</year>
                <fpage>31</fpage>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: Quando houver <fpage>, o elemento <lpage> é obrigatório

XML Inválido – Caso 12: sem @Units="pages" (ERROR)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Author. Book Title. Publisher; 2020. 300 p.</mixed-citation>
            <element-citation publication-type="book">
                <source>Book Title</source>
                <year>2020</year>
                <size>300</size>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: Elemento <size> deve ter obrigatoriamente @units="pages"

XML Inválido – Caso 13: com @Units incorreto (ERROR)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Author. Book Title. Publisher; 2020. 300 p.</mixed-citation>
            <element-citation publication-type="book">
                <source>Book Title</source>
                <year>2020</year>
                <size units="page">300</size>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: Valor de @units deve ser "pages". Valor encontrado: "page"

XML Inválido – Caso 14: sem @Content-Type (ERROR)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Website. Accessed 10 Apr 2010.</mixed-citation>
            <element-citation publication-type="webpage">
                <source>Website</source>
                <date-in-citation>10 Apr 2010</date-in-citation>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: Elemento <date-in-citation> deve ter obrigatoriamente @content-type="access-date"

XML Inválido – Caso 15: com @Content-Type incorreto (ERROR)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Website. Accessed 10 Apr 2010.</mixed-citation>
            <element-citation publication-type="webpage">
                <source>Website</source>
                <date-in-citation content-type="accessed">10 Apr 2010</date-in-citation>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: Valor de @content-type deve ser "access-date". Valor encontrado: "accessed"

XML Inválido – Caso 16: sem (ERROR)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>John. Article. Journal. 2020.</mixed-citation>
            <element-citation publication-type="journal">
                <person-group person-group-type="author">
                    <name>
                        <given-names>John</given-names>
                    </name>
                </person-group>
                <source>Journal</source>
                <year>2020</year>
            </element-citation>
        </ref>
    </ref-list>
</back>

Erro esperado: Quando <person-group> contém <name>, o elemento <surname> é obrigatório

XML Inválido – Caso 17: Atributos vazios (CRITICAL)

<back>
    <ref-list>
        <ref id="B1">
            <mixed-citation>Reference.</mixed-citation>
            <element-citation publication-type="">
                <source>Journal</source>
                <year>2020</year>
            </element-citation>
        </ref>
    </ref-list>
</back>

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

Padrão de Implementação

Diretrizes Gerais:

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

    • Consultar implementações similares como article_contribs.py (validação de person-group)
    • Usar estrutura de classes já estabelecida no packtools
    • IMPORTANTE: Verificar se já existem validações parciais para <ref-list> 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 <ref-list> obrigatório não se aplica para errata, retratação, etc.
    • Exemplo: validação de <lpage> só se aplica quando há <fpage>
    • 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 <ref>)
    • Cada dict deve conter: ref_id, has_mixed_citation, has_element_citation, publication_type, has_source, has_year, ext_link_count_element, ext_link_count_mixed, has_fpage, has_lpage, parent, parent_id, parent_lang

  6. Detecção de tipo de artigo:

    • Verificar @article-type para determinar se documento é indexável
    • Tipos não indexáveis: correction, retraction, addendum, expression-of-concern, reviewer-report
    • Usar XPath ou navegação DOM para acessar elemento raiz

  7. Contagem de <ext-link>:

    • Contar elementos <ext-link> dentro de <element-citation>
    • Contar elementos <ext-link> dentro de <mixed-citation>
    • Alertar se count > 1

  8. Validação de elementos condicionais:

    • <lpage> só é obrigatório quando há <fpage>
    • <surname> só é obrigatório quando há <name> dentro de <person-group>

  9. Lista de valores permitidos:

    • Criar constante com valores de @publication-type: ["book", "confproc", "data", "database", "journal", "legal-doc", "letter", "newspaper", "patent", "preprint", "report", "software", "thesis", "webpage", "other"]

Testes Esperados

Casos de teste obrigatórios:

Presença de :

  • Documento indexável com <ref-list> (OK)
  • Documento indexável sem <ref-list> (CRITICAL)
  • Errata sem <ref-list> (OK - exceção)
  • Retratação sem <ref-list> (OK - exceção)
  • Adendo sem <ref-list> (OK - exceção)
  • Manifestação de preocupação sem <ref-list> (OK - exceção)
  • Parecer sem <ref-list> (OK - exceção)

Estrutura de :

  • <ref-list> com pelo menos um <ref> (OK)
  • <ref-list> sem <ref> (CRITICAL)
  • <ref-list> vazio (CRITICAL)

Estrutura de :

  • <ref> com <mixed-citation> e <element-citation> (OK)
  • <ref> sem <mixed-citation> (CRITICAL)
  • <ref> sem <element-citation> (CRITICAL)
  • <ref> sem nenhum dos dois (CRITICAL)

Atributo @publication-type:

  • <element-citation> com @publication-type válido (OK)
  • <element-citation> sem @publication-type (CRITICAL)
  • @publication-type vazio (CRITICAL)
  • Todos os valores permitidos (OK para cada um)
  • Valor inválido "article" (ERROR)
  • Valor inválido "review" (ERROR)
  • Valor com uppercase "Journal" (ERROR - case-sensitive)

Contagem de :

  • <element-citation> sem <ext-link> (OK)
  • <element-citation> com um <ext-link> (OK)
  • <element-citation> com dois <ext-link> (ERROR)
  • <element-citation> com três ou mais <ext-link> (ERROR)
  • <mixed-citation> sem <ext-link> (OK)
  • <mixed-citation> com um <ext-link> (OK)
  • <mixed-citation> com dois <ext-link> (ERROR)

Elementos esperados:

  • <element-citation> com <source> (OK)
  • <element-citation> sem <source> (WARNING)
  • <element-citation> com <year> (OK)
  • <element-citation> sem <year> (WARNING)
  • Com <source> e <year> (OK)
  • Sem <source> nem <year> (WARNING - ambos)

Paginação:

  • Com <fpage> e <lpage> (OK)
  • Com <fpage> sem <lpage> (ERROR)
  • Com <lpage> sem <fpage> (OK - lpage opcional)
  • Sem nenhum dos dois (OK - paginação opcional)

Elemento :

  • <size units="pages"> (OK)
  • <size> sem @units (ERROR)
  • <size units="page"> (ERROR - valor incorreto)
  • <size units="p"> (ERROR - valor incorreto)

Elemento :

  • <date-in-citation content-type="access-date"> (OK)
  • <date-in-citation> sem @content-type (ERROR)
  • <date-in-citation content-type="accessed"> (ERROR - valor incorreto)

Elemento e :

  • <name> com <surname> (OK)
  • <name> sem <surname> (ERROR)
  • <name> com apenas <given-names> (ERROR)
  • <person-group> com <collab> (OK - autoria institucional)

Tipos de publicação:

  • journal (OK)
  • book (OK)
  • confproc (OK)
  • data (OK)
  • database (OK)
  • thesis (OK)
  • webpage (OK)
  • preprint (OK)
  • software (OK)
  • patent (OK)
  • report (OK)
  • legal-doc (OK)
  • letter (OK)
  • newspaper (OK)
  • other (OK)

Múltiplas referências:

  • <ref-list> com uma referência (OK)
  • <ref-list> com múltiplas referências (OK)
  • <ref-list> com 100+ referências (OK - sem limite)

Casos de borda:

  • <ref-list> aninhado (OK - permitido)
  • <mixed-citation> com formatação (OK - permitido)
  • Elementos vazios (CRITICAL)
  • Combinação de múltiplos erros (detectar todos)

Total esperado: ~70 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 (presença, estrutura, atributos, elementos, paginação)

Critérios de Aceite

O PR será aceito quando:

  • Verificação de validações existentes: Código existente para <ref-list> foi analisado e integrado ou substituído adequadamente
  • Todas as regras P0 implementadas (8 validações CRITICAL/ERROR)
  • Todas as regras P1 implementadas (6 validações ERROR/WARNING)
  • Testes unitários passando com cobertura mínima de ~70 casos
  • Nenhum teste existente quebrado
  • Arquivo ref_list_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 referências
  • Validação condicional de <ref-list> obrigatório (exceções para errata, etc.)
  • Validação de estrutura obrigatória (mixed + element citation)
  • Validação de valores permitidos de @publication-type
  • Validação de contagem de <ext-link>
  • Validação condicional de <lpage> quando há <fpage>
  • Validação de atributos obrigatórios em elementos específicos
  • Documentação inline clara (docstrings)

Referências

Documentação SPS:

Critérios SciELO Brasil:

Padrões JATS:

Padrões externos:

Referências internas packtools:

  • Internacionalização: Consultar conversas anteriores sobre implementação de i18n
  • Implementações similares: article_contribs.py (validação de person-group)
  • Funções auxiliares: utils.py (build_response)

Labels Sugeridas

enhancement validation SPS-1.10 scielo-brasil good-first-issue

Impacto Esperado

Antes:

  • Conformidade SPS 1.10 e Critérios SciELO Brasil para <ref-list>: X% (verificar validações existentes)
  • Referências podem estar ausentes em documentos indexáveis
  • Estrutura obrigatória (mixed + element citation) pode estar incompleta
  • Atributo @publication-type pode estar ausente ou incorreto
  • Múltiplos <ext-link> podem passar sem detecção
  • Elementos esperados (source, year) podem estar ausentes
  • Regras de elementos condicionais não aplicadas

Depois:

  • Conformidade SPS 1.10 e Critérios SciELO Brasil para <ref-list>: 70% (14 de 20 regras)
  • Validação CRITICAL de presença de <ref-list> em documentos indexáveis
  • Validação CRITICAL de estrutura obrigatória (mixed + element citation)
  • Validação CRITICAL de @publication-type obrigatório
  • Validação ERROR de valores permitidos de @publication-type
  • Validação ERROR de múltiplos <ext-link>
  • Validação WARNING de elementos esperados (source, year)
  • Validação ERROR de regras condicionais (fpage/lpage, atributos obrigatórios)
  • ~70 testes unitários garantindo qualidade
  • Internacionalização completa (PT/EN/ES)

Benefícios:

  • Garante conformidade com Critérios SciELO Brasil
  • Assegura presença de referências em documentos indexáveis
  • Melhora qualidade de metadados bibliográficos
  • Detecta estruturas incompletas antes da publicação
  • Previne uso de valores incorretos de @publication-type
  • Alerta sobre múltiplos links (problema de estrutura)
  • Facilita geração de métricas bibliométricas
  • Melhora interoperabilidade com sistemas de citação
  • Garante qualidade de dados para indexadores
  • 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