What's New in APIs.json 0.20

APIs.json 0.20 is the largest vocabulary expansion in the specification's history. The type field on each property entry in an APIs.json file is how tooling, indexers, and AI agents understand what kind of thing is being referenced — the spec, the docs, the pricing page, the Slack community. Until now, that vocabulary was conservative. Version 0.20 significantly expands it based on analysis of how real API providers are actually using APIs.json in the wild, and adds a large block of types that belong to a schema-validated list rather than the X- custom prefix space.

The full diff is on GitHub. Here's what changed by category.

Technical Contracts

Several formats that have matured into broad adoption are now first-class reserved types:

• JSONStructure — link to a JSON Structure definition for the API's data model
• Vocabulary — link to the controlled vocabulary or semantic model used by the API
• SpectralRules — link to the Spectral ruleset that governs the API's OpenAPI/AsyncAPI validation
• AgentSkills — link to an Agent Skills definition for AI agent integration
• LlmsText — link to a llms.txt file for LLM consumption
• ModelContextProtocol — link to an MCP server definition
• MockRestServer / MockMCPServer — links to mock server endpoints for development and testing
• BackstageApi — link to a Backstage catalog entity for the API
• ApiExamples — link to a structured examples file
• Standards — link to the standards or specifications the API claims conformance with
• Services — link to a services catalog or service mesh definition

Additionally, several formats that were documented in the specification text but not yet in the schema validation are now formally reserved: ALPS, Arazzo, JSONForms, DataContract, and ServerlessWorkflow.

Collections & Workspaces

InsomniaCollection and BrunoCollection are now reserved types alongside the existing PostmanCollection and PostmanWorkspace. These cover the two most widely used open-source REST client collection formats.

Developer Experience

Six new types cover the parts of developer experience that weren't previously addressable as first-class properties:

• CLI — link to the command-line interface for the API
• Console — link to an interactive API console or explorer
• Sandbox — link to a sandbox environment for testing without production credentials
• Examples — link to a general examples page or repository
• FAQ — link to a frequently asked questions page
• Summary — link to a high-level summary or overview document

Business

Plans is now a reserved type — distinct from Pricing, which points to a pricing page. Plans points to a structured plans comparison page or machine-readable plans document. UseCases is also now formally reserved for linking use case documentation or case studies.

Lifecycle

ReleaseNotes joins ChangeLog and RoadMap as a reserved lifecycle property. Many providers publish granular release notes distinct from a full changelog, and this type covers that distinction.

Legal & Compliance

Three new types round out the compliance picture:

• Compliance — link to compliance certification documentation (SOC 2, GDPR, HIPAA, PCI-DSS, etc.)
• License — link to the API's interface license, distinct from the existing InterfaceLicense type
• Training — link to structured learning resources (courses, certification paths, guided tutorials)

Community & Support

Four community channel types are now reserved:

• Community — link to the primary community hub or forum
• StackOverflow — link to the API's tagged questions on Stack Overflow
• Slack — link to the provider's developer Slack workspace
• Discord — link to the provider's Discord server

Web Presence

Five types now cover the web and portal footprint of an API provider:

• Website — the API provider's main website
• Portal — the API portal (may differ from the developer portal)
• DeveloperPortal — the dedicated developer portal
• YouTube — the provider's YouTube channel
• LinkedIn — the provider's LinkedIn profile

Source Control & Social

The GitHub property set is now complete: GitHubHttpUrl, GitHubSshUrl, GitHubIssues, and GitHubDiscussions join the existing GitHubOrg, GitHubRepo, and their aliases. GitHubOrganization and GitHubRepository are now formal aliases for GitHubOrg and GitHubRepo respectively. X is now reserved as the current platform name alongside the legacy Twitter type.

Naming Fixes

One naming inconsistency was corrected: JsonStructure was renamed to JSONStructure to match the capitalization convention used by JSONSchema, JSONLD, and other JSON-prefixed types in the specification.

Schema and Spec Document Now in Sync

As part of the 0.20 work, we audited the specification text document and the JSON Schema validation file to ensure they list the same reserved types. Previously, a number of types were documented in the spec text but not enforced by the schema, and vice versa. Both are now consistent. The canonical list of reserved words is maintained at apisjson.org/format/reservedwords.

The 0.20 schema is available at apisjson.org/format/apisjson_0.20.txt. If you have feedback on any of the new types or want to propose additional additions for 0.21, open an issue on GitHub.