Skip to content

Criar validações para o elemento <product> #1102

New issue
New issue
Open
Open
Criar validações para o elemento <product>#1102
Assignees
robertatakenakaRossi-Luciano
@Rossi-Luciano

Description

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

Objetivo

Implementar validações para o elemento <product> conforme a especificação SPS 1.10, aumentando a conformidade de X% para 70% (7 de 10 regras).

Nota: Algumas validações para <product> 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 <product> é usado para marcação da referência de resenha quando relacionada a um livro ou capítulo de livro. Deve aparecer em artigos com @article-type="book-review". Validações corretas garantem que o atributo obrigatório esteja presente, que elementos essenciais da referência bibliográfica estejam completos, e que haja consistência com o tipo de artigo.

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

Regras principais conforme SPS 1.10:

  1. Ocorrência:

    • <product> pode aparecer zero ou mais vezes em <article-meta>

  2. Atributo obrigatório:

    • @product-type="book" é obrigatório em <product>

  3. Contexto de uso:

    • <product> deve aparecer em artigos com @article-type="book-review"
    • Serve para resenhas de livros ou capítulos de livros

  4. Elementos tipicamente presentes:

    • <person-group person-group-type="author"> - Autor(es) do livro resenhado
    • <source> - Título do livro
    • <publisher-name> - Editora
    • <publisher-loc> - Local de publicação
    • <year> - Ano de publicação
    • <isbn> - ISBN do livro
    • <size units="pages"> - Número de páginas
    • <person-group person-group-type="translator"> - Tradutor(es) quando aplicável

  5. Elementos essenciais para referência bibliográfica:

    • Autor, título (<source>), editora, ano são elementos fundamentais

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

# Regra Nível Descrição
1 Validar presença de @product-type CRITICAL O atributo @product-type é obrigatório em <product>
2 Validar valor de @product-type ERROR O valor de @product-type deve ser "book" para resenhas de livros
3 Validar presença de <source> CRITICAL O elemento <source> (título do livro) é obrigatório em <product>
4 Validar consistência com tipo de artigo ERROR Se <product> está presente, <article> deve ter @article-type="book-review"

P1 – Importantes (implementar se possível)

# Regra Nível Descrição
5 Validar presença de autor WARNING Recomenda-se que <product> contenha <person-group person-group-type="author"> com informações do(s) autor(es)
6 Validar presença de editora WARNING Recomenda-se que <product> contenha <publisher-name>
7 Validar presença de ano WARNING Recomenda-se que <product> contenha <year>

P2 – Futuras (fora do escopo deste Issue)

# Regra Motivo de exclusão
8 Validar formato completo de ISBN Média complexidade - requer validação de checksum
9 Validar consistência de dados bibliográficos Baixa prioridade - dados bibliográficos têm variações aceitas
10 Validar que não há <product> quando @article-type não é "book-review" Baixa prioridade - inverso da regra 4

Arquivos a Criar/Modificar

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

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

Criar (se não existirem):

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

Referenciar (implementações similares):

  • packtools/sps/validation/article_contribs.py – Validação de person-group
  • packtools/sps/validation/utils.py – Funções auxiliares (build_response)

Exemplos de XML

XML Válido (deve passar sem erros):

<!-- Exemplo 1: Produto completo com todos os elementos recomendados -->
<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="book">
                <person-group person-group-type="author">
                    <name>
                        <surname>ONFRAY</surname>
                        <given-names>Michel</given-names>
                    </name>
                </person-group>
                <source>La comunidad filosófica: manifiesto por una universidad popular</source>
                <person-group person-group-type="translator">
                    <name>
                        <surname>Castro</surname>
                        <given-names>Antonia García</given-names>
                    </name>
                </person-group>
                <publisher-loc>Barcelona</publisher-loc>
                <publisher-name>Gedisa</publisher-name>
                <year>2008</year>
                <size units="pages">155</size>
                <isbn>978-84-9784-252-5</isbn>
            </product>
        </article-meta>
    </front>
</article>

<!-- Exemplo 2: Produto com múltiplos autores -->
<article article-type="book-review" xml:lang="pt">
    <front>
        <article-meta>
            <product product-type="book">
                <person-group person-group-type="author">
                    <name>
                        <surname>Silva</surname>
                        <given-names>João</given-names>
                    </name>
                    <name>
                        <surname>Santos</surname>
                        <given-names>Maria</given-names>
                    </name>
                </person-group>
                <source>Manual de Metodologia Científica</source>
                <publisher-loc>São Paulo</publisher-loc>
                <publisher-name>Atlas</publisher-name>
                <year>2020</year>
            </product>
        </article-meta>
    </front>
</article>

<!-- Exemplo 3: Produto mínimo (apenas elementos obrigatórios) -->
<article article-type="book-review" xml:lang="es">
    <front>
        <article-meta>
            <product product-type="book">
                <source>Historia de la Filosofía Moderna</source>
            </product>
        </article-meta>
    </front>
</article>

<!-- Exemplo 4: Múltiplos produtos (resenha de múltiplos livros) -->
<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="book">
                <person-group person-group-type="author">
                    <name>
                        <surname>Smith</surname>
                        <given-names>John</given-names>
                    </name>
                </person-group>
                <source>Introduction to Philosophy</source>
                <publisher-name>Oxford University Press</publisher-name>
                <year>2019</year>
            </product>
            <product product-type="book">
                <person-group person-group-type="author">
                    <name>
                        <surname>Jones</surname>
                        <given-names>Mary</given-names>
                    </name>
                </person-group>
                <source>Advanced Philosophy</source>
                <publisher-name>Cambridge University Press</publisher-name>
                <year>2020</year>
            </product>
        </article-meta>
    </front>
</article>

<!-- Exemplo 5: Produto com editor organizador -->
<article article-type="book-review" xml:lang="pt">
    <front>
        <article-meta>
            <product product-type="book">
                <person-group person-group-type="editor">
                    <name>
                        <surname>Oliveira</surname>
                        <given-names>Carlos</given-names>
                    </name>
                </person-group>
                <source>Coletânea de Artigos sobre Educação</source>
                <publisher-loc>Rio de Janeiro</publisher-loc>
                <publisher-name>Fundação Getúlio Vargas</publisher-name>
                <year>2021</year>
            </product>
        </article-meta>
    </front>
</article>

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

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product>
                <source>Book Title</source>
            </product>
        </article-meta>
    </front>
</article>

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

XML Inválido – Caso 2: @product-type com valor incorreto (ERROR)

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="other">
                <source>Book Title</source>
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: Valor de @product-type deve ser "book". Valor encontrado: "other"

XML Inválido – Caso 3: @product-type vazio (CRITICAL)

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="">
                <source>Book Title</source>
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: Atributo @product-type não pode estar vazio

XML Inválido – Caso 4: Sem (CRITICAL)

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="book">
                <person-group person-group-type="author">
                    <name>
                        <surname>Smith</surname>
                        <given-names>John</given-names>
                    </name>
                </person-group>
                <publisher-name>Oxford University Press</publisher-name>
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: Elemento <source> (título do livro) é obrigatório em <product>

XML Inválido – Caso 5: vazio (CRITICAL)

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="book">
                <source></source>
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: Elemento <source> não pode estar vazio

XML Inválido – Caso 6: apenas espaços (CRITICAL)

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="book">
                <source>   </source>
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: Elemento <source> não pode conter apenas espaços

XML Inválido – Caso 7: com article-type diferente de "book-review" (ERROR)

<article article-type="research-article" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="book">
                <source>Book Title</source>
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: Elemento <product> presente mas @article-type não é "book-review". Para resenhas de livros, use @article-type="book-review" em <article>

XML Inválido – Caso 8: Sem autor (WARNING)

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="book">
                <source>Book Title</source>
                <publisher-name>Publisher</publisher-name>
                <year>2020</year>
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: (WARNING) Recomenda-se incluir <person-group person-group-type="author"> com informações do(s) autor(es) do livro resenhado

XML Inválido – Caso 9: Sem editora (WARNING)

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="book">
                <person-group person-group-type="author">
                    <name>
                        <surname>Smith</surname>
                        <given-names>John</given-names>
                    </name>
                </person-group>
                <source>Book Title</source>
                <year>2020</year>
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: (WARNING) Recomenda-se incluir <publisher-name> para completude da referência bibliográfica

XML Inválido – Caso 10: Sem ano (WARNING)

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="book">
                <person-group person-group-type="author">
                    <name>
                        <surname>Smith</surname>
                        <given-names>John</given-names>
                    </name>
                </person-group>
                <source>Book Title</source>
                <publisher-name>Publisher</publisher-name>
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: (WARNING) Recomenda-se incluir <year> para completude da referência bibliográfica

XML Inválido – Caso 11: @product-type com uppercase (ERROR)

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="Book">
                <source>Book Title</source>
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: Valor de @product-type deve ser "book" (minúsculas). Valor encontrado: "Book"

XML Inválido – Caso 12: vazio (CRITICAL)

<article article-type="book-review" xml:lang="en">
    <front>
        <article-meta>
            <product product-type="book">
            </product>
        </article-meta>
    </front>
</article>

Erro esperado: Elemento <product> não pode estar vazio. Pelo menos <source> é obrigatório.

Padrão de Implementação

Diretrizes Gerais:

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

    • Consultar implementações similares como article_contribs.py (validação de person-group)
    • Usar estrutura de classes já estabelecida no packtools
    • IMPORTANTE: Verificar se já existem validações parciais para <product> 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 consistência com article-type só se aplica se <product> existir
    • Exemplo: warnings de elementos recomendados não devem ser CRITICAL
    • 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 <product>)
    • Cada dict deve conter: product_type, source, has_author, has_publisher_name, has_year, person_groups, isbn, publisher_loc, size, parent, parent_id, parent_lang
    • Detectar article-type do documento raiz para validação de consistência

  6. Validação de article-type:

    • Acessar elemento <article> raiz
    • Verificar se @article-type="book-review" quando há <product>
    • Usar XPath: /article/@article-type ou navegação DOM

  7. Validação de elementos presentes:

    • Verificar presença de <source> (obrigatório)
    • Verificar presença de <person-group person-group-type="author"> (recomendado)
    • Verificar presença de <publisher-name> (recomendado)
    • Verificar presença de <year> (recomendado)

  8. Validação de texto vazio:

    • Usar .strip() para verificar se <source> tem conteúdo real
    • Strings com apenas espaços devem ser consideradas inválidas

Testes Esperados

Casos de teste obrigatórios:

Atributo @product-type:

  • <product> com @product-type="book" (OK)
  • <product> sem @product-type (CRITICAL)
  • @product-type vazio (CRITICAL)
  • @product-type apenas espaços (CRITICAL)
  • @product-type com valor incorreto "other" (ERROR)
  • @product-type com valor incorreto "journal" (ERROR)
  • @product-type com uppercase "Book" (ERROR)
  • @product-type com uppercase "BOOK" (ERROR)

Elemento :

  • <product> com <source> (OK)
  • <product> sem <source> (CRITICAL)
  • <source> vazio (CRITICAL)
  • <source> apenas espaços (CRITICAL)
  • <source> com conteúdo válido (OK)

Consistência com article-type:

  • <product> com @article-type="book-review" (OK)
  • <product> com @article-type="research-article" (ERROR)
  • <product> com @article-type="review-article" (ERROR)
  • <product> sem @article-type em article (ERROR)
  • Sem <product> e @article-type="book-review" (OK - product é opcional)

Elementos recomendados:

  • <product> com autor (OK)
  • <product> sem autor (WARNING)
  • <product> com <publisher-name> (OK)
  • <product> sem <publisher-name> (WARNING)
  • <product> com <year> (OK)
  • <product> sem <year> (WARNING)
  • <product> com todos os elementos recomendados (OK)

Estrutura de person-group:

  • Autor com person-group-type="author" (OK)
  • Editor com person-group-type="editor" (OK)
  • Tradutor com person-group-type="translator" (OK)
  • Múltiplos autores (OK)
  • <person-group> vazio (WARNING)

Múltiplos produtos:

  • Artigo com um <product> (OK)
  • Artigo com dois <product> (OK)
  • Artigo com três ou mais <product> (OK)
  • Artigo sem <product> (OK - zero ou mais vezes)

Elementos opcionais:

  • <product> com <isbn> (OK)
  • <product> com <publisher-loc> (OK)
  • <product> com <size units="pages"> (OK)
  • <product> sem elementos opcionais (OK)

Casos de borda:

  • <product> vazio (CRITICAL - falta source)
  • <source> com caracteres especiais (OK)
  • <source> com subtítulo (OK)
  • Ano com 4 dígitos 2020 (OK)
  • ISBN com formato válido (OK)
  • ISBN com formato inválido (permitir - não validar formato completo)

Total esperado: ~45 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, source, consistência, elementos recomendados)

Critérios de Aceite

O PR será aceito quando:

  • Verificação de validações existentes: Código existente para <product> foi analisado e integrado ou substituído adequadamente
  • Todas as regras P0 implementadas (4 validações CRITICAL/ERROR)
  • Todas as regras P1 implementadas (3 validações WARNING)
  • Testes unitários passando com cobertura mínima de ~45 casos
  • Nenhum teste existente quebrado
  • Arquivo product_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 elementos
  • Validação de consistência com article-type funcionando
  • Validação de elementos obrigatórios funcionando
  • Validação de elementos recomendados funcionando (WARNING)
  • Suporte para múltiplos produtos (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: article_contribs.py (validação de person-group)
  • 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 <product>: X% (verificar validações existentes)
  • Atributo obrigatório pode estar ausente
  • Valores incorretos de @product-type podem passar
  • Inconsistência com @article-type não detectada
  • Elementos essenciais podem estar ausentes
  • Referências bibliográficas incompletas não alertadas

Depois:

  • Conformidade SPS 1.10 para <product>: 70% (7 de 10 regras)
  • Validação CRITICAL de @product-type obrigatório
  • Validação ERROR de valor correto ("book")
  • Validação CRITICAL de <source> obrigatório
  • Validação ERROR de consistência com article-type
  • Validação WARNING de elementos recomendados (autor, editora, ano)
  • ~45 testes unitários garantindo qualidade
  • Internacionalização completa (PT/EN/ES)

Benefícios:

  • Melhora a qualidade dos XMLs SciELO
  • Garante consistência em resenhas de livros
  • Detecta inconsistências de tipo de artigo
  • Assegura presença de informações bibliográficas essenciais
  • Alerta sobre referências incompletas
  • Facilita processamento automatizado de resenhas
  • Melhora qualidade de metadados bibliográficos
  • Facilita indexação e recuperação de resenhas
  • Facilita manutenção e depuração de XMLs

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