Skip to content

Implementar validações de <graphic> e <inline-graphic> conforme SPS 1.10#1095

Draft
Copilot wants to merge 7 commits intomasterfrom
copilot/add-validations-graphic-elements
Draft

Implementar validações de <graphic> e <inline-graphic> conforme SPS 1.10#1095
Copilot wants to merge 7 commits intomasterfrom
copilot/add-validations-graphic-elements

Conversation

Copy link
Contributor

Copilot AI commented Feb 13, 2026

O que esse PR faz?

Implementa 7 de 10 validações para elementos <graphic> e <inline-graphic> conforme SPS 1.10, atingindo conformidade de 70%, integra as validações ao pipeline de validação XML e resolve duplicidade de validações de acessibilidade.

Regras implementadas:

  • P0 (Critical): @id e @xLink:href obrigatórios em ambos elementos; validação de extensões (.jpg, .jpeg, .png, .tif, .tiff, .svg)
  • P1 (Important): Presença de elementos de acessibilidade (via validador dedicado); restrição de .svg apenas dentro de <alternatives>

Mudanças principais:

  • GraphicValidation.validate_id(): sobrescrito para exigir @id em <inline-graphic> (spec SPS 1.10, anteriormente isento)
  • GraphicValidation.validate_svg_in_alternatives(): novo método valida SVG apenas em <alternatives>
  • XMLGraphicValidation: classe wrapper para integração com pipeline de validação
  • validate_graphics(): função de entrada no pipeline de validação
  • graphic_rules.json: arquivo de configuração com parâmetros de validação
  • Remoção de validação duplicada: GraphicValidation não chama mais validação de acessibilidade, que é tratada pelo validador dedicado XMLAccessibilityDataValidation
# Exemplo de validação SVG
<fig id="f1">
    <graphic id="g1" xlink:href="vector.svg"/>  <!-- ERROR: svg fora de alternatives -->
</fig>

<fig id="f2">
    <alternatives>
        <graphic id="g2" xlink:href="vector.svg"/>  <!-- OK -->
        <graphic id="g3" xlink:href="raster.jpg"/>
    </alternatives>
</fig>

Onde a revisão poderia começar?

  1. packtools/sps/validation/graphic.py - lógica de validação e integração ao pipeline (120 linhas)
    • Importante: Note que a validação de acessibilidade foi removida para evitar duplicidade
  2. packtools/sps/validation/xml_validations.py - função validate_graphics() adicionada
  3. packtools/sps/validation/xml_validator.py - registro do grupo "graphic" no pipeline
  4. packtools/sps/validation_rules/graphic_rules.json - configuração de parâmetros
  5. tests/sps/validation/test_graphic.py - suite de testes (17 testes, todos passando)

Como este poderia ser testado manualmente?

Teste 1: Validação individual de elementos

from lxml import etree
from packtools.sps.models.graphic import XmlGraphic
from packtools.sps.validation.graphic import GraphicValidation

xml = etree.fromstring('''
<article xmlns:xlink="http://www.w3.org/1999/xlink">
    <body>
        <fig id="f1">
            <graphic id="g1" xlink:href="image.svg"/>  <!-- Deve falhar -->
        </fig>
        <p>
            <inline-graphic xlink:href="icon.png"/>  <!-- Deve falhar (sem @id) -->
        </p>
    </body>
</article>
''')

params = {
    "media_attributes_error_level": "CRITICAL",
    "xlink_href_error_level": "ERROR",
    "valid_extension": ["jpg", "png", "tif", "tiff", "jpeg", "svg"],
    "svg_error_level": "ERROR",
}

for graphic_data in XmlGraphic(xml).data:
    validator = GraphicValidation(graphic_data, params)
    results = list(validator.validate())
    # Verificar erros CRITICAL/ERROR nos results
    # Note: validações de acessibilidade NÃO aparecem aqui (são processadas separadamente)

Teste 2: Validação através do pipeline completo

from lxml import etree
from packtools.sps.validation.xml_validator import validate_xml_content

xml = etree.fromstring('''<article>...</article>''')
params = {}  # Usa regras padrão de graphic_rules.json

for result in validate_xml_content(xml, params):
    if result.get("group") == "graphic":
        for item in result.get("items", []):
            print(f"[graphic] {item.get('title')}: {item.get('response')}")
    elif result.get("group") == "accessibility":
        for item in result.get("items", []):
            print(f"[accessibility] {item.get('title')}: {item.get('response')}")

Executar testes:

python3 -m unittest tests.sps.validation.test_graphic -v

Algum cenário de contexto que queira dar?

Breaking change (intencional): <inline-graphic> agora requer @id (spec SPS 1.10). Anteriormente, base class isentava elementos inline-* desta validação. XMLs existentes sem @id em <inline-graphic> agora falharão com CRITICAL.

Rationale: SPS 1.10 explicitamente define "@id (obrigatório em <graphic> e <inline-graphic>)". A isenção anterior não estava alinhada com a spec.

Validação SVG: Nova verificação contextual - SVG permitido, mas apenas dentro de <alternatives>. Permite SVG vetorial com fallback raster para compatibilidade.

Integração ao Pipeline: As validações agora executam automaticamente durante a validação XML padrão. Resultados aparecem no relatório sob o grupo "graphic" junto com outros grupos de validação (fig, media, ext-link, etc.).

Arquitetura de Integração:

  • XMLGraphicValidation: wrapper que itera sobre todos os elementos graphic/inline-graphic no documento
  • validate_graphics(): ponto de entrada no pipeline, carrega configurações de graphic_rules.json
  • Registro em xml_validator.py: adiciona grupo "graphic" à sequência de validações

Separação de Responsabilidades (Fix para duplicidade):

  • GraphicValidation valida apenas atributos específicos de graphic: @id, @xLink:href, SVG em alternatives
  • XMLAccessibilityDataValidation (validador dedicado no pipeline) valida exclusivamente acessibilidade: <alt-text>, <long-desc>
  • Esta separação elimina duplicidade de entradas nos relatórios e inconsistências de severidade

Cobertura de testes:

  • 17 testes unitários cobrindo todos os 7 cenários de validação
  • Testes de integração para fluxo completo
  • Zero vulnerabilidades (CodeQL ✓)

Screenshots

N/A - validações backend

Quais são tickets relevantes?

Referenciado automaticamente pelo sistema.

Referências

  • SPS 1.10 - Especificação de <graphic> e <inline-graphic>
  • Padrão de validação: packtools/sps/validation/visual_resource_base.py
  • Padrão de integração: packtools/sps/validation/media.py (XMLMediaValidation)
  • Validação de acessibilidade: packtools/sps/validation/accessibility_data.py
Original prompt

This section details on the original issue you should resolve

<issue_title>Criar validações para os elementos e </issue_title>
<issue_description>## Objetivo

Implementar validações para os elementos <graphic> e <inline-graphic> conforme a especificação SPS 1.10, aumentando a conformidade de X% para 70% (7 de 10 regras).

Nota: Algumas validações para <graphic> e <inline-graphic> podem já estar parcialmente implementadas no repositório (ex: em validação de <fig>). Este Issue visa reavaliar, complementar e garantir cobertura completa das regras SPS 1.10 para ambos os elementos.


Contexto

Os elementos <graphic> e <inline-graphic> são usados exclusivamente para figuras e imagens estáticas. <graphic> representa figuras em elementos estruturais (fig, app, supplementary-material, table-wrap, bio), enquanto <inline-graphic> representa figuras inline dentro de parágrafos. Validações corretas garantem que apenas formatos suportados sejam usados, que atributos obrigatórios estejam presentes, e que boas práticas de acessibilidade sejam seguidas.

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.graphicfigura

Regras principais conforme SPS 1.10:

  1. Atributos obrigatórios (ambos elementos):

    • @id (obrigatório em <graphic> e <inline-graphic>)
    • @xlink:href (obrigatório em <graphic> e <inline-graphic>)
  2. Extensões de arquivo permitidas:

    • .jpg ou .jpeg (preferencialmente)
    • .png
    • .tif ou .tiff
    • .svg - apenas dentro de <alternatives>
  3. Uso correto:

    • <graphic> - para figuras em elementos estruturais
    • <inline-graphic> - para figuras inline em parágrafos
    • Não usar <inline-graphic> para criar caracteres especiais comuns (diacríticos, símbolos de copyright - usar Unicode)
  4. Acessibilidade (recomendado):

    • Todas as figuras devem ter <alt-text> e/ou <long-desc>
  5. Contextos válidos para <graphic>:

    • Dentro de <fig>
    • Dentro de <app> (apêndice)
    • Dentro de <supplementary-material> (material suplementar)
    • Dentro de <table-wrap> (tabela)
    • Dentro de <bio> (foto de autor)
  6. Contextos válidos para <inline-graphic>:

    • Dentro de <p> (parágrafo)
    • Outros elementos inline
  7. Posicionamento:

    • Figuras em <graphic> devem aparecer logo abaixo da primeira chamada no texto
    • Exceto quando dentro de <app-group> ou <supplementary-material>

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

# Regra Nível Descrição
1 Validar presença de @id em <graphic> CRITICAL O atributo @id é obrigatório em <graphic>
2 Validar presença de @xlink:href em <graphic> CRITICAL O atributo @xlink:href é obrigatório em <graphic>
3 Validar presença de @id em <inline-graphic> CRITICAL O atributo @id é obrigatório em <inline-graphic>
4 Validar presença de @xlink:href em <inline-graphic> CRITICAL O atributo @xlink:href é obrigatório em <inline-graphic>
5 Validar extensão de arquivo em @xlink:href ERROR Arquivo deve ter extensão permitida: .jpg, .jpeg, .png, .tif, .tiff (.svg apenas em <alternatives>)

P1 – Importantes (implementar se possível)

# Regra Nível Descrição
6 Validar presença de <alt-text> ou <long-desc> WARNING Para acessibilidade, figuras devem ter <alt-text> e/ou <long-desc> como elemento filho
7 Validar uso de .svg apenas em <alternatives> ERROR Extensão .svg só é permitida quando <graphic> está dentro de <alternatives>

P2 – Futuras (fora do escopo deste Issue)

# Regra Motivo de exclusão
8 Validar que <inline-graphic> não é usado para caracteres especiais Alta complexidade - requer análise semântica de contexto de uso
9 Validar posicionamento após primeira chamada no texto Alta complexidade - requer análise de fluxo do documento e referências cruzadas
10 Validar contextos válidos de uso Baixa prioridade - schema XML já restringe contextos permitidos

Arquivos a Criar/Modificar

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

  • packtools/sps/models/graphic.py ou similar – Verificar se modelo existe
  • packtools/sps/validation/fig.py – Pode ter validações de <graphic> dentro de <fig>
  • packtools/sps/validation/graphic.py – Verificar validações existentes
  • packtools/sps/validation/rules/graphic_rules.json ou similar – Verificar configuração

Criar (se não existirem):

  • packtools/sps/models/graphic.py – Modelo de extração de dados
  • `packtools/sps/valida...

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Copilot AI and others added 3 commits February 13, 2026 12:26
Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com>
Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com>
Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com>
Copilot AI changed the title [WIP] Implement validation for <graphic> and <inline-graphic> elements Implementar validações de <graphic> e <inline-graphic> conforme SPS 1.10 Feb 13, 2026
Copy link
Collaborator

@Rossi-Luciano Rossi-Luciano left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Problema 1 — GraphicValidation não está integrado ao pipeline de validação
GraphicValidation (definido em graphic.py) não é importado nem chamado em nenhum ponto de xml_validations.py ou xml_validator.py. O módulo existe mas está completamente desconectado da cadeia de execução. Como consequência, nenhuma das validações implementadas diretamente na classe — validate_id, validate_xlink_href e validate_svg_in_alternatives — produz resultado no relatório.
Para integrar, é necessário: (1) criar uma função validate_graphics(xmltree, params) em xml_validations.py que instancie GraphicValidation para cada e do XML; (2) adicionar o yield correspondente com group: "graphic" em xml_validator.py; e (3) criar o arquivo graphic_rules.json em validation_rules/ com os parâmetros necessários (media_attributes_error_level, xlink_href_error_level, svg_error_level).

Problema 2 — Detecções de G1 e G3 vêm do módulo errado
A ausência de @id em (G1) e a extensão .gif inválida (G3) aparecem no relatório, mas emitidas por ArticleFigValidation (validate_figs), não por GraphicValidation. Isso tem duas implicações: (1) o override de validate_id implementado em GraphicValidation — que estende a obrigatoriedade do @id também para — nunca é exercido, pois ArticleFigValidation não processa ; (2) os níveis de erro aplicados são os de fig_rules, não os parâmetros configurados para GraphicValidation, o que pode gerar inconsistência caso as regras divirjam.

Problema 3 — Chave incorreta em fig_rules.json e inclusão indevida de svg
O arquivo fig_rules.json enviado define a chave "allowed file extensions" (com espaços), enquanto o código em FigValidation lê rules["allowed_file_extensions"] (com underscores). A chave nunca é encontrada, fazendo FigValidation recorrer ao get_default_params() interno e ignorar completamente a configuração do arquivo.
Adicionalmente, o valor fornecido inclui "svg" na lista de extensões permitidas. Incluir svg incondicionalmente contorna a regra SPS 1.10 que restringe SVG ao contexto , eliminando a validação de G4 mesmo que a chave fosse lida corretamente.
Correções necessárias: renomear a chave para "allowed_file_extensions" e remover "svg" da lista — o controle de SVG é responsabilidade de validate_svg_in_alternatives, não da lista de extensões.

Problema 4 — validate_svg_in_alternatives ausente para (G5)
Mesmo após a integração de GraphicValidation ao pipeline (Problema 1), a validação de SVG em fora de só funcionará se o modelo que alimenta GraphicValidation preencher corretamente o campo parent_tag para elementos . ArticleFigValidation não processa , portanto este cenário permanece sem cobertura independentemente da correção do fig_rules.json.

Problema 5 — alt_text_exist_error_level definido como "WARNING" em accessibility_data_rules.json
A ausência de (G6) é reportada como WARNING porque accessibility_data_rules.json define "alt_text_exist_error_level": "WARNING". O comportamento está correto em relação à configuração atual, mas diverge do nível esperado pelos casos de teste (ERROR). Se a especificação SPS 1.10 trata ausente como erro efetivo, o parâmetro deve ser alterado para "ERROR" no arquivo de regras. A decisão impacta todas as validações de acessibilidade que usam XMLAccessibilityDataValidation, não apenas as de .

@robertatakenaka
Copy link
Member

@copilot identifiquei alguns problemas para que você faça a correção

Problema 1 — GraphicValidation não está integrado ao pipeline de validação
GraphicValidation (definido em graphic.py) não é importado nem chamado em nenhum ponto de xml_validations.py ou xml_validator.py. O módulo existe mas está completamente desconectado da cadeia de execução. Como consequência, nenhuma das validações implementadas diretamente na classe — validate_id, validate_xlink_href e validate_svg_in_alternatives — produz resultado no relatório.
Para integrar, é necessário: (1) criar uma função validate_graphics(xmltree, params) em xml_validations.py que instancie GraphicValidation para cada e do XML; (2) adicionar o yield correspondente com group: "graphic" em xml_validator.py; e (3) criar o arquivo graphic_rules.json em validation_rules/ com os parâmetros necessários (media_attributes_error_level, xlink_href_error_level, svg_error_level).

Problema 2 — Detecções de G1 e G3 vêm do módulo errado
A ausência de @id em (G1) e a extensão .gif inválida (G3) aparecem no relatório, mas emitidas por ArticleFigValidation (validate_figs), não por GraphicValidation. Isso tem duas implicações: (1) o override de validate_id implementado em GraphicValidation — que estende a obrigatoriedade do @id também para — nunca é exercido, pois ArticleFigValidation não processa ; (2) os níveis de erro aplicados são os de fig_rules, não os parâmetros configurados para GraphicValidation, o que pode gerar inconsistência caso as regras divirjam.

Problema 3 — Chave incorreta em fig_rules.json e inclusão indevida de svg
O arquivo fig_rules.json enviado define a chave "allowed file extensions" (com espaços), enquanto o código em FigValidation lê rules["allowed_file_extensions"] (com underscores). A chave nunca é encontrada, fazendo FigValidation recorrer ao get_default_params() interno e ignorar completamente a configuração do arquivo.
Adicionalmente, o valor fornecido inclui "svg" na lista de extensões permitidas. Incluir svg incondicionalmente contorna a regra SPS 1.10 que restringe SVG ao contexto , eliminando a validação de G4 mesmo que a chave fosse lida corretamente.
Correções necessárias: renomear a chave para "allowed_file_extensions" e remover "svg" da lista — o controle de SVG é responsabilidade de validate_svg_in_alternatives, não da lista de extensões.

Problema 4 — validate_svg_in_alternatives ausente para (G5)
Mesmo após a integração de GraphicValidation ao pipeline (Problema 1), a validação de SVG em fora de só funcionará se o modelo que alimenta GraphicValidation preencher corretamente o campo parent_tag para elementos . ArticleFigValidation não processa , portanto este cenário permanece sem cobertura independentemente da correção do fig_rules.json.

Problema 5 — alt_text_exist_error_level definido como "WARNING" em accessibility_data_rules.json
A ausência de (G6) é reportada como WARNING porque accessibility_data_rules.json define "alt_text_exist_error_level": "WARNING". O comportamento está correto em relação à configuração atual, mas diverge do nível esperado pelos casos de teste (ERROR). Se a especificação SPS 1.10 trata ausente como erro efetivo, o parâmetro deve ser alterado para "ERROR" no arquivo de regras. A decisão impacta todas as validações de acessibilidade que usam XMLAccessibilityDataValidation, não apenas as de .

- Add XMLGraphicValidation class to wrap GraphicValidation for pipeline integration
- Create graphic_rules.json with validation parameters for graphic/inline-graphic elements
- Add validate_graphics() function to xml_validations.py
- Register graphic validation group in xml_validator.py validate_xml_content()

This resolves the issue where GraphicValidation was defined but never called.
Now graphic validations will run as part of the standard validation workflow.

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

Copilot AI commented Mar 2, 2026

Problema 1 — GraphicValidation não está integrado ao pipeline de validação
GraphicValidation (definido em graphic.py) não é importado nem chamado em nenhum ponto de xml_validations.py ou xml_v...

Fixed in commit 1d1513c.

I've integrated GraphicValidation into the validation pipeline:

  • Added XMLGraphicValidation wrapper class following the pattern of XMLMediaValidation
  • Created graphic_rules.json with validation configuration
  • Added validate_graphics() function to xml_validations.py
  • Registered the "graphic" validation group in xml_validator.py

GraphicValidation now runs automatically as part of the standard validation workflow.

@copilot identifiquei alguns problemas para que você faça a correção

Problema 1 — GraphicValidation não está integrado ao pipeline de validação
...

Fixed in commit 1d1513c.

The GraphicValidation module is now fully integrated into the validation pipeline. All validations for <graphic> and <inline-graphic> elements will now execute during standard XML validation and appear in validation reports under the "graphic" group.

Copilot AI changed the title Implementar validações de <graphic> e <inline-graphic> conforme SPS 1.10 Implementar validações de <graphic> e <inline-graphic> com integração ao pipeline Mar 2, 2026
@Rossi-Luciano Rossi-Luciano self-requested a review March 3, 2026 13:50
Copy link
Collaborator

@Rossi-Luciano Rossi-Luciano left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Duplicidade sistemática de entradas de acessibilidade

  • A maioria dos erros de acessibilidade aparece duas ou três vezes no relatório de erros, com subject diferente (graphic vs accessibility vs fig). Isso ocorre porque dois validadores independentes percorrem os mesmos elementos: GraphicValidation (via graphic.py) chama self.accessibility_validation.validate(), e um segundo validador de figura (externo ao módulo avaliado) também itera pelos mesmos <graphic>. Não é um erro do módulo, mas gera ruído no relatório.

Inconsistência de nível entre validadores para o <alt-text> com 145 caracteres

  • O validador de figura reporta WARNING (subject=fig), GraphicValidation via AccessibilityDataValidation reporta CRITICAL (subject=graphic). O mesmo defeito recebe severidades diferentes dependendo de qual validador dispara. Embora ambos os registros estejam no relatório de erros, a inconsistência pode causar confusão na triagem.

@robertatakenaka
Copy link
Member

@copilot pode resolver as questões:
Duplicidade sistemática de entradas de acessibilidade

A maioria dos erros de acessibilidade aparece duas ou três vezes no relatório de erros, com subject diferente (graphic vs accessibility vs fig). Isso ocorre porque dois validadores independentes percorrem os mesmos elementos: GraphicValidation (via graphic.py) chama self.accessibility_validation.validate(), e um segundo validador de figura (externo ao módulo avaliado) também itera pelos mesmos . Não é um erro do módulo, mas gera ruído no relatório.
Inconsistência de nível entre validadores para o com 145 caracteres

O validador de figura reporta WARNING (subject=fig), GraphicValidation via AccessibilityDataValidation reporta CRITICAL (subject=graphic). O mesmo defeito recebe severidades diferentes dependendo de qual validador dispara. Embora ambos os registros estejam no relatório de erros, a inconsistência pode causar confusão na triagem.

GraphicValidation was calling self.accessibility_validation.validate() which caused
duplicate entries in validation reports because XMLAccessibilityDataValidation also
processes all graphic elements in the pipeline.

Changes:
- Removed accessibility validation call from GraphicValidation.validate()
- Updated docstring to clarify that accessibility is handled separately
- Added comment explaining why accessibility validation is not included

This resolves the issue where accessibility errors appeared 2-3 times with different
subjects (graphic, accessibility, fig) in validation reports.

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

Copilot AI commented Mar 3, 2026

Duplicidade sistemática de entradas de acessibilidade

  • A maioria dos erros de acessibilidade aparece duas ou três vezes no relatório de erros, com subject diferente (graphic vs accessibility ...

Fixed in commit 7b2e4b7.

Removed the duplicate accessibility validation call from GraphicValidation.validate(). The accessibility checks are now handled exclusively by the dedicated XMLAccessibilityDataValidation pipeline validator, eliminating:

  • Duplicate entries in validation reports (graphic vs accessibility vs fig subjects)
  • Severity inconsistencies for the same validation issue

GraphicValidation now focuses solely on graphic-specific validations (@id, @xLink:href, SVG in alternatives).

@copilot pode resolver as questões:
Duplicidade sistemática de entradas de acessibilidade

...

Fixed in commit 7b2e4b7.

The duplicate accessibility validation entries have been resolved by removing the accessibility validation call from GraphicValidation. Each validation now runs only once through its dedicated validator in the pipeline, producing clean reports without duplicates or severity inconsistencies.

Copilot AI changed the title Implementar validações de <graphic> e <inline-graphic> com integração ao pipeline Implementar validações de <graphic> e <inline-graphic> conforme SPS 1.10 Mar 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Criar validações para os elementos <graphic> e <inline-graphic>

3 participants