Skip to content

Add <xref> element validations per SPS 1.10 specification#1136

Draft
Copilot wants to merge 2 commits intomasterfrom
copilot/create-validations-for-xref-element
Draft

Add <xref> element validations per SPS 1.10 specification#1136
Copilot wants to merge 2 commits intomasterfrom
copilot/create-validations-for-xref-element

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Mar 19, 2026 •
edited
Loading

O que esse PR faz?

Implementa 7 das 10 regras de validação para o elemento <xref> conforme SPS 1.10 e Critérios SciELO Brasil (70% de conformidade).

P0 – Críticas:

  • validate_rid_presence (CRITICAL) — @rid obrigatório e não-vazio
  • validate_ref_type_presence (CRITICAL) — @ref-type obrigatório e não-vazio
  • validate_ref_type_value (ERROR) — @ref-type deve ser um dos 16 valores permitidos
  • validate_bibr_presence (ERROR) — ao menos um <xref ref-type="bibr"> no documento
  • validate_rid_has_corresponding_id (ERROR) — todo @rid deve ter @id correspondente

P1 – Importantes:

  • validate_transcript_xref (WARNING) — <sec sec-type="transcript"> precisa de <xref ref-type="sec">
  • validate_aff_self_closing (INFO) — <xref ref-type="aff"> sem texto deve usar formato self-closing

Corrige bugs no método existente validate_attrib_name_and_value_has_corresponding_xref() que usava self.xref_xml (inexistente) e o builtin id em vez da variável do loop.

Onde a revisão poderia começar?

packtools/sps/validation/article_xref.py — contém todas as novas validações e as correções nos métodos existentes.

Como este poderia ser testado manualmente?

from lxml import etree
from packtools.sps.validation.article_xref import ArticleXrefValidation

xml = etree.fromstring('''
<article article-type="research-article" xml:lang="pt">
  <body>
    <p><xref ref-type="bibr" rid="B1">1</xref></p>
    <p><xref ref-type="image" rid="f1">Figure 1</xref></p>
    <p><xref ref-type="fig">Figure 2</xref></p>
  </body>
  <back>
    <ref-list><ref id="B1"><mixed-citation>Ref</mixed-citation></ref></ref-list>
  </back>
</article>
''')

v = ArticleXrefValidation(xml)
for r in v.validate_rid_presence():
    print(r["response"])      # OK, OK, CRITICAL (missing rid)
for r in v.validate_ref_type_value():
    print(r["response"])      # OK, ERROR ("image" invalid), skipped (empty)
for r in v.validate_bibr_presence():
    print(r["response"])      # OK

74 testes unitários: python -m pytest tests/sps/validation/test_article_xref.py -v

Algum cenário de contexto que queira dar?

Validações parciais para <xref> já existiam (validate_xref_rid_has_corresponding_element_id, validate_element_id_has_corresponding_xref_rid, validate_attrib_name_and_value_has_corresponding_xref). Este PR complementa com as regras faltantes e corrige bugs nos métodos existentes. Os testes existentes foram reescritos para o formato atual com suporte a i18n (msg_text, msg_params, adv_text, adv_params).

Arquivos alterados:

  • packtools/sps/validation_rules/xref_rules.json — novo arquivo de configuração de regras
  • packtools/sps/models/v2/article_xref.py — all_xrefs(), all_ids(), transcript_sections() em XMLCrossReference
  • packtools/sps/validation/article_xref.py — 7 novos métodos + correção de bugs
  • packtools/sps/validation/xml_validations.py — orquestrador atualizado
  • tests/sps/validation/test_article_xref.py — 74 testes em 14 classes

Screenshots

N/A

Quais são tickets relevantes?

Referências

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • api.crossref.org
    • Triggering command: /usr/bin/python python -m pytest tests/sps/validation/ -v --ignore=tests/sps/validation/test_footnotes.py (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Original prompt

This section details on the original issue you should resolve

<issue_title>Criar validações para o elemento </issue_title>
<issue_description>## Objetivo

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

Nota: Algumas validações para <xref> 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 <xref> é usado para referência cruzada relacionando informações no texto. Para SciELO Brasil, é obrigatória a presença de pelo menos uma <xref> com @ref-type="bibr" (referência bibliográfica) no documento. Validações corretas garantem presença de atributos obrigatórios, valores válidos, e correspondência entre @rid e @id.

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

Documentação SPS

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

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

  1. Ocorrência:

    • <xref> pode aparecer zero ou mais vezes em: <article-title>, <attrib>, <contrib>, <p>, <td>, <th>, <trans-title>, <sec>, <verse-line>

  2. Obrigatoriedade (Critério SciELO Brasil):

    • <xref> com @ref-type="bibr" deve ocorrer pelo menos uma vez no documento

  3. Atributos obrigatórios:

    • @rid - Contém identificador do elemento referenciado (obrigatório)
    • @ref-type - Especifica tipo de referência cruzada (obrigatório)

  4. Valores permitidos para @ref-type:

    • aff - Afiliação
    • app - Apêndice
    • author-notes - Notas relacionadas ao autor
    • bibr - Referência bibliográfica
    • bio - Bibliografia do autor
    • boxed-text - Caixa de texto
    • contrib - Autoria
    • corresp - Autor correspondente
    • disp-formula - Fórmula/Equação
    • fig - Figura ou grupo de figuras
    • fn - Nota
    • list - Lista ou item da lista
    • sec - Seção
    • supplementary-material - Material suplementar
    • table - Tabela ou grupo de tabelas
    • table-fn - Nota de rodapé de tabelas

  5. Correspondência @rid e @id:

    • Todo @rid obrigatoriamente deve ter @id correspondente no XML
    • Um @id pode ou não ter @rid correspondente

  6. Regra especial para transcrição:

    • <xref ref-type="sec" @rid> é obrigatório quando existe <sec sec-type="transcript">

  7. Regra especial para afiliação:

    • Para afiliação sem identificação de etiqueta no PDF: usar <xref ref-type="aff" rid="aff1"/> (self-closing)

  8. Regra de <sup>:

    • <sup> não pode abarcar <xref> quando não há caracteres textuais
    • Neste caso <sup> deve estar dentro de <xref>

  9. Menção obrigatória:

    • Para valores exceto aff, deve ocorrer menção ou etiqueta correspondente no texto

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

# Regra Nível Descrição
1 Validar presença de @rid CRITICAL O atributo @rid é obrigatório em <xref>
2 Validar presença de @ref-type CRITICAL O atributo @ref-type é obrigatório em <xref>
3 Validar valores permitidos de @ref-type ERROR O valor de @ref-type deve estar na lista de valores permitidos
4 Validar presença de pelo menos um @ref-type="bibr" ERROR Documento deve conter pelo menos uma <xref> com @ref-type="bibr" (Critério SciELO Brasil)
5 Validar correspondência @rid e @id ERROR Todo @rid em <xref> deve ter @id correspondente no documento

P1 – Importantes (implementar se possível)

# Regra Nível Descrição
6 Validar presença de <xref> para transcrição WARNING Quando há <sec sec-type="transcript">, deve haver <xref ref-type="sec"> referenciando-a
7 Validar formato de afiliação sem label INFO Para @ref-type="aff" sem conteúdo textual, recomenda-se usar elemento self-closing <xref ... />

P2 – Futuras (fora do escopo deste Issue)

# Regra Motivo de exclusão
8 Validar que <sup> não abarca <xref> sem texto Alta complexidade - requer análise de estrutura e conteúdo textual
9 Validar presença de menção/etiqueta no texto Alta complexidade - requer análise semântica do texto
10 Validar formatação consistente de citações Baixa prioridade - formato livre permitido

Arquivos a Criar/Modificar

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

  • packtools/sps/models/xref.py ou similar – Verificar se modelo existe
  • packtools/sps/validation/xref.py – Verificar validações existentes
  • `packtools/sps/validation/rules/xref_rul...

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

@robertatakenaka
Add xref validation rules per SPS 1.10: rid/ref-type presence, ref-ty…
8ad460f 
…pe values, bibr presence, rid-id correspondence, transcript xref, aff self-closing

Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com>
Copilot AI changed the title [WIP] Implement validations for the <xref> element Add <xref> element validations per SPS 1.10 specification Mar 19, 2026
Copilot AI requested a review from robertatakenaka March 19, 2026 12:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@robertatakenaka robertatakenaka Awaiting requested review from robertatakenaka

At least 2 approving reviews are required to merge this pull request.

Assignees

@robertatakenaka robertatakenaka

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Criar validações para o elemento <xref>

2 participants

@robertatakenaka