Date filters

DateRangeFilter

Filters by comparing a field to a range of date values.

Table

Filter schema

Property	Type	Description
operator	RangeOperators	The operator to apply to the filter value
value	range object	The value to use for the filter operation

Range object

Property	Type	Description
min	isoDate or utcDateTime	The minimum date value for this range
max	isoDate or utcDateTime	The maximum date value for this range

Formats

Example

A JSON example of this model.

{
  "operator": "between",
  "value": {
    "min": "2025-10-28",
    "max": "2025-10-28"
  }
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: DateRangeFilter.yaml
type: object
properties:
  operator:
    $ref: RangeOperators.yaml
    description: The operator to apply to the filter value
  value:
    type: object
    properties:
      min:
        anyOf:
          - $ref: isoDate.yaml
          - type: string
            format: date-time
          - type: string
            format: date-time
      max:
        anyOf:
          - $ref: isoDate.yaml
          - type: string
            format: date-time
          - type: string
            format: date-time
    required:
      - min
      - max
    unevaluatedProperties:
      not: {}
    examples:
      - min: 2021-01-01
        max: 2021-01-02
    description: The value to use for the filter operation
required:
  - operator
  - value
unevaluatedProperties:
  not: {}
description: Filters by comparing a field to a range of date values

TypeSpec

The TypeSpec code for this model.

/** Filters by comparing a field to a range of date values */
model DateRangeFilter {
  /** The operator to apply to the filter value */
  operator: RangeOperators;

  /** The value to use for the filter operation */
  @example(#{
    min: Types.isoDate.fromISO("2021-01-01"),
    max: Types.isoDate.fromISO("2021-01-02"),
  })
  value: {
    min: Types.isoDate | utcDateTime | offsetDateTime;
    max: Types.isoDate | utcDateTime | offsetDateTime;
  };
}

Python

The Python code for this model.

class DateRangeFilter(CommonGrantsBaseModel):
    """Filter that matches dates within a specified range."""

    operator: RangeOperator = Field(
        ...,
        description="The operator to apply to the filter value",
    )
    value: DateRange = Field(..., description="The date range value")

    @field_validator("operator", mode="before")
    @classmethod
    def validate_operator(cls, v):
        """Convert string to enum if needed."""
        if isinstance(v, str):
            return RangeOperator(v)
        return v

Changelog

Version	Changes
0.1.0	Added DateRangeFilter model

DateComparisonFilter

Filters by comparing a field to a date value.

Table

Property	Type	Description
operator	ComparisonOperators	The operator to apply to the filter value
value	isoDate or utcDateTime	The value to use for the filter operation

Formats

Example

A JSON example of this model.

{
  "operator": "gt",
  "value": "2025-10-28"
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: DateComparisonFilter.yaml
type: object
properties:
  operator:
    $ref: ComparisonOperators.yaml
    description: The operator to apply to the filter value
  value:
    anyOf:
      - $ref: isoDate.yaml
      - type: string
        format: date-time
      - type: string
        format: date-time
    examples:
      - 2021-01-01
    description: The value to use for the filter operation
required:
  - operator
  - value
unevaluatedProperties:
  not: {}
description: Filters by comparing a field to a date value

TypeSpec

The TypeSpec code for this model.

/** Filters by comparing a field to a date value */
model DateComparisonFilter {
  /** The operator to apply to the filter value */
  operator: ComparisonOperators;

  /** The value to use for the filter operation */
  @example(Types.isoDate.fromISO("2021-01-01"))
  value: Types.isoDate | utcDateTime | offsetDateTime;
}

Python

The Python code for this model.

class DateComparisonFilter(CommonGrantsBaseModel):
    """Filter that matches dates against a specific value."""

    operator: ComparisonOperator = Field(
        ...,
        description="The operator to apply to the filter value",
    )
    value: ISODate = Field(..., description="The date value to compare against")

    @field_validator("operator", mode="before")
    @classmethod
    def validate_operator(cls, v):
        """Convert string to enum if needed."""
        if isinstance(v, str):
            return ComparisonOperator(v)
        return v

    @field_validator("value", mode="before")
    @classmethod
    def validate_date(cls, v):
        """Convert string to date if needed."""
        if isinstance(v, str):
            return date.fromisoformat(v)
        return v

Changelog

Version	Changes
0.1.0	Added DateComparisonFilter model