Skip to content

Criar validações para o elemento <pub-date> #1103

Open
#1139
Open
Criar validações para o elemento <pub-date>#1103
#1139
Assignees
robertatakenakaRossi-Lucianocopilot-swe-agent
@Rossi-Luciano

Description

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

Objetivo

Implementar validações para o elemento <pub-date> conforme a especificação SPS 1.10, aumentando a conformidade de X% para 75% (9 de 12 regras).

Nota: Algumas validações para <pub-date> 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 <pub-date> representa as datas de publicação do documento e do número/volume ao qual pertence. São obrigatórias duas datas distintas: uma para o documento (@date-type="pub") e outra para a coleção (@date-type="collection"). Validações corretas garantem presença de datas obrigatórias, formatos adequados, e conformidade com regras específicas para cada tipo de data.

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

Regras principais conforme SPS 1.10:

  1. Ocorrência:

    • <pub-date> deve aparecer uma ou mais vezes em <article-meta>

  2. Datas obrigatórias:

    • <pub-date publication-format="electronic" date-type="pub"> - Data de publicação do documento (obrigatório)
    • <pub-date publication-format="electronic" date-type="collection"> - Data do número/volume (obrigatório)

  3. Atributos obrigatórios:

    • @date-type (valores: pub, collection)
    • @publication-format="electronic" (obrigatório para ambas as datas)

  4. Elementos obrigatórios para date-type="pub":

    • <day> (obrigatório)
    • <month> (obrigatório)
    • <year> (obrigatório)

  5. Elementos para date-type="collection":

    • <year> (obrigatório)
    • <month> ou <season> (opcional, depende da periodicidade)
    • <day> não é permitido

  6. Formato obrigatório:

    • <day> e <month> devem ter dois dígitos: 01, 02, ..., 12

  7. Periodicidade e elementos:

    • Anual: apenas <year>
    • Mensal: <month> + <year>
    • Bimestral/Quadrimestral/etc: <season> + <year>

  8. Observações:

    • Datas pub podem usar 00 em day/month para preenchimento posterior
    • Datas collection devem seguir a periodicidade do periódico

Regras a Implementar

P0 – Críticas (implementar obrigatoriamente)

# Regra Nível Descrição
1 Validar presença de <pub-date date-type="pub"> CRITICAL O elemento <pub-date> com @date-type="pub" é obrigatório
2 Validar presença de <pub-date date-type="collection"> CRITICAL O elemento <pub-date> com @date-type="collection" é obrigatório
3 Validar presença de @publication-format="electronic" CRITICAL O atributo @publication-format="electronic" é obrigatório em todas as <pub-date>
4 Validar elementos obrigatórios em pub CRITICAL Para date-type="pub": <day>, <month> e <year> são obrigatórios
5 Validar presença de <year> em collection CRITICAL Para date-type="collection": <year> é obrigatório
6 Validar ausência de <day> em collection ERROR Para date-type="collection": <day> não é permitido
7 Validar formato de dois dígitos para <day> e <month> ERROR Elementos <day> e <month> devem ter exatamente dois dígitos (01-31, 01-12)

P1 – Importantes (implementar se possível)

# Regra Nível Descrição
8 Validar unicidade de tipos de data ERROR Deve haver exatamente um <pub-date> com date-type="pub" e um com date-type="collection"
9 Validar valores numéricos válidos ERROR Valores de <day> devem estar entre 01-31, <month> entre 01-12

P2 – Futuras (fora do escopo deste Issue)

# Regra Motivo de exclusão
10 Validar data válida (dia/mês/ano formam data real) Média complexidade - requer validação de calendário
11 Validar consistência de periodicidade com uso de month/season Alta complexidade - requer conhecimento da periodicidade do periódico
12 Validar que data de pub é posterior ou igual a data de collection Baixa prioridade - lógica de negócio complexa

Arquivos a Criar/Modificar

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

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

Criar (se não existirem):

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

Referenciar (implementações similares):

  • packtools/sps/validation/history.py – Validação de datas similar (day/month/year)
  • packtools/sps/validation/utils.py – Funções auxiliares (build_response)

Exemplos de XML

XML Válido (deve passar sem erros):

<!-- Exemplo 1: Periódico anual -->
<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

<!-- Exemplo 2: Periódico mensal -->
<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <month>01</month>
        <year>2025</year>
    </pub-date>
</article-meta>

<!-- Exemplo 3: Periódico bimestral (com season) -->
<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <season>Jan-Feb</season>
        <year>2025</year>
    </pub-date>
</article-meta>

<!-- Exemplo 4: Data com dia e mês com dois dígitos -->
<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>15</day>
        <month>03</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <month>03</month>
        <year>2025</year>
    </pub-date>
</article-meta>

<!-- Exemplo 5: Data pub com 00 (placeholder para preenchimento posterior) -->
<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>00</day>
        <month>00</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <month>03</month>
        <year>2025</year>
    </pub-date>
</article-meta>

<!-- Exemplo 6: Periódico trimestral -->
<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>03</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <season>Jan-Mar</season>
        <year>2025</year>
    </pub-date>
</article-meta>

XML Inválido – Caso 1: Sem pub-date type="pub" (CRITICAL)

<article-meta>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Elemento <pub-date> com @date-type="pub" é obrigatório

XML Inválido – Caso 2: Sem pub-date type="collection" (CRITICAL)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Elemento <pub-date> com @date-type="collection" é obrigatório

XML Inválido – Caso 3: Sem @publication-format (CRITICAL)

<article-meta>
    <pub-date date-type="pub">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Atributo @publication-format é obrigatório em <pub-date>

XML Inválido – Caso 4: @publication-format com valor incorreto (CRITICAL)

<article-meta>
    <pub-date publication-format="print" date-type="pub">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Valor de @publication-format deve ser "electronic". Valor encontrado: "print"

XML Inválido – Caso 5: pub sem (CRITICAL)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Para @date-type="pub", elemento <day> é obrigatório

XML Inválido – Caso 6: pub sem (CRITICAL)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Para @date-type="pub", elemento <month> é obrigatório

XML Inválido – Caso 7: pub sem (CRITICAL)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>01</month>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Para @date-type="pub", elemento <year> é obrigatório

XML Inválido – Caso 8: collection sem (CRITICAL)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <month>03</month>
    </pub-date>
</article-meta>

Erro esperado: Para @date-type="collection", elemento <year> é obrigatório

XML Inválido – Caso 9: collection com (ERROR)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <day>01</day>
        <month>03</month>
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Para @date-type="collection", elemento <day> não é permitido

XML Inválido – Caso 10: com um dígito (ERROR)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>1</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Elemento <day> deve ter dois dígitos (use 01 ao invés de 1)

XML Inválido – Caso 11: com um dígito (ERROR)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>3</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Elemento <month> deve ter dois dígitos (use 03 ao invés de 3)

XML Inválido – Caso 12: Múltiplos pub-date type="pub" (ERROR)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="pub">
        <day>15</day>
        <month>02</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Deve haver exatamente um <pub-date> com @date-type="pub". Encontrados: 2

XML Inválido – Caso 13: Múltiplos pub-date type="collection" (ERROR)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Deve haver exatamente um <pub-date> com @date-type="collection". Encontrados: 2

XML Inválido – Caso 14: Mês inválido (13) (ERROR)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>01</day>
        <month>13</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Valor de <month> inválido: 13 (deve estar entre 01 e 12)

XML Inválido – Caso 15: Dia inválido (32) (ERROR)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day>32</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

Erro esperado: Valor de <day> inválido: 32 (deve estar entre 01 e 31)

XML Inválido – Caso 16: Elementos vazios (CRITICAL)

<article-meta>
    <pub-date publication-format="electronic" date-type="pub">
        <day></day>
        <month></month>
        <year></year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year></year>
    </pub-date>
</article-meta>

Erro esperado: Elementos de data não podem estar vazios

XML Inválido – Caso 17: Sem @date-type (CRITICAL)

<article-meta>
    <pub-date publication-format="electronic">
        <day>01</day>
        <month>01</month>
        <year>2025</year>
    </pub-date>
    <pub-date publication-format="electronic" date-type="collection">
        <year>2025</year>
    </pub-date>
</article-meta>

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

Padrão de Implementação

Diretrizes Gerais:

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

    • Consultar implementações similares como history.py (validação de datas)
    • Usar estrutura de classes já estabelecida no packtools
    • IMPORTANTE: Verificar se já existem validações parciais para <pub-date> 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 elementos obrigatórios só se aplica para tipos específicos de data
    • Exemplo: validação de <day> proibido só para collection
    • 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 <pub-date>)
    • Cada dict deve conter: date_type, publication_format, day, month, year, season, parent, parent_id, parent_lang
    • Separar datas por tipo para facilitar validações

  6. Validação de presença:

    • Verificar se existe pelo menos um <pub-date date-type="pub">
    • Verificar se existe pelo menos um <pub-date date-type="collection">
    • Contar ocorrências de cada tipo

  7. Validação de formato de dois dígitos:

    • Verificar comprimento exato: len(day) == 2 e len(month) == 2
    • Validar que consiste apenas de dígitos: day.isdigit()
    • Aceitar 00 como valor válido (placeholder)

  8. Validação de valores numéricos:

    • Day: 00-31 (00 é válido, 01-31 são normais)
    • Month: 00-12 (00 é válido, 01-12 são normais)
    • Usar conversão para int após validar formato

  9. Validação específica por tipo:

    • Para pub: verificar presença de day, month, year
    • Para collection: verificar presença de year, ausência de day

Testes Esperados

Casos de teste obrigatórios:

Presença de datas obrigatórias:

  • Com pub e collection (OK)
  • Sem pub (CRITICAL)
  • Sem collection (CRITICAL)
  • Sem nenhuma <pub-date> (CRITICAL)

Atributo @date-type:

  • <pub-date> com @date-type="pub" (OK)
  • <pub-date> com @date-type="collection" (OK)
  • <pub-date> sem @date-type (CRITICAL)
  • @date-type vazio (CRITICAL)
  • @date-type com valor inválido (ERROR)

Atributo @publication-format:

  • @publication-format="electronic" (OK)
  • Sem @publication-format (CRITICAL)
  • @publication-format vazio (CRITICAL)
  • @publication-format="print" (CRITICAL - valor incorreto)
  • @publication-format="online" (CRITICAL - valor incorreto)

Elementos obrigatórios para pub:

  • pub com day, month, year (OK)
  • pub sem day (CRITICAL)
  • pub sem month (CRITICAL)
  • pub sem year (CRITICAL)

Elementos para collection:

  • collection com year (OK)
  • collection com month + year (OK)
  • collection com season + year (OK)
  • collection sem year (CRITICAL)
  • collection com day (ERROR - proibido)

Formato de dois dígitos:

  • day com dois dígitos 01 (OK)
  • day com dois dígitos 31 (OK)
  • day com um dígito 1 (ERROR)
  • day com três dígitos 001 (ERROR)
  • month com dois dígitos 01 (OK)
  • month com dois dígitos 12 (OK)
  • month com um dígito 3 (ERROR)
  • month com três dígitos 012 (ERROR)

Valores numéricos válidos:

  • day 01 (OK)
  • day 31 (OK)
  • day 00 (OK - placeholder)
  • day 32 (ERROR - inválido)
  • month 01 (OK)
  • month 12 (OK)
  • month 00 (OK - placeholder)
  • month 13 (ERROR - inválido)

Unicidade de tipos:

  • Um pub e um collection (OK)
  • Dois pub (ERROR)
  • Dois collection (ERROR)
  • Três ou mais do mesmo tipo (ERROR)

Periodicidades diferentes:

  • Anual: collection com apenas year (OK)
  • Mensal: collection com month + year (OK)
  • Bimestral: collection com season + year (OK)
  • Trimestral: collection com season + year (OK)

Casos de borda:

  • Elementos vazios (CRITICAL)
  • Elementos apenas com espaços (CRITICAL)
  • Valores não numéricos em day/month (ERROR)
  • Ano com 4 dígitos (OK)
  • Ano com 2 dígitos (WARNING - formato não padrão)
  • Season com formato livre (OK - texto livre)

Total esperado: ~60 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, elementos, formatos, unicidade)

Critérios de Aceite

O PR será aceito quando:

  • Verificação de validações existentes: Código existente para <pub-date> foi analisado e integrado ou substituído adequadamente
  • Todas as regras P0 implementadas (7 validações CRITICAL/ERROR)
  • Todas as regras P1 implementadas (2 validações ERROR)
  • Testes unitários passando com cobertura mínima de ~60 casos
  • Nenhum teste existente quebrado
  • Arquivo pub_date_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 presença de datas obrigatórias funcionando
  • Validação de formato de dois dígitos funcionando
  • Validação de valores numéricos funcionando
  • Validação de unicidade de tipos funcionando
  • Validação específica por tipo (pub vs collection) funcionando
  • 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: history.py (validação de datas similar)
  • 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 <pub-date>: X% (verificar validações existentes)
  • Datas obrigatórias podem estar ausentes
  • Atributos obrigatórios podem estar faltando
  • Elementos incorretos por tipo de data não detectados
  • Formatos inconsistentes (um vs dois dígitos) não detectados
  • Múltiplas datas do mesmo tipo não detectadas
  • <day> em collection pode passar sem erro

Depois:

  • Conformidade SPS 1.10 para <pub-date>: 75% (9 de 12 regras)
  • Validação CRITICAL de presença de datas obrigatórias (pub e collection)
  • Validação CRITICAL de atributos obrigatórios
  • Validação CRITICAL de elementos obrigatórios por tipo
  • Validação ERROR de formato de dois dígitos
  • Validação ERROR de valores numéricos válidos
  • Validação ERROR de unicidade de tipos
  • Validação ERROR de proibição de <day> em collection
  • ~60 testes unitários garantindo qualidade
  • Internacionalização completa (PT/EN/ES)

Benefícios:

  • Melhora a qualidade dos XMLs SciELO
  • Garante presença de informações temporais essenciais
  • Detecta inconsistências de formato antes da publicação
  • Previne uso incorreto de elementos por tipo de data
  • Facilita processamento automatizado de datas
  • Melhora precisão de metadados temporais
  • Garante conformidade com padrões SPS
  • Facilita indexação e ordenação temporal
  • 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.

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