feat(validation): Implementar validações para elemento `<ext-link>` conforme SPS 1.10 by Copilot · Pull Request #1091 · scieloorg/packtools

Copilot · 2026-02-13T12:11:16Z

O que esse PR faz?

Implementa 6 validações para o elemento <ext-link> conforme especificação SPS 1.10, aumentando conformidade de 0% para 67%.

Validações P0 (Critical/Error):

Presença obrigatória de @ext-link-type e @xlink:href
Formato de URL (deve iniciar com http:// ou https://)
Valores permitidos: uri, doi, pmid, pmcid, clinical-trial

Validações P1 (Warning):

Texto descritivo (detecta frases genéricas em PT/EN, case-insensitive)
@xlink:title obrigatório quando texto é genérico ou URL

Características técnicas:

Suporte completo a i18n (advice_text + advice_params)
Extração de ext-links em artigo principal e sub-artigos
Tratamento correto do namespace XLink
Validações condicionais (skip quando atributo ausente)

Onde a revisão poderia começar?

packtools/sps/validation/ext_link.py - Lógica de validação (6 métodos geradores)
packtools/sps/models/ext_link.py - Extração de dados (herda de Fulltext)
tests/sps/validation/test_ext_link.py - 26 testes unitários

Como este poderia ser testado manualmente?

from lxml import etree
from packtools.sps.validation.ext_link import ExtLinkValidation

# Caso 1: Atributos faltando (CRITICAL)
xml = """<article xmlns:xlink="http://www.w3.org/1999/xlink">
    <body><ext-link>Link</ext-link></body>
</article>"""
validator = ExtLinkValidation(etree.fromstring(xml))
list(validator.validate_ext_link_type_presence())  # CRITICAL
list(validator.validate_xlink_href_presence())     # CRITICAL

# Caso 2: URL sem protocolo (ERROR)
xml2 = """<article xmlns:xlink="http://www.w3.org/1999/xlink">
    <body><ext-link ext-link-type="uri" xlink:href="www.example.com">Link</ext-link></body>
</article>"""
validator2 = ExtLinkValidation(etree.fromstring(xml2))
list(validator2.validate_xlink_href_format())  # ERROR

# Caso 3: Texto genérico (WARNING)
xml3 = """<article xmlns:xlink="http://www.w3.org/1999/xlink">
    <body><ext-link ext-link-type="uri" xlink:href="https://example.com">clique aqui</ext-link></body>
</article>"""
validator3 = ExtLinkValidation(etree.fromstring(xml3))
list(validator3.validate_descriptive_text())  # WARNING

Executar testes: python3 -m unittest tests.sps.validation.test_ext_link -v

Algum cenário de contexto que queira dar?

Padrões seguidos:

build_response() com i18n completo (análogo a article_doi.py, article_contribs.py)
Modelo herda de Fulltext para contexto de parent (análogo a related_articles.py)
Validações condicionais retornam early quando dependências ausentes
Namespace XLink tratado: {http://www.w3.org/1999/xlink}href → xlink_href

Frases genéricas detectadas:
leia mais, clique aqui, acesse, veja mais, saiba mais, click here, read more, see more, learn more, more info

Regras não implementadas (fora de escopo):

Validação específica de formato DOI (já existe em utils.validate_doi_format())
Validação de formato PMID/PMCID (baixa prioridade, requer integração com APIs externas)

Garantias de qualidade:

✅ 26 testes unitários (100% pass rate)
✅ CodeQL: 0 vulnerabilidades
✅ Testes existentes não afetados
✅ Code review: 1 fix de whitespace aplicado

Screenshots

N/A - Validações backend sem interface gráfica.

Quais são tickets relevantes?

Issue original contém especificação completa SPS 1.10 para <ext-link>.

Referências

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 <ext-link> conforme a especificação SPS 1.10, aumentando a conformidade de 0% para 67% (6 de 9 regras).

Contexto

O elemento <ext-link> é usado para marcar links ou hyperlink text externos em artigos científicos, garantindo acessibilidade e interoperabilidade. Validações corretas asseguram que os links estejam bem formados, possuam atributos obrigatórios e sigam boas práticas de acessibilidade (texto descritivo ao invés de URLs genéricas).

Conformidade atual: 0 de 9 regras implementadas (0%)
Meta após implementação: 6 de 9 regras (67%)

Documentação SPS

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

Regras principais conforme SPS 1.10:

Atributos obrigatórios:
- @ext-link-type (obrigatório)
- @xlink:href (obrigatório)
Valores permitidos para @ext-link-type:
- uri - Link para website
- doi - Link DOI (deve incluir doi.org/ ou dx.doi.org/)
- pmid - Link para PubMed
- pmcid - Link para PubMed Central
- clinical-trial - Link para registro de ensaio clínico
Formato do @xlink:href:
- Deve ser URL completa iniciando com http:// ou https://
Acessibilidade:
- Texto dentro de <ext-link> deve ser descritivo
- Evitar textos genéricos como "Leia mais", "clique aqui", "acesse"
- Quando o texto não for descritivo suficiente, usar @xlink:title com descrição
Restrições:
- Não usar <uri> ou <self-uri> (substituídos por <ext-link>)
- Exceto em referências bibliográficas onde a URL pode ser exposta

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

#	Regra	Nível	Descrição
1	Validar presença de `@ext-link-type`	CRITICAL	O atributo `@ext-link-type` é obrigatório em todos os `<ext-link>`
2	Validar presença de `@xlink:href`	CRITICAL	O atributo `@xlink:href` é obrigatório em todos os `<ext-link>`
3	Validar formato de `@xlink:href`	ERROR	O valor de `@xlink:href` deve ser URL completa começando com `http://` ou `https://`
4	Validar valor de `@ext-link-type`	ERROR	O valor de `@ext-link-type` deve ser um dos permitidos: `uri`, `doi`, `pmid`, `pmcid`, `clinical-trial`

P1 – Importantes (implementar se possível)

#	Regra	Nível	Descrição
5	Validar texto descritivo	WARNING	O texto do link não deve ser genérico ("leia mais", "clique aqui", "acesse", "veja mais", "saiba mais", "click here", "read more", "see more"). Validação case-insensitive.
6	Validar `@xlink:title` quando texto genérico	WARNING	Quando o texto for genérico ou for a própria URL, o atributo `@xlink:title` deve estar presente com descrição do destino do link

P2 – Futuras (fora do escopo deste Issue)

#	Regra	Motivo de exclusão
7	Validar formato específico de DOI em `@xlink:href`	Validação de formato DOI específico já existe em `utils.validate_doi_format()`
8	Validar formato de PMID	Baixa prioridade - depende de integração com PubMed API
9	Validar formato de PMCID	Baixa prioridade - depende de integração com PMC API

Arquivos a Criar/Modificar

Criar:

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

Referenciar (implementações similares):

packtools/sps/models/related_article.py – Modelo similar (também é link)
packtools/sps/validation/article_doi.py – Validação de atributos obrigatórios e formato
packtools/sps/validation/utils.py – Funções auxiliares (build_response, is_valid_url_format)

Exemplos de XML

XML Válido (deve passar sem erros):

<!-- Exemplo 1: hyperlink text descritivo -->
<p>
    <ext-link ext-link-type="uri" xlink:href="https://www.scielo.br/">SciELO Brasil</ext-link>
</p>

<!-- Exemplo 2: link com @xlink:title para contexto adicional -->
<p>
    <ext-link ext-link-type="uri" 
              xlink:href="https://docs.google.com/document/d/123/edit" 
              xlink:title="Guia de uso de elementos e atributos XML para documentos SPS">
        Leia mais sobre link no SPS
    </ext-link>
</p>

<!-- Exemplo 3: link DOI -->
<p>
    <ext-link ext-link-type="doi" xlink:href="https://doi.org/10.1590/1806-9584-2025v33n1103677">
        https://doi.org/10.1590/1806-9584-2025v33n1103677
    </ext-link>
</p>

<!-- Exemplo 4: link para ensaio clínico -->
<p>
    <ext-link ext-link-type="clinical-trial" xlink...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes scieloorg/packtools#1082

<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

…sing) Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com>

Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com>

Initial plan

6feb3f6

Copilot AI assigned Copilot and robertatakenaka Feb 13, 2026

Copilot started work on behalf of robertatakenaka February 13, 2026 12:11 View session

Copilot AI and others added 2 commits February 13, 2026 12:16

Implement ext-link validations with model and tests (all 26 tests pas…

9e4ef44

…sing) Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com>

Fix whitespace in test file (code review feedback)

992d351

Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Implement validations for ext-link element~~ feat(validation): Implementar validações para elemento <ext-link> conforme SPS 1.10 Feb 13, 2026

Copilot AI requested a review from robertatakenaka February 13, 2026 12:22

Copilot finished work on behalf of robertatakenaka February 13, 2026 12:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(validation): Implementar validações para elemento `<ext-link>` conforme SPS 1.10#1091

feat(validation): Implementar validações para elemento `<ext-link>` conforme SPS 1.10#1091
Copilot wants to merge 3 commits intomasterfrom
copilot/add-validations-for-ext-link

Copilot AI commented Feb 13, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Copilot AI commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

O que esse PR faz?

Onde a revisão poderia começar?

Como este poderia ser testado manualmente?

Algum cenário de contexto que queira dar?

Screenshots

Quais são tickets relevantes?

Referências

Contexto

Documentação SPS

Regras principais conforme SPS 1.10:

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

P1 – Importantes (implementar se possível)

P2 – Futuras (fora do escopo deste Issue)

Arquivos a Criar/Modificar

Criar:

Referenciar (implementações similares):

Exemplos de XML

XML Válido (deve passar sem erros):

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Feb 13, 2026 •

edited

Loading