Criar validações para o elemento <related-article>

[Rossi-Luciano]

Objetivo

Implementar validações para o elemento <related-article> conforme a especificação SPS 1.10, aumentando a conformidade de X% para 70% (8 de 12 regras).

Nota: Algumas validações para <related-article> 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 <related-article> indica documentos relacionados ao que está sendo publicado (erratas, retratações, adendos, comentários, cartas, pareceres, preprints). Quando o documento relacionado também está publicado em SciELO, deve-se adicionar o <related-article> em ambos os documentos. Validações corretas garantem presença de atributos obrigatórios, valores corretos, e uso adequado de DOI vs URI.

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

---

Documentação SPS

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

Regras principais conforme SPS 1.10:

1. Ocorrência:

   • <related-article> pode aparecer zero ou mais vezes em <article-meta> e <front-stub>

2. Atributos obrigatórios:

   • @related-article-type (obrigatório)
   • @id (obrigatório)
   • @ext-link-type (obrigatório, valores: doi ou uri)

3. Valores permitidos para @related-article-type:

   • corrected-article - Errata
   • correction-forward - Documento corrigido pela errata
   • retracted-article - Retratação (total ou parcial)
   • retraction-forward - Documento retratado totalmente
   • partial-retraction - Documento retratado parcialmente
   • addended-article - Adendo
   • addendum - Documento objeto do adendo
   • expression-of-concern - Manifestação de preocupação
   • object-of-concern - Documento objeto de manifestação de preocupação
   • commentary-article - Comentário ou carta
   • commentary - Documento comentado ou resposta
   • reply - Resposta (para comentário ou carta)
   • letter - Carta ou resposta para carta
   • reviewed-article - Parecer (revisão por pares)
   • reviewer-report - Documento com parecer
   • preprint - Manuscrito em servidor de preprints

4. Regras de @ext-link-type:

   • Padrão: @ext-link-type="doi"
   • Exceções que permitem uri:
     • @related-article-type="reviewer-report" (parecer com link externo)
     • @related-article-type="preprint" (preprint)
   • Preferência: usar doi se existir, mesmo para exceções

5. Ordem obrigatória de atributos:

   1. @related-article-type
   2. @id
   3. @xlink:href
   4. @ext-link-type

6. Posicionamento:

   • Deve ser inserido abaixo de <permissions> ou acima de <counts>

7. Tradução (<sub-article>):

   • Documentos com tradução devem ter <related-article> também no idioma traduzido
   • Não repetir mesmo @id de <article> em <sub-article>

---

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

#	Regra	Nível	Descrição
1	Validar presença de @related-article-type	CRITICAL	O atributo @related-article-type é obrigatório em <related-article>
2	Validar presença de @id	CRITICAL	O atributo @id é obrigatório em <related-article>
3	Validar presença de @ext-link-type	CRITICAL	O atributo @ext-link-type é obrigatório em <related-article>
4	Validar valores permitidos de @related-article-type	ERROR	O valor de @related-article-type deve estar na lista de valores permitidos
5	Validar valores permitidos de @ext-link-type	ERROR	O valor de @ext-link-type deve ser "doi" ou "uri"
6	Validar uso de doi como padrão	WARNING	@ext-link-type deve ser "doi" (exceto para reviewer-report e preprint que podem usar "uri")

P1 – Importantes (implementar se possível)

#	Regra	Nível	Descrição
7	Validar presença de @xlink:href	ERROR	O atributo @xlink:href é obrigatório em <related-article>
8	Recomendar ordem de atributos	INFO	Atributos devem seguir a ordem: @related-article-type, @id, @xlink:href, @ext-link-type

P2 – Futuras (fora do escopo deste Issue)

#	Regra	Motivo de exclusão
9	Validar posicionamento após <permissions> ou antes de <counts>	Média complexidade - requer análise de ordem de elementos irmãos
10	Validar presença em <sub-article> quando há no artigo principal	Alta complexidade - requer análise cross-document
11	Validar unicidade de @id entre <article> e <sub-article>	Média complexidade - requer análise cross-document
12	Validar formato de DOI em @xlink:href quando @ext-link-type="doi"	Baixa prioridade - validação de formato já pode existir em outras partes

---

Arquivos a Criar/Modificar

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

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

Criar (se não existirem):

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

Referenciar (implementações similares):

• packtools/sps/validation/ext_link.py – Validação de links similar
• packtools/sps/validation/utils.py – Funções auxiliares (build_response)

---

Exemplos de XML

XML Válido (deve passar sem erros):

<!-- Exemplo 1: Preprint relacionado (pode usar uri) -->
<article-meta>
    <related-article related-article-type="preprint" 
                     id="r1" 
                     xlink:href="https://preprints.scielo.org/index.php/scielo/preprint/view/11166" 
                     ext-link-type="uri"/>
</article-meta>

<!-- Exemplo 2: Errata relacionada (usar doi) -->
<article-meta>
    <related-article related-article-type="corrected-article" 
                     id="r1" 
                     xlink:href="10.1590/123436773822" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 3: Documento corrigido por errata -->
<article-meta>
    <related-article related-article-type="correction-forward" 
                     id="r1" 
                     xlink:href="10.1590/123456720182998e" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 4: Resposta para carta -->
<article-meta>
    <related-article related-article-type="letter" 
                     id="r1" 
                     xlink:href="10.1590/123456720182998e" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 5: Carta com múltiplos relacionamentos -->
<article-meta>
    <related-article related-article-type="commentary" 
                     id="r1" 
                     xlink:href="10.1590/123456720182998e" 
                     ext-link-type="doi"/>
    <related-article related-article-type="reply" 
                     id="r2" 
                     xlink:href="10.1590/123456720182999r" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 6: Retratação total -->
<article-meta>
    <related-article related-article-type="retracted-article" 
                     id="r1" 
                     xlink:href="10.1590/original-article" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 7: Documento retratado -->
<article-meta>
    <related-article related-article-type="retraction-forward" 
                     id="r1" 
                     xlink:href="10.1590/retraction-notice" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 8: Retratação parcial -->
<article-meta>
    <related-article related-article-type="partial-retraction" 
                     id="r1" 
                     xlink:href="10.1590/partial-retraction" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 9: Adendo -->
<article-meta>
    <related-article related-article-type="addended-article" 
                     id="r1" 
                     xlink:href="10.1590/original-article" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 10: Documento objeto de adendo -->
<article-meta>
    <related-article related-article-type="addendum" 
                     id="r1" 
                     xlink:href="10.1590/addendum-notice" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 11: Manifestação de preocupação -->
<article-meta>
    <related-article related-article-type="expression-of-concern" 
                     id="r1" 
                     xlink:href="10.1590/original-article" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 12: Documento objeto de manifestação -->
<article-meta>
    <related-article related-article-type="object-of-concern" 
                     id="r1" 
                     xlink:href="10.1590/concern-notice" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 13: Parecer (revisão por pares) com uri -->
<article-meta>
    <related-article related-article-type="reviewer-report" 
                     id="r1" 
                     xlink:href="https://example.com/review/123" 
                     ext-link-type="uri"/>
</article-meta>

<!-- Exemplo 14: Artigo revisado -->
<article-meta>
    <related-article related-article-type="reviewed-article" 
                     id="r1" 
                     xlink:href="10.1590/original-article" 
                     ext-link-type="doi"/>
</article-meta>

<!-- Exemplo 15: Comentário -->
<article-meta>
    <related-article related-article-type="commentary-article" 
                     id="r1" 
                     xlink:href="10.1590/original-article" 
                     ext-link-type="doi"/>
</article-meta>

XML Inválido – Caso 1: Sem @related-article-type (CRITICAL)

<article-meta>
    <related-article id="r1" 
                     xlink:href="10.1590/123456" 
                     ext-link-type="doi"/>
</article-meta>

Erro esperado: Atributo @related-article-type é obrigatório em <related-article>

XML Inválido – Caso 2: Sem @id (CRITICAL)

<article-meta>
    <related-article related-article-type="corrected-article" 
                     xlink:href="10.1590/123456" 
                     ext-link-type="doi"/>
</article-meta>

Erro esperado: Atributo @id é obrigatório em <related-article>

XML Inválido – Caso 3: Sem @ext-link-type (CRITICAL)

<article-meta>
    <related-article related-article-type="corrected-article" 
                     id="r1" 
                     xlink:href="10.1590/123456"/>
</article-meta>

Erro esperado: Atributo @ext-link-type é obrigatório em <related-article>

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

<article-meta>
    <related-article related-article-type="related" 
                     id="r1" 
                     xlink:href="10.1590/123456" 
                     ext-link-type="doi"/>
</article-meta>

Erro esperado: Valor "related" não está na lista de valores permitidos para @related-article-type

XML Inválido – Caso 5: @ext-link-type com valor inválido (ERROR)

<article-meta>
    <related-article related-article-type="corrected-article" 
                     id="r1" 
                     xlink:href="10.1590/123456" 
                     ext-link-type="url"/>
</article-meta>

Erro esperado: Valor "url" não permitido para @ext-link-type. Valores permitidos: "doi", "uri"

XML Inválido – Caso 6: Usando uri quando deveria usar doi (WARNING)

<article-meta>
    <related-article related-article-type="corrected-article" 
                     id="r1" 
                     xlink:href="https://doi.org/10.1590/123456" 
                     ext-link-type="uri"/>
</article-meta>

Erro esperado: (WARNING) Para @related-article-type="corrected-article", use @ext-link-type="doi". Valor "uri" só é permitido para reviewer-report e preprint

XML Inválido – Caso 7: Sem @xLink:href (ERROR)

<article-meta>
    <related-article related-article-type="corrected-article" 
                     id="r1" 
                     ext-link-type="doi"/>
</article-meta>

Erro esperado: Atributo @xlink:href é obrigatório em <related-article>

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

<article-meta>
    <related-article related-article-type="" 
                     id="" 
                     xlink:href="" 
                     ext-link-type=""/>
</article-meta>

Erro esperado: Atributos obrigatórios não podem estar vazios

XML Inválido – Caso 9: @related-article-type apenas espaços (CRITICAL)

<article-meta>
    <related-article related-article-type="   " 
                     id="r1" 
                     xlink:href="10.1590/123456" 
                     ext-link-type="doi"/>
</article-meta>

Erro esperado: Atributo @related-article-type não pode conter apenas espaços

XML Inválido – Caso 10: Valor com uppercase (ERROR)

<article-meta>
    <related-article related-article-type="Corrected-Article" 
                     id="r1" 
                     xlink:href="10.1590/123456" 
                     ext-link-type="doi"/>
</article-meta>

Erro esperado: Valor de @related-article-type deve estar em minúsculas. Use corrected-article ao invés de Corrected-Article

XML Inválido – Caso 11: @ext-link-type uppercase (ERROR)

<article-meta>
    <related-article related-article-type="corrected-article" 
                     id="r1" 
                     xlink:href="10.1590/123456" 
                     ext-link-type="DOI"/>
</article-meta>

Erro esperado: Valor de @ext-link-type deve estar em minúsculas. Use doi ao invés de DOI

XML Inválido – Caso 12: @xLink:href vazio (ERROR)

<article-meta>
    <related-article related-article-type="corrected-article" 
                     id="r1" 
                     xlink:href="" 
                     ext-link-type="doi"/>
</article-meta>

Erro esperado: Atributo @xlink:href não pode estar vazio

XML Inválido – Caso 13: Preprint com doi mas poderia ser uri (OK - preferência)

<article-meta>
    <related-article related-article-type="preprint" 
                     id="r1" 
                     xlink:href="10.12345/preprint.123" 
                     ext-link-type="doi"/>
</article-meta>

Nota: Este é válido (OK) porque doi é sempre preferido, mesmo para preprint

---

Padrão de Implementação

Diretrizes Gerais:

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

   • Consultar implementações similares como ext_link.py (validação de links)
   • Usar estrutura de classes já estabelecida no packtools
   • IMPORTANTE: Verificar se já existem validações parciais para <related-article> 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 preferência por doi é WARNING, não ERROR
   • Exemplo: validação de ordem de atributos é INFO
   • 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 <related-article>)
   • Cada dict deve conter: related_article_type, id, xlink_href, ext_link_type, parent, parent_id, parent_lang

6. Lista de valores permitidos:

   • Criar constante com valores de @related-article-type: ["corrected-article", "correction-forward", "retracted-article", "retraction-forward", "partial-retraction", "addended-article", "addendum", "expression-of-concern", "object-of-concern", "commentary-article", "commentary", "reply", "letter", "reviewed-article", "reviewer-report", "preprint"]
   • Criar constante com valores de @ext-link-type: ["doi", "uri"]

7. Validação de uso de doi vs uri:

   • Tipos que permitem uri: ["reviewer-report", "preprint"]
   • Para outros tipos, se ext-link-type="uri", gerar WARNING recomendando doi
   • Comparação deve ser case-sensitive (valores devem ser minúsculos)

8. Validação de ordem de atributos:

   • Ordem esperada: related-article-type, id, xlink:href, ext-link-type
   • Nível: INFO (informativo, não bloqueia)
   • Pode usar análise de XML source ou ordem de atributos do elemento

---

Testes Esperados

Casos de teste obrigatórios:

Atributos obrigatórios:

• <related-article> com todos os atributos (OK)
• Sem @related-article-type (CRITICAL)
• Sem @id (CRITICAL)
• Sem @ext-link-type (CRITICAL)
• Sem @xlink:href (ERROR)
• Atributos vazios (CRITICAL)
• Atributos apenas com espaços (CRITICAL)

Valores de @related-article-type:

• Todos os valores permitidos (OK para cada um)
• corrected-article (OK)
• correction-forward (OK)
• retracted-article (OK)
• retraction-forward (OK)
• partial-retraction (OK)
• addended-article (OK)
• addendum (OK)
• expression-of-concern (OK)
• object-of-concern (OK)
• commentary-article (OK)
• commentary (OK)
• reply (OK)
• letter (OK)
• reviewed-article (OK)
• reviewer-report (OK)
• preprint (OK)
• Valor inválido "related" (ERROR)
• Valor inválido "errata" (ERROR - use corrected-article)
• Valor com uppercase "Corrected-Article" (ERROR)

Valores de @ext-link-type:

• @ext-link-type="doi" (OK)
• @ext-link-type="uri" (OK para reviewer-report/preprint)
• Valor inválido "url" (ERROR)
• Valor inválido "link" (ERROR)
• Uppercase "DOI" (ERROR)
• Uppercase "URI" (ERROR)

Preferência doi vs uri:

• corrected-article com doi (OK)
• corrected-article com uri (WARNING - use doi)
• preprint com doi (OK - preferido)
• preprint com uri (OK)
• reviewer-report com doi (OK - preferido)
• reviewer-report com uri (OK)
• retracted-article com uri (WARNING - use doi)
• addendum com uri (WARNING - use doi)

Múltiplos related-articles:

• Artigo com um <related-article> (OK)
• Artigo com dois <related-article> (OK)
• Artigo com múltiplos <related-article> (OK)
• Artigo sem <related-article> (OK - zero ou mais vezes)

Contextos:

• <related-article> em <article-meta> (OK)
• <related-article> em <front-stub> (OK)

Casos de borda:

• @id com caracteres especiais (OK)
• @xlink:href com URL completa (OK)
• @xlink:href apenas com DOI (OK)
• @xlink:href com prefixo https://doi.org/ (OK)
• Valores com espaços extras (ERROR)

Total esperado: ~50 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 (atributos, valores, preferências, múltiplos)

---

Critérios de Aceite

O PR será aceito quando:

• Verificação de validações existentes: Código existente para <related-article> foi analisado e integrado ou substituído adequadamente
• Todas as regras P0 implementadas (6 validações CRITICAL/ERROR/WARNING)
• Todas as regras P1 implementadas (2 validações ERROR/INFO)
• Testes unitários passando com cobertura mínima de ~50 casos
• Nenhum teste existente quebrado
• Arquivo related_article_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 todos os atributos
• Validação de valores permitidos case-sensitive
• Validação de preferência doi vs uri funcionando (WARNING)
• Suporte para múltiplos <related-article> (zero ou mais vezes)
• Documentação inline clara (docstrings)

---

Referências

Documentação SPS:

• SPS 1.10 – <related-article>: Relação entre Documentos
• SPS 1.10 – Guia para Publicação de Errata
• SPS 1.10 – Guia para Publicação de Retratação
• SPS 1.10 – Guia para Publicação de Adendo
• SPS 1.10 – Guia para publicação de Manifestação de Preocupação
• SPS 1.10 – Carta
• SPS 1.10 – Comentário
• SPS 1.10 – Parecer: Revisão por Pares Aberta
• SPS 1.10 – Preprint: documentos publicados anteriormente como Preprint

Padrões JATS:

• JATS 1.3 – <related-article>
• XLink Namespace

Referências internas packtools:

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

---

Labels Sugeridas

enhancement validation SPS-1.10 good-first-issue

---

Impacto Esperado

Antes:

• Conformidade SPS 1.10 para <related-article>: X% (verificar validações existentes)
• Atributos obrigatórios podem estar ausentes
• Valores incorretos podem passar sem detecção
• Uso inadequado de uri vs doi não alertado
• Tipos de relacionamento inválidos não detectados

Depois:

• Conformidade SPS 1.10 para <related-article>: 70% (8 de 12 regras)
• Validação CRITICAL de atributos obrigatórios
• Validação ERROR de valores permitidos
• Validação WARNING de preferência por doi
• ~50 testes unitários garantindo qualidade
• Internacionalização completa (PT/EN/ES)

Benefícios:

• Melhora a qualidade dos XMLs SciELO
• Garante relacionamentos corretos entre documentos
• Detecta tipos inválidos de relacionamento
• Promove uso de DOI (mais estável que URIs)
• Facilita navegação entre documentos relacionados
• Melhora rastreabilidade de erratas, retratações, etc.
• Garante conformidade com padrões SPS
• Facilita processamento automatizado de relacionamentos
• Melhora experiência do usuário na plataforma SciELO
• 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.