Skip to content

Criar validações para o elemento <permissions> #1101

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

Description

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

Objetivo

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

Nota: Algumas validações para <permissions> 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 <permissions> define condições sob as quais o conteúdo do documento pode ser usado, acessado e distribuído. Para SciELO Brasil é obrigatória a declaração de licença Creative Commons CC-BY. Validações corretas garantem conformidade com políticas de Ciência Aberta, presença de atributos obrigatórios, e consistência entre idioma e links de licença.

Conformidade atual: X de 12 regras implementadas (X%)
Meta após implementação: 9 de 12 regras (75%)

Documentação SPS

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

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

  1. Ocorrência:

    • <permissions> deve aparecer uma vez em <article-meta>

  2. Licença obrigatória (SciELO Brasil):

    • Declaração de licença Creative Commons CC-BY é obrigatória
    • Elemento <license> é obrigatório
    • Elemento <license-p> é obrigatório dentro de <license>

  3. Atributos obrigatórios em <license>:

    • @license-type="open-access" (obrigatório)
    • @xlink:href (obrigatório - link CC-BY correspondente ao idioma)
    • @xml:lang (obrigatório - idioma do texto da licença)

  4. Links válidos para @xlink:href por idioma:

    • Português: https://creativecommons.org/licenses/by/4.0/deed.pt
    • Inglês: https://creativecommons.org/licenses/by/4.0/deed.en
    • Espanhol: https://creativecommons.org/licenses/by/4.0/deed.es

  5. Consistência idioma e link:

    • @xml:lang deve corresponder ao idioma do link em @xlink:href
    • Exemplo: xml:lang="pt" → link deve terminar com deed.pt

  6. Texto padrão para <license-p>:

    • Quando PDF não indica texto específico, usar: "This is an open-access article distributed under the terms of the Creative Commons Attribution License"

  7. Elementos de Copyright (condicionais):

    • <copyright-statement> - Quando PDF apresenta declaração de copyright
    • <copyright-year> - Quando há informação de ano
    • <copyright-holder> - Quando há informação do detentor

  8. Conformidade com Critérios SciELO Brasil:

    • Seção 2.3: Ciência Aberta
    • Seção 5.2.4: Qualificação editorial
    • Seção 5.2.10.1: Interoperabilidade

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

# Regra Nível Descrição
1 Validar presença de <permissions> CRITICAL O elemento <permissions> é obrigatório em <article-meta> (Critério SciELO Brasil)
2 Validar unicidade de <permissions> ERROR O elemento <permissions> deve aparecer exatamente uma vez em <article-meta>
3 Validar presença de <license> CRITICAL O elemento <license> é obrigatório em <permissions>
4 Validar presença de @license-type="open-access" CRITICAL O atributo @license-type com valor "open-access" é obrigatório em <license>
5 Validar presença de @xlink:href CRITICAL O atributo @xlink:href é obrigatório em <license>
6 Validar presença de @xml:lang CRITICAL O atributo @xml:lang é obrigatório em <license>
7 Validar presença de <license-p> CRITICAL O elemento <license-p> é obrigatório em <license>
8 Validar URL de licença CC-BY ERROR O @xlink:href deve ser um link válido de Creative Commons CC-BY 4.0

P1 – Importantes (implementar se possível)

# Regra Nível Descrição
9 Validar consistência @xml:lang e @xlink:href ERROR O idioma em @xml:lang deve corresponder ao idioma no link @xlink:href (pt→deed.pt, en→deed.en, es→deed.es)
10 Validar estrutura de copyright quando presente WARNING Se houver <copyright-statement>, validar presença de <copyright-year> quando ano estiver mencionado no statement

P2 – Futuras (fora do escopo deste Issue)

# Regra Motivo de exclusão
11 Validar sincronização de texto <license-p> com PDF Alta complexidade - requer análise de PDF externo
12 Validar formato de ano em <copyright-year> Baixa prioridade - schema JATS já valida

Arquivos a Criar/Modificar

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

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

Criar (se não existirem):

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

Referenciar (implementações similares):

  • packtools/sps/validation/journal_meta.py – Validação de unicidade e presença
  • packtools/sps/validation/ext_link.py – Validação de URLs
  • packtools/sps/validation/utils.py – Funções auxiliares (build_response)

Exemplos de XML

XML Válido (deve passar sem erros):

<!-- Exemplo 1: Licença CC-BY em inglês sem copyright -->
<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.en" 
                 xml:lang="en">
            <license-p>This is an open-access article distributed under the terms of the Creative Commons Attribution License</license-p>
        </license>
    </permissions>
</article-meta>

<!-- Exemplo 2: Licença CC-BY em português sem copyright -->
<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.pt" 
                 xml:lang="pt">
            <license-p>Este é um artigo de acesso aberto distribuído sob os termos da Licença Creative Commons Atribuição</license-p>
        </license>
    </permissions>
</article-meta>

<!-- Exemplo 3: Licença CC-BY em espanhol sem copyright -->
<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.es" 
                 xml:lang="es">
            <license-p>Este es un artículo de acceso abierto distribuido bajo los términos de la Licencia Creative Commons Atribución</license-p>
        </license>
    </permissions>
</article-meta>

<!-- Exemplo 4: Licença com copyright completo (ano e detentor) -->
<article-meta>
    <permissions>
        <copyright-statement>Copyright © 2025, the authors</copyright-statement>
        <copyright-year>2025</copyright-year>
        <copyright-holder>the authors</copyright-holder>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.en" 
                 xml:lang="en">
            <license-p>This is an open-access article distributed under the terms of the Creative Commons Attribution License</license-p>
        </license>
    </permissions>
</article-meta>

<!-- Exemplo 5: Licença com copyright apenas ano -->
<article-meta>
    <permissions>
        <copyright-statement>Copyright © 2025</copyright-statement>
        <copyright-year>2025</copyright-year>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.en" 
                 xml:lang="en">
            <license-p>This is an open-access article distributed under the terms of the Creative Commons Attribution License</license-p>
        </license>
    </permissions>
</article-meta>

<!-- Exemplo 6: Link com versão específica (4.0) -->
<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/" 
                 xml:lang="en">
            <license-p>This is an open-access article distributed under the terms of the Creative Commons Attribution License</license-p>
        </license>
    </permissions>
</article-meta>

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

<article-meta>
    <!-- sem permissions -->
</article-meta>

Erro esperado: Elemento <permissions> é obrigatório em <article-meta> conforme Critérios SciELO Brasil

XML Inválido – Caso 2: Múltiplos (ERROR)

<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.en" 
                 xml:lang="en">
            <license-p>License text</license-p>
        </license>
    </permissions>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.pt" 
                 xml:lang="pt">
            <license-p>Texto da licença</license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: Elemento <permissions> deve aparecer exatamente uma vez em <article-meta>

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

<article-meta>
    <permissions>
        <copyright-statement>Copyright © 2025</copyright-statement>
    </permissions>
</article-meta>

Erro esperado: Elemento <license> é obrigatório em <permissions>

XML Inválido – Caso 4: Sem @license-type (CRITICAL)

<article-meta>
    <permissions>
        <license xlink:href="https://creativecommons.org/licenses/by/4.0/deed.en" 
                 xml:lang="en">
            <license-p>License text</license-p>
        </license>
    </permissions>
</article-meta>

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

XML Inválido – Caso 5: @license-type com valor incorreto (CRITICAL)

<article-meta>
    <permissions>
        <license license-type="cc-by" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.en" 
                 xml:lang="en">
            <license-p>License text</license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: Valor de @license-type deve ser "open-access". Valor encontrado: "cc-by"

XML Inválido – Caso 6: Sem @xLink:href (CRITICAL)

<article-meta>
    <permissions>
        <license license-type="open-access" xml:lang="en">
            <license-p>License text</license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: Atributo @xlink:href é obrigatório em <license>

XML Inválido – Caso 7: Sem @xml:lang (CRITICAL)

<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.en">
            <license-p>License text</license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: Atributo @xml:lang é obrigatório em <license>

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

<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.en" 
                 xml:lang="en">
        </license>
    </permissions>
</article-meta>

Erro esperado: Elemento <license-p> é obrigatório em <license>

XML Inválido – Caso 9: URL não CC-BY (ERROR)

<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://www.example.com/license" 
                 xml:lang="en">
            <license-p>License text</license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: URL em @xlink:href deve ser link válido de Creative Commons CC-BY 4.0. Use formato: https://creativecommons.org/licenses/by/4.0/deed.{idioma}

XML Inválido – Caso 10: URL CC-NC (não CC-BY) (ERROR)

<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by-nc/4.0/deed.en" 
                 xml:lang="en">
            <license-p>License text</license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: SciELO Brasil requer licença CC-BY. Link encontrado aponta para CC-BY-NC. Use: https://creativecommons.org/licenses/by/4.0/deed.en

XML Inválido – Caso 11: Inconsistência idioma e link (ERROR)

<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.en" 
                 xml:lang="pt">
            <license-p>Texto da licença em português</license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: Inconsistência entre @xml:lang="pt" e link terminando em deed.en. Para português, use link terminando em deed.pt

XML Inválido – Caso 12: Inconsistência idioma e link (espanhol) (ERROR)

<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.pt" 
                 xml:lang="es">
            <license-p>Texto de licencia en español</license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: Inconsistência entre @xml:lang="es" e link terminando em deed.pt. Para espanhol, use link terminando em deed.es

XML Inválido – Caso 13: Atributos vazios (CRITICAL)

<article-meta>
    <permissions>
        <license license-type="" xlink:href="" xml:lang="">
            <license-p></license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: Atributos obrigatórios e elementos não podem estar vazios

XML Inválido – Caso 14: URL CC-BY versão antiga (WARNING)

<article-meta>
    <permissions>
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/3.0/deed.en" 
                 xml:lang="en">
            <license-p>License text</license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: (WARNING) Recomenda-se usar Creative Commons CC-BY versão 4.0. Link encontrado aponta para versão 3.0

XML Inválido – Caso 15: com ano mas sem (WARNING)

<article-meta>
    <permissions>
        <copyright-statement>Copyright © 2025, the authors</copyright-statement>
        <!-- falta copyright-year -->
        <license license-type="open-access" 
                 xlink:href="https://creativecommons.org/licenses/by/4.0/deed.en" 
                 xml:lang="en">
            <license-p>License text</license-p>
        </license>
    </permissions>
</article-meta>

Erro esperado: (WARNING) <copyright-statement> menciona ano (2025). Adicione elemento <copyright-year> com o ano.

Padrão de Implementação

Diretrizes Gerais:

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

    • Consultar implementações similares como journal_meta.py (validação de unicidade)
    • Usar estrutura de classes já estabelecida no packtools
    • IMPORTANTE: Verificar se já existem validações parciais para <permissions> 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 <copyright-year> só se aplica se houver <copyright-statement>
    • 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 dicionário com dados de <permissions>
    • Dict deve conter: has_permissions, license_type, xlink_href, xml_lang, license_p, copyright_statement, copyright_year, copyright_holder, parent, parent_id, parent_lang

  6. Validação de URL CC-BY:

    • Verificar se URL contém creativecommons.org/licenses/by/
    • Detectar versão da licença (4.0 recomendado)
    • Alertar sobre CC-BY-NC, CC-BY-SA, CC-BY-ND (não permitidos para SciELO Brasil)

  7. Validação de consistência idioma-link:

    • Mapeamento:
      • pt → link deve terminar com deed.pt
      • en → link deve terminar com deed.en
      • es → link deve terminar com deed.es
    • Extrair sufixo do link e comparar com @xml:lang

  8. Detecção de ano em copyright-statement:

    • Usar regex para detectar padrões de ano: \d{4}, ©\s*\d{4}, etc.
    • Se ano detectado, verificar presença de <copyright-year>

Testes Esperados

Casos de teste obrigatórios:

Presença e unicidade:

  • Um <permissions> em <article-meta> (OK)
  • Sem <permissions> em <article-meta> (CRITICAL)
  • Múltiplos <permissions> em <article-meta> (ERROR)

Elemento :

  • <permissions> com <license> (OK)
  • <permissions> sem <license> (CRITICAL)

Atributos obrigatórios:

  • <license> com todos os atributos obrigatórios (OK)
  • Sem @license-type (CRITICAL)
  • Sem @xlink:href (CRITICAL)
  • Sem @xml:lang (CRITICAL)
  • Atributos vazios (CRITICAL)
  • Atributos apenas com espaços (CRITICAL)

Valor de @license-type:

  • @license-type="open-access" (OK)
  • @license-type="cc-by" (CRITICAL - valor incorreto)
  • @license-type="Open-Access" (CRITICAL - case-sensitive)

Elemento :

  • <license> com <license-p> (OK)
  • <license> sem <license-p> (CRITICAL)
  • <license-p> vazio (CRITICAL)
  • <license-p> apenas espaços (CRITICAL)

URLs de licença CC-BY:

  • URL CC-BY 4.0 português deed.pt (OK)
  • URL CC-BY 4.0 inglês deed.en (OK)
  • URL CC-BY 4.0 espanhol deed.es (OK)
  • URL CC-BY 4.0 sem sufixo de idioma (OK - aceitar)
  • URL CC-BY 3.0 (WARNING - versão antiga)
  • URL CC-BY-NC (ERROR - não permitido)
  • URL CC-BY-SA (ERROR - não permitido)
  • URL CC-BY-ND (ERROR - não permitido)
  • URL não Creative Commons (ERROR)
  • URL vazio (CRITICAL)

Consistência xml:lang e xlink:href:

  • pt + deed.pt (OK)
  • en + deed.en (OK)
  • es + deed.es (OK)
  • pt + deed.en (ERROR - inconsistente)
  • en + deed.pt (ERROR - inconsistente)
  • es + deed.en (ERROR - inconsistente)
  • fr + deed.fr (OK - permitir outros idiomas)

Elementos de copyright:

  • Com <copyright-statement> (OK)
  • Com <copyright-year> (OK)
  • Com <copyright-holder> (OK)
  • Todos os três elementos (OK)
  • Sem nenhum elemento de copyright (OK - opcional)

Validação condicional de copyright:

  • Statement com ano + <copyright-year> presente (OK)
  • Statement com ano + sem <copyright-year> (WARNING)
  • Statement sem ano mencionado (OK - year não obrigatório)

Casos de borda:

  • Link com ou sem barra final (OK - ambos válidos)
  • Link com https vs http (OK - aceitar ambos)
  • <license-p> com texto longo (OK)
  • Múltiplos <copyright-statement> (WARNING - duplicação)
  • Copyright statement em múltiplos idiomas (analisar contexto)

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 (presença, atributos, URLs, consistência, copyright)

Critérios de Aceite

O PR será aceito quando:

  • Verificação de validações existentes: Código existente para <permissions> foi analisado e integrado ou substituído adequadamente
  • Todas as regras P0 implementadas (8 validações CRITICAL/ERROR)
  • Todas as regras P1 implementadas (2 validações ERROR/WARNING)
  • Testes unitários passando com cobertura mínima de ~50 casos
  • Nenhum teste existente quebrado
  • Arquivo permissions_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 URLs CC-BY funcionando (detectando versão, tipo de licença)
  • Validação de consistência idioma-link funcionando
  • Validação condicional de copyright funcionando
  • Detecção de ano em copyright-statement via regex
  • Documentação inline clara (docstrings)

Referências

Documentação SPS:

Critérios SciELO Brasil:

Padrões JATS:

Creative Commons:

Referências internas packtools:

  • Internacionalização: Consultar conversas anteriores sobre implementação de i18n
  • Implementações similares: journal_meta.py (unicidade), ext_link.py (validação de URLs)
  • Funções auxiliares: utils.py (build_response)

Labels Sugeridas

enhancement validation SPS-1.10 scielo-brasil good-first-issue

Impacto Esperado

Antes:

  • Conformidade SPS 1.10 e Critérios SciELO Brasil para <permissions>: X% (verificar validações existentes)
  • Licenças podem estar ausentes
  • Atributos obrigatórios podem estar faltando
  • URLs de licenças não CC-BY podem passar
  • Inconsistências entre idioma e link não detectadas
  • Elementos de copyright podem estar incompletos

Depois:

  • Conformidade SPS 1.10 e Critérios SciELO Brasil para <permissions>: 75% (9 de 12 regras)
  • Validação CRITICAL de presença de <permissions> e <license>
  • Validação CRITICAL de atributos obrigatórios
  • Validação ERROR de URLs Creative Commons CC-BY válidas
  • Validação ERROR de consistência idioma-link
  • Validação WARNING de completude de copyright
  • ~50 testes unitários garantindo qualidade
  • Internacionalização completa (PT/EN/ES)

Benefícios:

  • Garante conformidade com política de Ciência Aberta SciELO
  • Assegura uso correto de licenças Creative Commons CC-BY
  • Detecta inconsistências de idioma antes da publicação
  • Previne uso de licenças não permitidas (CC-BY-NC, CC-BY-SA, etc.)
  • Melhora interoperabilidade com repositórios internacionais
  • Facilita coleta e indexação em bases de dados
  • Promove conformidade com Critérios SciELO Brasil
  • Garante clareza sobre direitos de uso e distribuição
  • 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