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

[Rossi-Luciano]

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:

• SPS 1.10 – <ref-list>: Lista de Referências
• SPS 1.10 – Elementos Obrigatórios para Publicação de Documentos Indexáveis
• SPS 1.10 – Declaração de Disponibilidade de Dados
• SPS 1.10 – Guia de citação de dados de pesquisa

Critérios SciELO Brasil:

• Seção 5.2.8.1 – Textos em XML – SciELO Publishing Schema

Padrões JATS:

• JATS 1.3 – <ref-list>
• JATS 1.3 – <ref>
• JATS 1.3 – <mixed-citation>
• JATS 1.3 – <element-citation>
• JATS 1.3 – <person-group>

Padrões externos:

• Sample PubMed Central Citations

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.