Understanding Temporal Expression components

Last updated: November 25, 2025

We strongly recommend getting started with our Temporal Expression AI generator to generate your first expressions. This will help provide a good understanding of what options to use, and when. This article

Introduction

Temporal expressions are a powerful way to describe when events should occur using a structured language. Instead of creating separate schedules for every possible time pattern, you can compose complex schedules from simple building blocks.

Think of temporal expressions like LEGO blocks - each piece has a specific purpose, and you can combine them in countless ways to create exactly the schedule you need.

Core Concepts

Time Ranges

All temporal expressions work with time ranges, not single points in time. Even when you specify "9 AM", the system understands this as "from 9:00:00 AM to 10:00:00 AM" (the full hour). This range-based approach makes it easy to combine and modify schedules.

End-Moment Non-Inclusive

When a time range goes "from 9 AM to 5 PM", it includes everything up to 5 PM but stops exactly at 5 PM (5 PM itself is not included). This prevents overlapping issues when schedules connect to each other.

Composition

You can build complex schedules by combining simpler ones. Want "weekday business hours excluding holidays"? Combine weekdays, business hours, and holiday exclusions into a single expression.

Basic Building Blocks (Primitive Expressions)

Time Units

YEAR - Matches entire years

  • Covers January 1st at midnight through December 31st at 11:59:59 PM

  • Example: "All of 2024" or "Every leap year"

MONTH - Matches specific months in every year

  • Covers the 1st at midnight through the last day at 11:59:59 PM

  • Example: "Every December" or "Summer months (June, July, August)"

DAY - Matches specific days of the month in every month

  • Covers midnight to 11:59:59 PM of that day

  • Example: "The 15th of every month" or "The 1st and 31st"

  • Note: Day 31 only matches in months that have 31 days

HOUR - Matches specific hours in every day

  • Covers the full 60-minute period

  • Uses 24-hour format (0-23)

  • Example: "9 AM" (hour 9) or "2 PM" (hour 14)

MINUTE - Matches specific minutes in every hour

  • Covers the full 60-second period

  • Example: "30 minutes past every hour" or "The top of every hour" (minute 0)

Day of Week Patterns

DAY_OF_WEEK - Matches specific days of the week

  • Covers midnight to midnight (full 24-hour period)

  • Uses three-letter codes: SUN, MON, TUE, WED, THU, FRI, SAT

  • Example: "Every Monday" or "Weekends" (Saturday and Sunday)

Week-Based Patterns

WEEK_OF_MONTH - Matches specific weeks within each month

  • Week 1 is the first week of the month, Week 5 handles longer months

  • You can specify which day starts the week (defaults to Monday)

  • Example: "First week of every month" or "Third week starting on Sunday"

WEEK_OF_YEAR - Matches specific weeks within each year

  • Uses ISO 8601 standard (Week 1 has at least 4 days in the new year)

  • Weeks run Monday through Sunday

  • Example: "Week 20 of every year" or "The last week of the year"

LAST_WEEK_OF_MONTH - Always matches the final week of each month

  • Automatically adjusts for months of different lengths

  • Example: "Last week of every month for month-end processing"

LAST_WEEK_OF_YEAR - Always matches the final week of each year

  • Handles years with 52 or 53 weeks

  • Example: "Year-end holiday period"

Special Days

LAST_DAY_OF_MONTH - Always matches the final day of each month

  • Automatically handles February (28 or 29 days), 30-day months, and 31-day months

  • Example: "Month-end billing" or "Final day for submissions"

EASTER - Matches Easter Sunday each year

  • Automatically calculates the correct date using lunar calendar rules

  • Example: "Easter holiday scheduling" or "Spring religious observances"

Exact Dates and Times

ISO_ON - Matches a specific calendar date

  • Uses YYYY-MM-DD format

  • Example: "New Year's Day 2024" (2024-01-01) or "Independence Day 2025" (2025-07-04)

ISO_RANGE - Matches time ranges within a day

  • Uses HH:MM:SS format for start and end times

  • Example: "Business hours" (09:00:00 to 17:00:00) or "Lunch break" (12:00:00 to 13:00:00)

  • Can span midnight: "Night shift" (23:00:00 to 07:00:00)

References

REFERENCE - Points to another saved expression

  • Lets you reuse complex expressions without rebuilding them

  • Example: Reference "company_holidays" or "trading_hours"

Combining Expressions (Composite Operations)

Set Operations

UNION - Combines multiple time ranges ("OR" logic)

  • Results in time that matches ANY of the child expressions

  • Example: "Weekends OR holidays" or "Morning rush OR evening rush"

INTERSECTION - Finds overlapping time ranges ("AND" logic)

  • Results in time that matches ALL of the child expressions

  • Example: "Weekdays AND business hours" or "December AND Mondays"

DIFFERENCE - Subtracts time ranges ("AND NOT" logic)

  • Takes the first expression and removes any time that matches the others

  • Example: "Weekdays minus holidays" or "Business hours except lunch break"

COMPLEMENT - Everything EXCEPT the specified time ranges ("NOT" logic)

  • Results in all time that does NOT match the child expressions

  • Scope depends on what you're complementing (complement of hours stays within each day)

  • Example: "All time except weekends" or "Non-business hours"

Time Boundaries

BEFORE - All time before the specified expressions

  • Creates an upper time boundary

  • Scope depends on what you're using (before a specific day affects that month)

  • Example: "Everything before 9 AM" or "All dates before project deadline"

AFTER - All time after the specified expressions

  • Creates a lower time boundary

  • Scope depends on what you're using (after a specific hour affects that day)

  • Example: "Everything after 5 PM" or "All dates after project start"

ENVELOPE - The broadest possible time range spanning multiple expressions

  • Finds the earliest start and latest end across all child expressions

  • Creates one continuous time range covering everything

  • Example: "Entire conference period" (from first session start to last session end)

Time Shifting

OFFSET - Shifts expressions forward or backward in time

  • Moves time ranges by specified amounts (days, hours, months, etc.)

  • Use positive numbers to shift forward, negative to shift backward

  • Example: "Day after each holiday" (+1 day) or "Two hours before each meeting" (-2 hours)

Repetition

RECURRENCE - Repeats a pattern at regular intervals

  • Takes a base pattern and repeats it according to a specified distance

  • Can be unlimited or limited to a specific count

  • Example: "Every Monday" (weekly recurrence) or "First of every month" (monthly recurrence)

Timezone Handling

TIMEZONE - Evaluates expressions in a specific timezone

  • Wraps other expressions and interprets them in the given timezone

  • Uses standard timezone identifiers like "America/New_York" or "Europe/London"

  • Example: "London business hours" or "Multi-timezone meeting coordination"

Building Complex Schedules

Common Patterns

Business Days Start with weekdays (Monday through Friday), then subtract holidays and company-specific days off.

Extended Hours Support Take regular business hours and add early morning or evening periods for urgent requests.

Seasonal Scheduling Combine specific months with day-of-week patterns for seasonal business patterns.

Holiday-Aware Scheduling Use regular patterns but exclude various holiday calendars (federal, religious, company-specific).

Multi-Location Coordination Use timezone expressions to coordinate schedules across different geographical locations.

Strategy for Complex Requirements

  1. Start Simple - Begin with the basic time pattern you want

  2. Add Constraints - Layer on additional requirements using intersections

  3. Handle Exceptions - Use difference operations to exclude unwanted times

  4. Consider Repetition - Use recurrence for ongoing patterns

  5. Test Edge Cases - Think about month boundaries, leap years, and timezone changes

Time Distance Specifications

When using OFFSET or RECURRENCE, you specify distances using combinations of:

  • years - For annual patterns or long-term shifts

  • months - For monthly cycles or seasonal adjustments

  • weeks - For weekly patterns or multi-week intervals

  • days - For daily patterns or simple date shifts

  • hours - For hourly patterns or time-of-day adjustments

  • minutes - For precise timing or short intervals

  • seconds - For very precise timing needs

You can combine these: "1 month and 2 days" or "2 hours and 30 minutes".

Best Practices

Design Principles

  • Start with the main pattern then add constraints and exceptions

  • Use descriptive IDs when saving expressions for later reference

  • Test your expressions with known dates to verify they work as expected

  • Keep expressions readable by breaking complex logic into referenced sub-expressions

Performance Considerations

  • Avoid overly deep nesting of composite expressions

  • Use references to share common patterns rather than duplicating them

  • Consider the scope of your expressions (yearly patterns vs. daily patterns)

Maintenance Tips

  • Document complex expressions with clear descriptions

  • Use consistent naming for referenced expressions

  • Version your expressions when making significant changes

  • Test after modifications to ensure behavior remains correct

This system gives you the flexibility to describe virtually any time pattern while keeping the individual pieces simple and understandable. Start with basic building blocks and gradually combine them to create exactly the schedule you need.