Skip to content

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

Open
#1140
Open
Criar validações para o elemento <related-article>#1105
#1140
Assignees
robertatakenakaRossi-Lucianocopilot-swe-agent
@Rossi-Luciano

Description

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

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:

Padrões JATS:

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.

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