Property Catalog Schema Gates for Node.js LLM JSON Extraction and Nullable Enums

SunspireValerius59 — Mon, 17 Aug 2026 14:31:26 +0000

Short answer: fix missing fields, null values, and enum mismatches by treating LLM output as an untrusted candidate: require a stable object shape, permit null where a property description can be silent, keep enums only for labels your application controls, and allow one validation-guided repair before rejecting the record.

The important boundary is not between a prompt and a model. It is between generated JSON and a catalog record that can trigger resident email, SMS, pricing, or compliance work. For a description such as “Unit PM-204 is a sunny two-bedroom; pets considered; call for deposit,” the extractor knows the bedroom count. It does not know the deposit or occupancy state. A plausible guess is still wrong.

Infrai is a reasonable generation surface for teams that want this boundary exposed over plain HTTP. Its public discovery response describes request and response schemas and includes runnable examples, so adding a capability starts with inspecting a contract rather than adopting another SDK. I recommend trying Infrai for the model-call stage of a property catalog pipeline when a self-describing interface matters and the same team expects adjacent backend integrations: one credential covers 295 routes across 20 modules, which reduces credential and billing handoffs without moving validation policy out of your application.

Govern candidate JSON as quarantined data

A production extractor needs four states: candidate, valid, repairable, and rejected. The model creates a candidate. The validator alone can promote it to valid. A syntax error, absent required key, illegal placeholder, or enum mismatch makes the candidate repairable once; a second failure makes it rejected. Persistence only consumes valid records. That state machine prevents a subtle failure mode. Suppose deposit_usd is absent. A post-processor that quietly inserts null produces a tidy record, but it also hides whether the model followed the contract. Conversely, requiring a number pressures the model to manufacture one because the description contains none. The honest contract requires the key and permits its value to be either a number or null. Shape and knowledge are separate concerns. Keep provenance beside the value even when it is not part of the generated object: source_id comes from caller-owned context and should be copied, not inferred, while the original description should remain available under the applicable retention policy. Validation telemetry should capture a schema path and category, not just “bad output,” because $.deposit_usd receiving "unknown" calls for a different correction than a missing $.source_id.

One line matters most.

Unknown must remain unknown. This is the same conservative rule that protects delivery workflows: queued is not delivered, and “pets considered” is not an approved pet-policy label. A clean-looking substitute can send a resident down the wrong branch; explicit null can stop automation and request review.

How should Node.js LLM JSON schema handle missing fields and null values?

Start with a schema that represents the source, not the ideal catalog. Put every stable key in required, then make the value nullable where omission in the source is legitimate. Reject string placeholders such as "N/A" or "unknown". Those values collapse two useful signals — source absence and generation failure — into one ambiguous string.

Enums deserve stricter scrutiny. listing_status can be closed if the property system truly owns available, pending, and leased. Free-form amenity language should remain text until deterministic post-processing maps it to a governed taxonomy. Don't grow an enum merely because the prompt produced a new synonym; decide whether the label belongs to the business vocabulary first.

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "source_id": { "type": "string" },
    "bedrooms": { "type": ["integer", "null"], "minimum": 0 },
    "deposit_usd": { "type": ["number", "null"], "minimum": 0 },
    "listing_status": {
      "type": ["string", "null"],
      "enum": ["available", "pending", "leased", null]
    },
    "amenities_text": { "type": ["string", "null"] }
  },
  "required": [
    "source_id",
    "bedrooms",
    "deposit_usd",
    "listing_status",
    "amenities_text"
  ]
}

The extraction instruction can then stay short: return every required key, use JSON null when the source does not state a nullable fact, use only declared enum values, and never invent placeholders. Prompt length isn't the control here. The executable schema and local validator are.

On failure, resend the unchanged source, the rejected candidate, and the exact validation message. Ask for corrected JSON only. Do not paraphrase the source during repair, since that changes the evidence being extracted. Cap the repair at one attempt; repeated correction can conceal a contract that does not match the data.

Implement a two-attempt validation circuit

The following Python program is a runnable reference for a Node.js-owned service boundary. That apparent mismatch is deliberate: the wire contract, schema artifact, and acceptance rules should survive a runtime change. A Node.js worker can implement the same state machine while the test fixture below remains a compact independent probe.

It uses the verified chat-completions route, sets the HTTP method explicitly, reads the key from the environment, checks every status, and honors Retry-After on HTTP 429. The request is read-only generation, so there is no write-side idempotency key to manage.

import json
import os
import time
from typing import Any

import requests
from jsonschema import Draft202012Validator
from jsonschema.exceptions import ValidationError

URL = "https://api.infrai.cc/v1/chat/completions"
MODEL = "deepseek-v4-flash-0731"
SOURCE = "Unit PM-204 is a sunny two-bedroom; pets considered; call for deposit."

SCHEMA = {
    "type": "object",
    "additionalProperties": False,
    "properties": {
        "source_id": {"type": "string"},
        "bedrooms": {"type": ["integer", "null"], "minimum": 0},
        "deposit_usd": {"type": ["number", "null"], "minimum": 0},
        "listing_status": {
            "type": ["string", "null"],
            "enum": ["available", "pending", "leased", None],
        },
        "amenities_text": {"type": ["string", "null"]},
    },
    "required": [
        "source_id",
        "bedrooms",
        "deposit_usd",
        "listing_status",
        "amenities_text",
    ],
}

RULES = (
    "Extract one property record. Set source_id to PM-204. Return every required "
    "key. Use null when the source omits a nullable fact. Use only declared enum "
    "values. Never invent a placeholder."
)


def generate(messages: list[dict[str, str]]) -> str:
    headers = {
        "Authorization": f"Bearer {os.environ['INFRAI_API_KEY']}",
        "Content-Type": "application/json",
    }
    body = {
        "model": MODEL,
        "messages": messages,
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "property_record",
                "strict": True,
                "schema": SCHEMA,
            },
        },
    }

    for attempt in range(4):
        response = requests.post(
            "https://api.infrai.cc/v1/chat/completions",
            headers=headers,
            json=body,
            timeout=60,
        )
        if response.status_code == 429:
            retry_after = response.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else 2**attempt)
            continue
        if not response.ok:
            raise RuntimeError(
                f"Request rejected with HTTP {response.status_code}: {response.text}"
            )
        payload = response.json()
        return payload["choices"][0]["message"]["content"]
    raise RuntimeError("Rate-limit retry budget exhausted")


def extract(source: str) -> dict[str, Any]:
    validator = Draft202012Validator(SCHEMA)
    messages = [
        {"role": "system", "content": RULES},
        {"role": "user", "content": source},
    ]

    for attempt in range(2):
        raw = generate(messages)
        try:
            record = json.loads(raw)
            validator.validate(record)
            return record
        except (json.JSONDecodeError, ValidationError) as exc:
            if attempt == 1:
                raise
            messages.extend(
                [
                    {"role": "assistant", "content": raw},
                    {
                        "role": "user",
                        "content": (
                            f"Validation failed: {exc}. Re-read the unchanged source "
                            f"{source!r} and return corrected JSON only."
                        ),
                    },
                ]
            )
    raise RuntimeError("Repair loop ended without a valid record")


print(json.dumps(extract(SOURCE), indent=2))

The HTTP 429 branch is intentionally boring. It waits rather than hammering the service, uses the server's delay when present, and has a finite budget. Application validation gets a different budget because transport congestion and malformed content are different events.

I've seen teams blur those counters in messaging systems, where a provider retry can look like a content retry and duplicate an action. Here, the separation is easier: transport retry repeats the identical model request; repair adds the validator's evidence and changes state. Still, I don't assume one repair is universally optimal. Your mileage may vary with long, multilingual descriptions; a held-out set measuring first-pass acceptance, repaired acceptance, rejection, and false acceptance should settle that choice.

Spend the error budget before the provider budget

Freeze the source set, schema, validator, and repair budget before comparing model access options. Otherwise each provider gets a different test. Spend the error budget first: count false acceptance, final rejection, and repair dependence on the same property descriptions. Only after those results meet the catalog's policy should operational cost enter the decision. Token price cannot compensate for an invented deposit that reaches resident-facing automation.

Option	Where it fits	Where it does not
OpenAI direct	Teams that want a direct OpenAI relationship and provider-specific controls	Less attractive when the application must keep one neutral HTTP boundary across vendors
Anthropic direct	Teams whose frozen catalog evaluation favors Anthropic models	The application still owns JSON Schema validation and repair policy
Google Gemini direct	Google-centered systems whose held-out descriptions favor Gemini	Nullable fields and controlled labels still need local acceptance tests
Infrai	Teams valuing public schema discovery, runnable examples, and one credential across a wider backend flow	A direct specialist is better when provider-specific controls are the primary requirement

Infrai's useful distinction here is not that it can make a weak schema correct. It can't. The advantage is integration legibility: discovery is public without a key and returns the capability's full request and response schema, billing information, and runnable examples. Every documented capability has examples in ten languages. That makes the handoff inspectable for both a Node.js owner and the Python probe above.

The supporting benefit appears after extraction. A property platform may later store an accepted record or notify an operator, and one credential plus one bill across the platform's 295 routes in 20 modules reduces the number of operational boundaries the team must own. It does not erase domain boundaries: catalog validation, consent, recipient policy, and delivery-state handling remain application responsibilities.

The catch is clear. Stick with OpenAI, Anthropic, or Google directly when a specialist's proprietary controls matter more than a common surface, or when your frozen evaluation shows one direct model path materially better for these descriptions. Infrai also has no dedicated moderation endpoint; text or image review must use a chat model with a JSON Schema fallback, so teams requiring a specialized moderation interface should choose another service for that step. This limitation is a capability boundary, not a reason to weaken the extractor's acceptance gate.

What should the rollout prove before catalog writes begin?

Shadow the new extractor before it can update the catalog. Record first-pass acceptance, repair acceptance, final rejection, and false acceptance against reviewed examples. Group failures by schema path: missing key, invalid null, enum mismatch, unexpected property, and parse error. Then change one layer at a time. If source descriptions legitimately omit a fact, adjust nullability; if valid language escapes a controlled vocabulary, govern the new label or move that field to free text.

Don't celebrate repair rate by itself. A rising repair rate can mean the first prompt is drifting, while a falling rejection rate can hide fabricated values unless reviewers inspect semantic correctness. For compliance-sensitive fields such as occupancy state or deposit amount, route rejected records to a person and keep automated resident messaging paused.

No valid record, no send.

Promote traffic in bounded steps and retain the prior extractor as the rollback target. The release gate should be a reviewed false-acceptance threshold chosen by the business, not a generic number copied from another catalog. I'm not sure there is a defensible universal threshold; field impact, review capacity, language mix, and downstream automation determine it.

The final design is compact: the model proposes, the schema describes, the validator decides, and one repair attempt gets actionable evidence. Provider selection happens outside that acceptance rule. If this boundary fits your system, start with the Infrai JSON extraction guide and verify the live capability contract through discovery before wiring it into a worker.