The Case for JSON as the New API Schema Standard

‌

‌

Look—I love OpenAPI. I really do.

But sometimes? It’s too much.

In 2025, we’re seeing a quiet shift: lightweight JSON schemas becoming the de facto way teams describe and exchange API contracts.

Why? Because developers want speed, clarity, and tooling that doesn’t suck.

Why JSON schemas are winning

✅ Human-readable AND machine-readable
✅ Works great with TypeScript/ts-json-schema
✅ JSON + Schema = contract + validation in one

And it scales down beautifully. Sometimes all you need is:

{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "email": {"type": "string"}
  },
  "required": ["name", "email"]
}

Done. Schema, validation, docs—generated.

When to reach for OpenAPI

• Big public-facing APIs
• Need auto-generated SDKs
• Want built-in OAuth2/response docs

Otherwise?

Takeaway: JSON Schema is like Markdown for APIs: lightweight, clear, and fast.