Criar validações para o elemento <permissions>

[Rossi-Luciano]

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:

• SPS 1.10 – <permissions>: Licença Creative Commons e Copyright

Critérios SciELO Brasil:

• Seção 2.3 – SciELO Brasil e Ciência Aberta
• Seção 5.2.4 – Relevância, sustentabilidade e qualificação editorial
• Seção 5.2.10.1 – Interoperabilidade

Padrões JATS:

• JATS 1.3 – <permissions>
• JATS 1.3 – <license>
• JATS 1.3 – <copyright-statement>
• JATS 1.3 – <copyright-year>
• JATS 1.3 – <copyright-holder>

Creative Commons:

• Creative Commons CC-BY 4.0
• CC License Chooser
• Download CC Logos

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

Observações importantes:

• Implementar internacionalização ajustando as respostas das validações ao formato da função build_response em packtools/sps/validation/utils.py;
• Verificar e adicionar as validações no orquestrador: packtools/sps/validation/xml_validations.py e packtools/sps/validation/xml_validator.py
• Verificar a corretude dos testes exsitentes para a validação e complementar caso necessário;
• Realizar ajustes, caso necessário, nos modelos que são utilizados pelas validações, garantindo que o ajuste não interfira em possíveis usos atuais desses modelos.