JSON Handling and Pydantic Models

A tool-calling pipeline handed json.loads a model response and got JSONDecodeError: Expecting ',' delimiter. The string looked like perfect JSON: the model had wrapped the object in a fenced code block labeled json and appended "Anything else?" after the closing brace. The parser was correct; the assumption that model text equals JSON was wrong.

What counts as acceptable — and what to do with the rest — gets decided at the boundary where a string becomes a record.

What raw output actually contains

Strip what is decoration, reject what is damage

import json, re

def extract_json(raw: str) -> dict:
    raw = raw.strip()
    fence = re.match(r"^```(?:json)?\s*(.*?)\s*```$", raw, re.DOTALL)
    if fence:
        raw = fence.group(1)                      # fences are decoration: safe to remove
    start, end = raw.find("{"), raw.rfind("}")
    if start == -1 or end == -1:
        raise ValueError("no JSON object in model output")
    return json.loads(raw[start:end + 1])         # prose outside the braces falls away

Input:

Here is the extraction:
```json
{"title": "Idempotency", "score": 0.92}
```
Hope that helps!

Output: {'title': 'Idempotency', 'score': 0.92}

Three decisions inside fifteen lines:

• The fence regex is anchored ^...$, so a code block inside the JSON cannot be mistaken for the wrapper.
• find/rfind bracket the object instead of trusting the whole string, so trailing chatter is excluded rather than fatal.
• Truncation still fails: on an unclosed object, raw[start:end + 1] raises JSONDecodeError. Returning {} would push the damage downstream, where the traceback lands on innocent code.

Parsing yields a dict. It says nothing about whether score is present, in range, or remotely the right type — and nothing yet stops a bad value from reaching arithmetic three frames later.

Once the string parses, the dict still carries no promises: keys may be missing, numbers may be strings, and nothing complains until round(score * 100) raises TypeError — far from the data that caused it. A model moves that complaint to the boundary where the data entered.

Declare the record once

from pydantic import BaseModel, ValidationError

class Summary(BaseModel):
    title: str
    score: float
    tags: list[str] = []          # a default makes the field optional, not absent-tolerant

good = Summary(title="Idempotency", score=0.92)
print(good.model_dump())

Output: {'title': 'Idempotency', 'score': 0.92, 'tags': []}

try:
    Summary(title="Idempotency", score="high")
except ValidationError as exc:
    print(exc)

Output:

1 validation error for Summary
score
  Input should be a valid number, unable to parse string as a number [type=float_parsing, input_value='high']

Read that block like a coordinate system:

• for Summary — which model rejected the data; matters the moment models nest.
• score — the exact field, as a path: items.0.price for lists inside models.
• type=float_parsing — machine-readable, so a test can assert on the kind of failure instead of message text that shifts between releases.

The comparison that makes the case

model_json_schema() emits JSON Schema — the same artifact you can pass to a model when requesting Schema-Constrained Generation, so the parser's expectations and the prompt's contract come from one declaration.

Two settings deserve a deliberate choice: model_config = ConfigDict(extra="forbid") turns an unexpected key into an error, and strict validation refuses conversions like "42" → 42 that the default lax mode accepts. Strict for types you control, lax where numbers arrive from forms and CSV cells as strings.

The schema stops type errors. It does not know that an email needs @, that priority has three legal values, or that a similarity above 1.0 means the embedding call misfired.

Types stop the obviously broken. They do not know that reporter must contain an @ or that a score outside [0, 1] means an upstream call went wrong. Checking those at each call site guarantees two sites eventually disagree; on the model, every consumer inherits one rule.

Rules declared next to the field

from enum import Enum
from pydantic import BaseModel, EmailStr, field_validator

class Priority(str, Enum):
    low = "low"
    high = "high"
    urgent = "urgent"

class Ticket(BaseModel):
    reporter: EmailStr
    priority: Priority
    score: float

    @field_validator("score")
    @classmethod
    def score_in_range(cls, v: float) -> float:
        if not 0.0 <= v <= 1.0:
            raise ValueError(f"score must be in [0, 1], got {v}")
        return v

Ticket(reporter="ada@example.com", priority="high", score=0.71)   # passes
Ticket(reporter="ada@example.com", priority="urgent", score=1.4)  # fails below

Output of the second call:

1 validation error for Ticket
score
  Value error, score must be in [0, 1], got 1.4 [type=value_error, input_value=1.4]

Three mechanisms, three jobs:

• EmailStr and Priority reuse rules that already exist. An Enum doubles as a type check: "URGENT" fails as a non-member, and ticket.priority.value serializes back to the wire string.
• @field_validator("score") runs after type coercion, so v arrives as a float and the range check never parses anything. Reach for mode="before" only when the raw input must be reshaped first.
• Raising ValueError produces an indexed ValidationError entry carrying your message. Returning None would silently replace the bad value and turn a detectable defect into an invisible one.

Where a rule must not live

A validator is synchronous and in-process: no API call to confirm the email, no database lookup for the ticket ID, no sleeping. Construction that blocks for thirty seconds turns every parse into an outage risk, and a model built in a request handler puts that latency on the hot path. Cross-system checks belong in a service layer with their own timeout — while validators stay pure, deterministic, and fast, which is what makes enforcing them on every record free.

One class of rejection remains: noisy but harmless inputs — a labeled email with mixed case, an optional field submitted blank. Those should not reach the validators at all.

A field typed float rejects " Score: 0.85 " — and every slightly messy but reasonable value arriving from spreadsheets, form fields, and model text. Rejecting noise that could be normalized cheaply burns engineer time on false alarms while real defects scroll past.

Normalize before validating

from pydantic import BaseModel, field_validator

class Extract(BaseModel):
    email: str
    score: float | None = None

    @field_validator("email", mode="before")
    @classmethod
    def clean_email(cls, v):
        if isinstance(v, str):
            v = v.strip().lower().split("<")[-1].rstrip(">")
        return v                                   # "  <Ada@Example.com> " -> "ada@example.com"

    @field_validator("score", mode="before")
    @classmethod
    def blank_to_none(cls, v):
        return None if v == "" else v              # absent data is None, not an error

print(Extract(email="  <Ada@Example.com>  ", score=""))

Output: Extract(email='ada@example.com', score=None)

mode="before" is the whole difference: these hooks see raw input before coercion, so two short methods erase three classes of noise — case, whitespace, empty strings. score="high" still fails, because normalization never invents a number the input did not contain.

Repair or reject

The dividing line: formatting defects are the input's fault and worth repairing; semantic defects carry the data's meaning and must reach the caller as errors. A pipeline that clamps score=1.4 to 1.0 converts a measurable bug into an invisible one.

With the boundary raising the right exceptions, the suite in Testing AI Code can assert on them without the network — and Environments and Dependency Hygiene keeps the pydantic version identical on every machine.