OpenAI-Compatible JSON Mode Validator

Validate OpenAI-compatible JSON mode, Structured Outputs, schema validation, LLM API compatibility, and agent reliability before you trust generated JSON in production.

Many APIs expose a /v1/chat/completions shape and accept OpenAI-style options. That does not mean they behave the same for response_format, JSON-only prompts, strict schemas, refusals, markdown fences, or malformed content. This small Node CLI gives you a repeatable smoke test for any OpenAI-compatible endpoint.

TKEN is included as a disclosed example endpoint: https://www.tken.shop/v1.

Try TKEN with this repo's tracking link

What It Checks

• response_format: { "type": "json_object" } compatibility.
• response_format: { "type": "json_schema" } Structured Outputs-style compatibility.
• JSON extraction from plain JSON, fenced JSON, or text-wrapped model output.
• Basic JSON Schema validation for required fields, primitive types, arrays, objects, enums, and additional properties.
• Offline mock mode that runs with no API key and no network.
• Live endpoint checks using OPENAI_API_KEY, --base-url, and --model.

Quickstart

npm install
npm run check

Run the default offline mock directly:

node src/cli.js --mock

Validate with the included invoice schema and prompt:

node src/cli.js --mock --schema examples/schema.invoice.json --prompt examples/prompt.invoice.txt

Test A Real Endpoint

Set an API key only when you want a live provider call:

OPENAI_API_KEY=your-key node src/cli.js \
  --base-url https://api.openai.com/v1 \
  --model gpt-4o-mini \
  --schema examples/schema.invoice.json \
  --prompt examples/prompt.invoice.txt

PowerShell:

$env:OPENAI_API_KEY="your-key"
node src/cli.js --base-url https://api.openai.com/v1 --model gpt-4o-mini --schema examples/schema.invoice.json

Disclosed TKEN example endpoint:

$env:OPENAI_API_KEY="your-key"
node src/cli.js --base-url https://www.tken.shop/v1 --model your-model --schema examples/schema.invoice.json

Use JSON object mode when a provider supports JSON mode but not schema-shaped response formats:

node src/cli.js --base-url https://your-provider.example/v1 --model your-model --format json_object

Use Structured Outputs-style schema mode:

node src/cli.js --base-url https://your-provider.example/v1 --model your-model --format json_schema

CLI

node src/cli.js [options]

Options:
  --mock                  Run offline mock mode. Default when no base URL is provided.
  --base-url <url>        OpenAI-compatible base URL, for example https://www.tken.shop/v1.
  --model <name>          Chat Completions model name.
  --schema <path>         JSON Schema file. Defaults to examples/schema.invoice.json.
  --prompt <path>         Prompt text file. Defaults to examples/prompt.invoice.txt.
  --format <mode>         json_schema or json_object. Default: json_schema.
  --timeout-ms <number>   Live request timeout. Default: 30000.
  --help                  Show help.

Environment variables:

• OPENAI_API_KEY: required for live endpoint checks.
• BASE_URL: optional live base URL alias.
• OPENAI_BASE_URL: optional live base URL alias.
• MODEL: optional model alias.
• OPENAI_MODEL: optional model alias.

Why This Exists

Agent workflows often fail in ordinary ways: a model wraps JSON in markdown, misses a required field, returns a number as a string, or accepts json_schema but silently behaves like plain chat. A lightweight compatibility check catches those issues before they become parser crashes, invoice routing bugs, or flaky automation.

This project is intentionally small and original. It does not copy provider SDKs or popular validator repositories. The schema checker is basic by design; production systems should still use a mature validator library or your platform's native schema tooling.

TKEN CTA

TKEN is shown here as a transparent OpenAI-compatible endpoint example, not as a partnership claim and not as a universal compatibility promise.

Open TKEN

Keywords

OpenAI-compatible JSON mode, Structured Outputs, schema validation, LLM API compatibility, agent reliability, JSON Schema, chat completions, custom base URL, OpenAI-compatible API, response_format, TKEN.

License

MIT