Validador de Cron Expression

Expressões cron: uma mini DSL para agendamento baseado em tempo

Cron e a língua franca dos jobs recorrentes no Unix. Uma expressão cron e uma string compacta com cinco (as vezes seis ou sete) campos separados por espaço que descreve "quando" algo deve rodar. O agendador — crond, timer do systemd, CronJob do Kubernetes, scheduler do GitHub Actions, Vercel Cron — desperta a cada minuto e dispara toda entrada cujo padrão bata com o relógio atual.

Apesar da simplicidade aparente, a sintaxe esta cheia de surpresas específicas de cada dialeto: dia da semana 0-indexado vs 1-indexado, operadores exclusivos do Quartz (L, W, #), lógica AND vs OR entre os campos de dia, e armadilhas de fuso horário. Este validador checa estrutura e ranges dos campos para você pegar erros de sintaxe antes de subir em produção.

O formato clássico Unix Vixie com 5 campos

O cron Vixie original, distribuido na maioria das distros Linux, usa cinco campos:

* * * * *  comando
| | | | |
| | | | +-- dia da semana (0-6, 0=Domingo; ou SUN-SAT)
| | | +---- mes           (1-12 ou JAN-DEC)
| | +------ dia do mes    (1-31)
| +-------- hora          (0-23)
+---------- minuto        (0-59)

Operadores dentro de um campo:

• * — qualquer valor.
• , — lista, ex.: 1,15,30.
• - — intervalo, ex.: 1-5.
• / — passo, ex.: */15 (a cada 15) ou 10-30/5.
• L, W, # — apenas no Quartz: último dia, dia útil mais próximo, n-esimo dia da semana do mês.

Exemplos comentados

• 0 9 * * 1-5 — todo dia útil as 09:00.
• */15 * * * * — a cada 15 minutos.
• 0 0 1 * * — todo dia 1 do mês a meia-noite.
• 30 2 * * 0 — todo domingo as 02:30.
• 0 12 1 1 * — meio-dia de 1 de janeiro.
• 0 0 * * 1#2 — segunda-feira da segunda semana do mês (Quartz).

Dialetos: Vixie, Quartz, AWS, Kubernetes, GitHub

Nem todo cron e o mesmo cron:

• Unix Vixie cron — 5 campos, dia da semana 0-6 (Domingo=0 ou 7).
• Quartz (Java) — 6 ou 7 campos: segundos minutos horas dom mes dow [ano], dia da semana 1-7 com Domingo=1. Suporta L (last), W (nearest weekday), # (n-esimo dia da semana).
• AWS EventBridge — 6 campos, inclui ano, exige ? em dom ou dow.
• Kubernetes CronJob — 5 campos puros, UTC por padrão; desde a 1.27 aceita timeZone na spec.
• GitHub Actions — 5 campos, somente UTC, intervalo mínimo de 5 minutos e disparos podem ser pulados sob carga.
• Vercel Cron — 5 campos, UTC, ressalvas semelhantes.

Armadilhas comuns: dia da semana e lógica dom+dow

Dois erros pegam quase todo dev:

• Domingo e 0 e também 7 no Vixie cron — aceito por compatibilidade com o cron original da AT&T. No Quartz Domingo e 1.
• dia do mês e dia da semana são ORed, não ANDed, quando ambos são especificados. 0 0 13 * 5 dispara em todo dia 13 e toda sexta — não "sexta-feira 13".
• Passo */0 e inválido; 0/15 e forma exclusiva do Quartz.
• Meses/dias da semana nomeados não são sensiveis a caixa, mas precisam ter três letras (JAN, MON).

O Brasil simplifica uma coisa: desde 2019 o pais aboliu o horário de verão, então um job agendado para 02:30 BRT não e pulado nem duplicado duas vezes por ano como aconteceria nos EUA ou na UE.

Ferramentas: validar, decodificar e prever próximos disparos

Bibliotecas e sites recomendados:

• crontab.guru — o decodificador visual canônico; cola uma expressão e mostra o significado em inglês.
• cronstrue (npm) — descrição legível por humano em vários idiomas.
• cron-validator, cron-parser (npm) — parse, validação e cálculo de próximos disparos em Node.
• Quartz (Java) — dialeto Quartz completo com CronExpression.
• croniter (Python) — iteracao compatível com Vixie das proximas execucoes.

FAQ

5 ou 6 campos — qual usar?

Agendadores de sabor Unix (Vixie, GitHub Actions, Kubernetes, Vercel) querem 5 campos. Quartz e AWS EventBridge usam 6+; so adote esse formato se o seu runner explicitamente suporta.

A relação entre dom e dow e AND ou OR?

OR. Quando ambos os campos são restringidos, o job dispara sempre que qualquer uma das condições bater. Para expressar "sexta-feira 13" você precisa restringir um deles e checar o outro dentro do job.

Como prever os próximos disparos antes de subir?

Cole a expressão no crontab.guru ou rode cron-parser em Node para enumerar os próximos N disparos. No GitHub Actions, dispare manualmente com o evento workflow_dispatch para testar.

Qual fuso horário e usado?

A maioria dos runners gerenciados (GitHub Actions, Vercel, AWS) executa em UTC. O crond Linux usa o fuso do sistema (/etc/localtime). Kubernetes 1.27+ suporta um campo explícito timeZone na spec do CronJob.

Por que meu cron no GitHub Actions atrasa as vezes?

O GitHub agenda workflows em best effort. Sob pico de carga, disparos podem atrasar vários minutos ou até ser pulados. Para timing rigoroso, use um agendador dedicado.