# Needle.Field Constraint Types: A Complete Guide to JSON-Schema Validation Parameters in Needle

> Explore 14 JSON-Schema constraint types in Needle Field including numeric bounds string validators array constraints and value restrictions Discover how to implement robust data validation.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: deep-dive
- Published: 2026-08-23

---

**`needle.Field` supports 14 JSON-Schema-based constraint types including numeric bounds (`ge`, `le`, `gt`, `lt`), string validators (`min_length`, `max_length`, `pattern`, `format`), array constraints (`min_items`, `max_items`, `unique_items`), and value restrictions (`enum`, `const`)**.

The `needle.Field` class provides a declarative way to attach validation constraints to function parameters when building AI tools with the **needle** library. When you use the `@tool` decorator, `Field` instances automatically translate into JSON Schema definitions that enforce type safety and input validation.

## What Constraint Types Are Supported by needle.Field

`needle.Field` accepts keyword arguments that map directly to JSON Schema validation keywords. The constructor is implemented in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) at lines 17-30, with schema generation handled by the `apply` method at lines 35-48.

### Value Metadata Constraints

These constraints control basic field properties and documentation:

- **`default`** — Fallback value used when the parameter is not supplied
- **`description`** — Human-readable explanation of the field's purpose
- **`enum`** — List of allowed literal values the parameter must match
- **`const`** — Single fixed value that the field must equal

These parameters appear in the `Field` constructor signature at [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) lines 17-18.

### Numeric Range Constraints

For `int` and `float` parameters, four bound types are available:

- **`ge`** — Inclusive minimum (≥), maps to JSON Schema `minimum`
- **`le`** — Inclusive maximum (≤), maps to JSON Schema `maximum`
- **`gt`** — Exclusive minimum (>), maps to JSON Schema `exclusiveMinimum`
- **`lt`** — Exclusive maximum (<), maps to JSON Schema `exclusiveMaximum`

You can combine inclusive and exclusive bounds as needed. The `multiple_of` constraint additionally requires values to be divisible by a specified number.

These numeric parameters are defined at [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) lines 19-21.

### String Validation Constraints

For `str` parameters, `Field` supports pattern and length validation:

- **`min_length`** — Minimum character count (inclusive)
- **`max_length`** — Maximum character count (inclusive)
- **`pattern`** — Regular expression the string must match
- **`format`** — JSON Schema format hint such as `"date-time"`, `"email"`, or `"uri"`

The string constraint implementation appears at [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) lines 28-30.

### Array/List Constraints

For collection types, three constraints control item count and uniqueness:

- **`min_items`** — Minimum number of elements in the array
- **`max_items`** — Maximum number of elements in the array
- **`unique_items`** — Boolean flag requiring all array elements to be distinct

These are also defined at [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) line 30.

## How needle.Field Translates Constraints to JSON Schema

The `apply` method at [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) lines 35-48 performs the conversion from `Field` parameters to JSON Schema keys. This transformation follows standard JSON Schema naming conventions:

| needle.Field Parameter | JSON Schema Output Key |
|------------------------|------------------------|
| `ge` | `minimum` |
| `le` | `maximum` |
| `gt` | `exclusiveMinimum` |
| `lt` | `exclusiveMaximum` |
| `multiple_of` | `multipleOf` |
| `min_length` | `minLength` |
| `max_length` | `maxLength` |
| `min_items` | `minItems` |
| `max_items` | `maxItems` |
| `unique_items` | `uniqueItems` |
| All others | Same name (e.g., `enum`, `const`, `pattern`, `format`) |

## Practical Code Examples

### Basic Parameter Validation with Default Values

```python
from needle import tool, Field

@tool
def generate(
    temperature: float = Field(default=0.7, ge=0, le=1, description="Sampling temperature"),
    max_tokens: int = Field(default=256, ge=1, le=1024),
    stop: str = Field(default=".", pattern=r"^\.$", description="Stop token")
):
    """Generate text using the model."""
    ...

```

This example demonstrates numeric bounds (`ge`, `le`) and regex pattern matching on the `needle.Field` parameters.

### Using typing.Annotated with Required Parameters

```python
from needle import tool, Field
from typing import Annotated

@tool
def classify(
    text: str,
    label: Annotated[str, Field(enum=["positive", "negative", "neutral"])]
):
    """Classify sentiment."""
    ...

```

When a parameter has no default value, wrap `Field` in `typing.Annotated` to attach constraints without providing a default.

### Array Validation Example

```python
from needle import tool, Field
from typing import Annotated, List

@tool
def process_tags(
    items: Annotated[List[str], Field(min_items=1, max_items=10, unique_items=True)]
):
    """Process a list of unique tags."""
    ...

```

## Complete Constraint Reference Table

| Constraint | Type | Applies To | JSON Schema Key |
|------------|------|------------|-----------------|
| `default` | Any | All types | Used at runtime, not in schema |
| `description` | `str` | All types | `description` |
| `enum` | `list` | All types | `enum` |
| `const` | Any | All types | `const` |
| `ge` | `float` / `int` | Numbers | `minimum` |
| `le` | `float` / `int` | Numbers | `maximum` |
| `gt` | `float` / `int` | Numbers | `exclusiveMinimum` |
| `lt` | `float` / `int` | Numbers | `exclusiveMaximum` |
| `multiple_of` | `float` / `int` | Numbers | `multipleOf` |
| `min_length` | `int` | Strings | `minLength` |
| `max_length` | `int` | Strings | `maxLength` |
| `pattern` | `str` | Strings | `pattern` |
| `format` | `str` | Strings | `format` |
| `min_items` | `int` | Arrays | `minItems` |
| `max_items` | `int` | Arrays | `maxItems` |
| `unique_items` | `bool` | Arrays | `uniqueItems` |

## Summary

- **`needle.Field` supports 14 constraint types** covering metadata, numeric bounds, string patterns, and array validation as defined in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py)
- **Constraints map directly to JSON Schema** via the `apply` method (lines 35-48), enabling automatic validation in AI tool interfaces
- **Two usage patterns exist**: as default values for optional parameters, or inside `typing.Annotated` for required parameters
- **All constraints are optional** — use only those relevant to your parameter's expected input
- **Combine multiple constraints** freely, such as `ge` + `le` for inclusive ranges or `min_length` + `pattern` for string validation

## Frequently Asked Questions

### Can I use multiple range constraints together in a single needle.Field?

Yes. According to the [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py) implementation, you can combine `ge`/`le` for inclusive bounds or `gt`/`lt` for exclusive bounds, and even mix them (e.g., `gt=0` with `le=100`). The `apply` method processes each constraint independently and adds all valid keys to the generated JSON Schema.

### Does needle.Field validate inputs at runtime or just generate schema?

The validation behavior depends on the Needle tool-binding system consuming the schema. The `Field` class itself, as implemented in lines 17-30 of [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py), is purely declarative—it stores constraint values and generates JSON Schema via `apply`. Actual input validation occurs when the schema is used by the runtime system.

### What is the difference between enum and const constraints in needle.Field?

`enum` accepts a list of allowed values, restricting the parameter to any member of that set, while `const` enforces a single fixed value. In [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py), both appear as direct keyword parameters (lines 18-22) and pass through unchanged to the JSON Schema output. Use `enum` for categorical choices and `const` when the value must be invariant.