# Supported Validation Parameters for needle.Field: Complete Reference Guide

> Discover all 16 supported validation parameters for needle.Field in this comprehensive guide. Learn about numeric bounds, string constraints, array limits, and value restrictions for AI tool argument validation.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: api-reference
- Published: 2026-09-08

---

**The `needle.Field` class supports 16 validation parameters—including numeric bounds (`ge`, `le`, `gt`, `lt`), string constraints (`pattern`, `format`), array limits (`min_items`, `unique_items`), and value restrictions (`enum`, `const`)—that automatically map to JSON-Schema keywords for AI tool argument validation.**

The `needle.Field` class in the **cactus-compute/needle** repository provides a lightweight mechanism for enriching Python type hints with validation rules that become enforceable JSON-Schema constraints. Understanding these supported validation parameters for `needle.Field` allows developers to define precise boundaries for tool arguments consumed by large language models.

## Complete List of Validation Parameters

The `Field` constructor in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) accepts keyword arguments that populate the generated schema during the `apply()` method. These parameters fall into five distinct categories based on their JSON-Schema mappings.

### Numeric Constraints

These parameters validate integer and float values by translating to boundary keywords:

- **`ge`** – Greater than or equal to; maps to `minimum` (inclusive)
- **`le`** – Less than or equal to; maps to `maximum` (inclusive)
- **`gt`** – Greater than; maps to `exclusiveMinimum`
- **`lt`** – Less than; maps to `exclusiveMaximum`
- **`multiple_of`** – Value must be divisible by this number; maps to `multipleOf`

### String Constraints

Use these parameters to enforce text length, patterns, and formats:

- **`min_length`** – Minimum character count; maps to `minLength`
- **`max_length`** – Maximum character count; maps to `maxLength`
- **`pattern`** – Regular expression the string must match; maps to `pattern`
- **`format`** – Semantic format hint (e.g., `email`, `date-time`, `uri`); maps to `format`

### Array Constraints

When the annotated type is a list, these parameters control collection properties:

- **`min_items`** – Minimum number of elements; maps to `minItems`
- **`max_items`** – Maximum number of elements; maps to `maxItems`
- **`unique_items`** – Requires all array elements to be distinct; maps to `uniqueItems`

### Value Restrictions

These parameters constrain the specific values a field may accept:

- **`enum`** – List of allowed values; maps to `enum` (automatically converted to a list by `Field.apply()`)
- **`const`** – Fixed constant value the field must equal; maps to `const`

### Metadata Fields

- **`description`** – Human-readable documentation string copied into the schema's `description` field
- **`default`** – Default value used by Needle at call time; **not** included in the JSON-Schema validation logic

## How Validations Map to JSON-Schema

According to the **cactus-compute/needle** source code, the `Field` class stores these parameters as instance attributes and applies them inside the `apply()` method at lines 18-49 of [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py). The implementation iterates through the validation parameters, filters out `None` values, and constructs a dictionary where Python parameter names map directly to their JSON-Schema equivalents.

For example, when you pass `ge=15` to a `Field`, the generated schema contains `"minimum": 15`. The method handles special cases like `enum` by ensuring it is serialized as a JSON array regardless of the input type.

## Practical Usage Examples

### Enforcing Numeric Ranges with Inclusive Bounds

Use `ge` and `le` to define acceptable ranges for thermostat-style controls:

```python
from needle.agent.tools import Field, tool

@tool
def set_temperature(
    value: int = Field(ge=15, le=30, description="Target temperature in °C")
):
    """Set the thermostat to a specific temperature."""
    pass

```

This generates the following schema fragment:

```json
{
  "type": "integer",
  "minimum": 15,
  "maximum": 30,
  "description": "Target temperature in °C"
}

```

### Validating String Patterns and Allowed Values

Combine `enum` with `pattern` to restrict inputs to specific lowercase color names:

```python
@tool
def choose_color(
    color: str = Field(
        enum=["red", "green", "blue"],
        pattern="^[a-z]+$",
        description="Pick a primary color"
    )
):
    """Select a color from the allowed list."""
    pass

```

Resulting schema:

```json
{
  "type": "string",
  "enum": ["red", "green", "blue"],
  "pattern": "^[a-z]+$",
  "description": "Pick a primary color"
}

```

### Constraining Array Contents

Use `min_items`, `max_items`, and `unique_items` to validate tag collections:

```python
@tool
def add_tags(
    tags: list = Field(
        min_items=1,
        max_items=5,
        unique_items=True,
        description="List of unique tags"
    )
):
    """Add between 1 and 5 unique tags to an item."""
    pass

```

Generated schema:

```json
{
  "type": "array",
  "items": {"type": "string"},
  "minItems": 1,
  "maxItems": 5,
  "uniqueItems": true,
  "description": "List of unique tags"
}

```

## Summary

- **`needle.Field`** supports **16 validation parameters** spanning numeric, string, array, and value constraints.
- Parameters map **directly to JSON-Schema keywords** inside `Field.apply()` at lines 18-49 of [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py).
- **Numeric bounds** use `ge`, `le`, `gt`, `lt`, and `multiple_of` for range validation.
- **String validation** employs `min_length`, `max_length`, `pattern`, and `format` for text constraints.
- **Array controls** include `min_items`, `max_items`, and `unique_items` for collection validation.
- **`enum`** and **`const`** restrict values to specific allowed sets or fixed constants.
- The **`default`** parameter is handled at runtime by Needle, not exposed in the JSON-Schema.

## Frequently Asked Questions

### What is needle.Field used for in the Needle SDK?

The `needle.Field` class annotates Python function parameters with validation metadata that the Needle SDK converts into OpenAI-compatible JSON-Schema definitions. This allows language models to understand constraints like minimum values or allowed enums before generating tool calls.

### How does needle.Field differ from Pydantic's Field?

While Pydantic's `Field` is tightly coupled to Pydantic model validation, `needle.Field` in **cactus-compute/needle** is a lightweight helper specifically designed for generating function schemas for AI agents. It focuses exclusively on JSON-Schema generation rather than runtime Python validation.

### Where are validation parameters applied in the source code?

Validation parameters are processed in the `Field.apply()` method located at lines 18-49 of [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py). This method builds the schema dictionary by mapping Python parameter names to their JSON-Schema equivalents and injecting non-`None` values.

### Can I combine multiple validation parameters in a single Field definition?

Yes. You can combine any compatible parameters (e.g., `ge` with `le`, or `pattern` with `min_length`) within a single `Field()` call. The `apply()` method aggregates all provided constraints into a single comprehensive JSON-Schema object.