What's New in APIs.json 0.21

APIs.json 0.21 turns the index into something an AI agent can act on. Where 0.20 was about expanding the property vocabulary, 0.21 adds three new top-level collections — prompts, rules, and workflows — that describe how to use, govern, and orchestrate an API, not just where to find it. Each is available at both the top level (applying across every API in the index) and on an individual API entry, mirroring the existing common and properties split.

As with prior releases, the additions were driven by analysis of how API providers are already using APIs.json in the wild. Spectral rulesets, Arazzo workflows, and a growing set of AI prompts were already appearing inside common and properties — 0.21 gives them dedicated, discoverable homes.

Three new collections

Each entry in the new collections uses the same shape as a property — type, url (or inline data), and optional name, description, mediaType, and tags.

• prompts — AI prompts that help humans and agents work with an API. Types: Prompt, AgentPrompt, PromptTemplate.
• rules — governance rulesets the API is held to. Types: SpectralRules, Rules, GovernanceRules.
• workflows — multi-step jobs-to-be-done across operations. Types: Arazzo, ServerlessWorkflow, Workflow.

prompts:
  - type: AgentPrompt
    url: https://developers.example.com/prompts/getting-started.md
rules:
  - type: SpectralRules
    url: https://developers.example.com/governance/example-rules.yaml
workflows:
  - type: Arazzo
    url: https://developers.example.com/workflows/onboard-and-charge.yaml

A new top-level kind

0.21 documents kind, which classifies the entity an index is about — company, government, opensource, standard, contract, topic, and so on — separately from the document type. It replaces the old x-type / xType vendor extensions.

Vocabulary promoted from real-world usage

A survey of indexes in the wild surfaced widely-used types that were not yet reserved. These are now first-class: FinOps, Features, Solutions, Tools, Careers, APIReference, GraphQL, JSONLDContext, PublicAPIsListing, Review, About, and Specification.

Schema and spec back in sync

The JSON Schema type pattern had drifted behind the reserved-words list — several types documented in the spec text (including Arazzo, JSONLD, and Vocabulary) were not actually enforced, and there was a casing bug (JsonStructure vs. JSONStructure). The schema's allowlist is now complete and consistent with the specification text and the reserved words page.

The canonical specification text and JSON Schema live in the api-json repository as apisjson_0.21.txt and schema_0.21.yml.