Numeric filters

NumberComparisonFilter

Filters by comparing a field to a numeric value.

Table

Property	Type	Description
operator	ComparisonOperators	The operator to apply to the filter value
value	numeric	The value to use for the filter operation

Formats

Example

A JSON example of this model.

{
  "operator": "gt",
  "value": 1000
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: NumberComparisonFilter.yaml
type: object
properties:
  operator:
    anyOf:
      - $ref: ComparisonOperators.yaml
      - $ref: EquivalenceOperators.yaml
    description: The comparison operator to apply to the filter value
  value:
    type: number
    examples:
      - 1000
    description: The value to use for the filter operation
required:
  - operator
  - value
unevaluatedProperties:
  not: {}
description: Filters by comparing a field to a numeric value

TypeSpec

The TypeSpec code for this model.

/** Filters by comparing a field to a numeric value */
@Versioning.added(CommonGrants.Versions.v0_1)
model NumberComparisonFilter {
  /** The comparison operator to apply to the filter value */
  @Versioning.typeChangedFrom(CommonGrants.Versions.v0_3, ComparisonOperators)
  operator: ComparisonOperators | EquivalenceOperators;

  /** The value to use for the filter operation */
  @example(1000)
  value: numeric;
}

Python

The Python code for this model.

    ``z.number()`` rejects booleans, so rejection keeps the SDKs aligned.
    """
    if isinstance(v, bool):
        raise ValueError("value must be a number, not a bool")
    return v


class NumberRange(CommonGrantsBaseModel):
    """Represents a range between two numeric values."""

TypeScript

The TypeScript code for this model.

export const NumberComparisonFilterSchema = z.object({
  operator: z.union([ComparisonOperatorsEnum, EquivalenceOperatorsEnum]),
  value: z.number(),
});

Changelog

Version	Changes	Schema
0.1.0	Added NumberComparisonFilter model	NumberComparisonFilter.yaml

NumberRangeFilter

Filters by comparing a field to a range of numeric 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	numeric	The minimum numeric value for this range
max	numeric	The maximum numeric value for this range

Formats

Example

A JSON example of this model.

{
  "operator": "between",
  "value": {
    "min": 1000,
    "max": 10000
  }
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: NumberRangeFilter.yaml
type: object
properties:
  operator:
    $ref: RangeOperators.yaml
    description: The operator to apply to the filter value
  value:
    type: object
    properties:
      min:
        type: number
      max:
        type: number
    required:
      - min
      - max
    unevaluatedProperties:
      not: {}
    examples:
      - min: 1000
        max: 10000
    description: The value to use for the filter operation
required:
  - operator
  - value
unevaluatedProperties:
  not: {}
description: Filters by comparing a field to a numeric range

TypeSpec

The TypeSpec code for this model.

/** Filters by comparing a field to a numeric range */
@Versioning.added(CommonGrants.Versions.v0_1)
model NumberRangeFilter {
  /** The operator to apply to the filter value */
  operator: RangeOperators;

  /** The value to use for the filter operation */
  @example(#{ min: 1000, max: 10000 })
  value: {
    min: numeric;
    max: numeric;
  };
}

Python

The Python code for this model.

class NumberComparisonFilter(CommonGrantsBaseModel):
    """Filter that matches numbers against a specific value.

    Accepts equivalence operators (``eq``/``neq``) in addition to comparison
    operators, per the core spec (filters/numeric.tsp, since protocol v0.3).
    """

    operator: ComparisonOperator | EquivalenceOperator = Field(
        ...,
        description="The comparison operator to apply to the filter value",
    )
    value: Union[int, float] = Field(
        ..., description="The numeric value to compare against"
    )

    @field_validator("operator", mode="before")

TypeScript

The TypeScript code for this model.

export const NumberRangeFilterSchema = z.object({
  operator: RangeOperatorsEnum,
  value: z.object({
    min: z.number(),
    max: z.number(),
  }),
});

Changelog

Version	Changes	Schema
0.1.0	Added NumberRangeFilter model	NumberRangeFilter.yaml

NumberArrayFilter

Filters by comparing a field to an array of numeric values.

Table

Property	Type	Description
operator	ArrayOperators	The operator to apply to the filter value
value	Array<numeric>	The value to use for the filter operation

Formats

Example

A JSON example of this model.

{
  "operator": "in",
  "value": [
    1000,
    2000,
    3000
  ]
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: NumberArrayFilter.yaml
type: object
properties:
  operator:
    $ref: ArrayOperators.yaml
    description: The operator to apply to the filter value
  value:
    type: array
    items:
      type: number
    examples:
      - - 1000
        - 2000
        - 3000
    description: The value to use for the filter operation
required:
  - operator
  - value
unevaluatedProperties:
  not: {}
description: Filters by comparing a field to an array of numeric values

TypeSpec

The TypeSpec code for this model.

/** Filters by comparing a field to an array of numeric values */
@Versioning.added(CommonGrants.Versions.v0_1)
model NumberArrayFilter {
  /** The operator to apply to the filter value */
  operator: ArrayOperators;

  /** The value to use for the filter operation */
  @example(#[1000, 2000, 3000])
  value: Array<numeric>;
}

Python

The Python code for this model.

        """Convert string to enum if needed."""
        if isinstance(v, str):
            if v in [op.value for op in ComparisonOperator]:
                return ComparisonOperator(v)
            elif v in [op.value for op in EquivalenceOperator]:
                return EquivalenceOperator(v)
        return v

    @field_validator("value", mode="before")
    @classmethod
    def reject_bool(cls, v):
        """Reject bool values (would lax-coerce to 1/0; see _ensure_not_bool)."""
        return _ensure_not_bool(v)


class NumberRangeFilter(CommonGrantsBaseModel):
    """Filter that matches numbers within a specified range."""

TypeScript

The TypeScript code for this model.

export const NumberArrayFilterSchema = z.object({
  operator: ArrayOperatorsEnum,
  value: z.array(z.number()),
});

Changelog

Version	Changes	Schema
0.1.0	Added NumberArrayFilter model	NumberArrayFilter.yaml