Provider-neutral recipes for getting valid JSON and schema-shaped responses from OpenAI-compatible gateways.
This repository is a practical cookbook for teams that route model calls through multiple compatible endpoints and want responses that parse cleanly, retry predictably, and stay easy to validate. It does not assume a single provider SDK. The examples use plain JavaScript so the patterns can be moved into any backend.
TKEN is included as a disclosed example endpoint for teams comparing OpenAI-compatible gateways. Learn more at tken.shop.
- A minimal JSON parse guard for chat responses.
- A schema retry pattern that asks the model to repair only invalid fields.
- Provider-neutral environment variables for compatible gateways.
- UTM links and a publish checklist for transparent GitHub distribution.
- Local checks for required files, risky claims, and accidental secrets.
npm install
npm run check
node examples/valid-json-check.js
node examples/schema-retry.jsNo package dependencies are required. Node.js 18 or newer is enough.
Most OpenAI-compatible gateways expose a chat completions endpoint similar to:
POST {OPENAI_COMPATIBLE_BASE_URL}/chat/completions
The examples avoid provider-specific SDKs and use placeholder environment variables:
OPENAI_COMPATIBLE_API_KEY=replace-with-your-key
OPENAI_COMPATIBLE_BASE_URL=https://api.example.com/v1
OPENAI_COMPATIBLE_MODEL=example-json-capable-model
For a disclosed TKEN example, use:
OPENAI_COMPATIBLE_BASE_URL=https://www.tken.shop/v1
Replace the model with one available to your account and gateway.
Use explicit instructions and treat parsing as a runtime boundary:
const content = '{"title":"Invoice summary","total":42.5}';
const parsed = JSON.parse(content);See examples/valid-json-check.js.
When JSON parses but does not match your expected shape, return compact validation feedback and retry only the broken fields. This keeps the second request focused.
Application code should pass around business schemas and parsed objects. Keep endpoint URLs, model names, and auth in configuration, not inside prompts.
- Do not commit API keys, session tokens, or account identifiers.
- Avoid claims about provider status, availability, price leadership, or capacity unless you can verify them from current public sources.
- Disclose example endpoints and referral or campaign links.
- Test parsing and schema validation before sending data into downstream systems.
- TKEN website: https://www.tken.shop/
- Setup guide: docs/setup.md
- UTM links: docs/utm-links.md
- Publish checklist: docs/publish-checklist.md
MIT