A common question from teams new to APIs.json: OpenAPI already has an info block that holds the API name, description, contact information, license, and terms of service URL. Why do I need APIs.json? Isn't that redundant?
It's a fair question. There is some overlap. But the two formats are solving fundamentally different problems, and understanding where they diverge explains why you need both.
What OpenAPI's info Block Is For
The OpenAPI info block describes the API contract — the technical specification of what the API does. It answers: what is this thing called, who owns it, what version is it, what are the legal terms under which it can be used?
info:
title: Payments API
version: "2.1"
description: Manage payment intents, charges, and refunds
contact:
name: API Support
url: https://example.com/support
email: [email protected]
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
termsOfService: https://example.com/termsThis information lives inside the spec file. It's tightly coupled to a specific API version. When you publish v2.1 of your API, this block describes v2.1 specifically. When you ship v3.0, you publish a new spec with updated info.
What APIs.json Is For
APIs.json operates at a different level. It describes the API operation — everything around the API, not just the contract itself. A single APIs.json entry can reference multiple versions of an OpenAPI spec, plus the documentation, plus the authentication guide, plus the SDK list, plus the pricing page, plus the change log. It wraps the full operational surface of an API into a single discoverable index.
{
"name": "Payments API",
"description": "Process payments, manage subscriptions, handle refunds",
"baseURL": "https://api.example.com/payments",
"properties": [
{ "type": "OpenAPI", "url": "https://example.com/specs/payments-v2.yaml" },
{ "type": "OpenAPI", "url": "https://example.com/specs/payments-v3.yaml" },
{ "type": "Documentation", "url": "https://docs.example.com/payments" },
{ "type": "Authentication", "url": "https://docs.example.com/auth" },
{ "type": "Pricing", "url": "https://example.com/pricing" },
{ "type": "ChangeLog", "url": "https://docs.example.com/changelog" },
{ "type": "Support", "url": "https://github.com/example/payments/issues" }
]
}The description in an APIs.json entry describes the API product, not a specific contract version. The properties array links to everything — including multiple versions of the OpenAPI spec — so that tooling can find whichever artifact it needs.
Where the Overlap Is Real
Both formats can reference a terms of service URL. Both can include contact information. Both include a name and description. For teams that are just getting started with APIs.json, it's reasonable to treat these overlapping fields as redundant and fill in whichever format you're already using.
The practical resolution is: OpenAPI's info is for version-specific metadata that lives inside the technical contract. APIs.json is for operational metadata that spans versions, artifacts, and the full lifecycle of the API as a product. When in doubt about which format a piece of information belongs in, ask whether it's tied to a specific API version (OpenAPI) or to the API as an ongoing operation (APIs.json).
The Discovery Layer
The most important difference isn't about where information lives — it's about what happens with it. OpenAPI specs are consumed by tools that generate documentation, mock servers, client SDKs, and validation middleware. They're technical artifacts for technical consumers.
APIs.json files are consumed by discovery tools. When you publish a valid APIs.json file at a well-known location, apis.io crawls it and makes your API searchable across its entire index. Your API becomes findable by name, by capability, by provider, and by the presence of specific operational artifacts. That's a different use case entirely from what the OpenAPI info block enables.
Think of it this way: OpenAPI tells tools what your API does. APIs.json tells the world that your API exists and where to find everything about it. Both layers are necessary for a well-operated API in 2026.