---
"$id": https://github.com/apis-json/api-json/blob/develop/spec/
"$schema": https://json-schema.org/draft/2020-12/schema
title: JSON Schema for APIs.json 0.23
type: object
additionalProperties: false
patternProperties:
  "^[Xx]-":
    type: object

$defs:

  maintainers:
    description: The person or organization responsible for maintaining the API
    required:
    - name
    properties:
      name:
        type: string
        description: name
        minLength: 5
    additionalProperties:
      type: string

  apis:
    description: The description of the API
    required:
      - name
      - description
      - image
      - baseURL
      - humanURL
      - properties
    properties:
      aid:
        type: string
        description: unique identifier for API
      name:
        type: string
        description: name
        minLength: 2
      description:
        type: string
        description: description of the API
        minLength: 5
      image:
        type: string
        description: URL of an image representing the API
      created:
        type: string
        format: date
        description: Date when the api was added to APIs.json
      modified:
        type: string
        format: date
        description: Date when the api was last modified
      baseURL:
        type: string
        pattern: "^(http)|(https)://(.*)$"
        description: baseURL
      humanURL:
        type: string
        pattern: "^(http)|(https)://(.*)$"
        description: humanURL
      tags:
        type: array
        items:
          type: string
          minLength: 1
        description: tags to describe the API
      properties:
        type: array
        items:
          "$ref": "#/$defs/urls"
        description: URLs
      prompts:
        type: array
        items:
          "$ref": "#/$defs/urls"
        description: AI prompts that apply to this API
      rules:
        type: array
        items:
          "$ref": "#/$defs/urls"
        description: Governance rulesets (e.g. Spectral) that apply to this API
      workflows:
        type: array
        items:
          "$ref": "#/$defs/urls"
        description: Arazzo (or other) workflows that apply to this API
      contact:
        type: array
        items:
          "$ref": "#/$defs/contact"
        description: Contact to reach if questions about API
      meta:
        type: array
        items:
          "$ref": "#/$defs/metaInformation"
  metaInformation:
    description: Metadata about the API
    required:
    - key
    - value
    properties:
      key:
        type: string
      value:
        type: string
  contact:
    description: Information on contacting the API support
    required:
    - FN
    additionalProperties: true
    patternProperties:
      "^[Xx]-":
        type: string
    properties:
      FN:
        type: string
        minLength: 1
      email:
        type: string
        format: email
      organizationName:
        type: string
        minLength: 1
      adr:
        type: string
      tel:
        type: string
        minLength: 1
      X-twitter:
        type: string
      X-github:
        type: string
      photo:
        type: string
        pattern: "^(http)|(https)://(.*)$"
      vCard:
        type: string
        pattern: "^(http)|(https)://(.*)$"
      url:
        type: string
        pattern: "^(http)|(https)://(.*)$"
  urls:
    description: A representation of a URL
    required:
    - type
    oneOf:
    - required:
      - url
    - required:
      - data
    properties:
      name:
        type: string
        description:  The display name of the property.
      description:
        type: string
        description: The description of the property.
        minLength: 5
      type:
        type: string
        description: One of the designated API property types — canonical names AND their recognised synonyms are accepted, because this vocabulary is spelled many ways in the wild — or an extension prefixed with x- or X-.
        pattern: "^(Swagger|OpenAPI|OpenAPISource|OpenAPI Source|JSONSchema|GraphQLSchema|GraphQL|PostmanCollection|PostmanWorkspace|InsomniaCollection|BrunoCollection|AsyncAPI|RAML|Blueprint|WADL|WSDL|ALPS|OpenAIPluginManifest|JSONLD|JSONLDContext|JSONForms|JSONStructure|Vocabulary|Arazzo|Overlay|ServerlessWorkflow|Workflow|Compare|Evolution|DataContract|SpectralRules|Rules|GovernanceRules|GettingStarted|Documentation|APIReference|Authentication|APIKeys|APIKey|APIOnboarding|Versioning|Signup|Login|SDKs|CLI|Console|Sandbox|Examples|ApiExamples|FAQ|Summary|Features|Solutions|Tools|Careers|Prompt|AgentPrompt|PromptTemplate|AgentSkills|LlmsText|ModelContextProtocol|MCPServer|MockRestServer|MockMCPServer|BackstageApi|Standards|Standard|Conformance|Certification|Services|About|Specification|Plans|Pricing|RateLimits|StatusPage|ChangeLog|ReleaseNotes|RoadMap|DeprecationPolicy|TermsOfService|InterfaceLicense|Licensing|PrivacyPolicy|ServiceLevelAgreement|Security|Compliance|License|Training|Blog|BlogFeed|Forums|Support|Contact|ErrorCodes|Webhooks|Integrations|UseCases|Community|StackOverflow|Slack|Discord|Website|Portal|DeveloperPortal|YouTube|LinkedIn|GitHubOrg|GitHubOrganization|GitHubRepo|GitHubRepository|GitHubHttpUrl|GitHubSshUrl|GitHubIssues|GitHubDiscussions|Twitter|X|AlertsTwitterHandle|FinOps|FinOpsFramework|FocusBillingExport|FocusConformanceReport|FocusContractCommitments|OpenCostSpecification|OpenCostAllocationAPI|UnitEconomics|ChargebackPolicy|TaggingPolicy|InvoiceReconciliation|SoftwareCarbonIntensity|SCIReport|GHGProtocolReport|PublicAPIsListing|Review|DomainSecurity|LLMsTxt|AgenticAccess|ContentSignal|SignUp|VulnerabilityDisclosure|Lifecycle|TrustCenter|Conventions|WellKnown|Packages|ErrorCatalog|DataModel|AgentSkill|OAuthScopes|HelpCenter|SecurityTxt|Deprecation|Components|SourceCode|BlogRSS|Idempotency|Partners|Instagram|Postman|InvestorRelations|Facebook|Newsroom|Crunchbase|CodeExamples|Wikipedia|ContactUs|OpenIDConnect|CaseStudies|Roadmap|Tutorials|Sustainability|ParentCompany|Repository|PressReleases|Events|Protobuf|DeclineCodes|Newsletter|HelmChart|DockerImage|ContributionGuide|CodeOfConduct|SecurityPolicy|Releases|IssueTracker|Contributors|Maintainers|KubernetesOperator|AgentCard|MCPClient|A2A|SBOM|Attestation|Provenance|APICatalog|Playground|Quickstart|KnowledgeBase|MailingList|API Documentation|APIDocumentation|Connect Go SDK|Connect Node\\.js SDK|Connect Python SDK|Deprecation Notice|Deprecations|Developer Portal|Discourse|Forum|GitHub|GitHub Org|Go SDK|Help Center|JSON Schema|API Key|API Keys|JSON\\-LD Context|Java SDK|JavaScript SDK|Knowledge Base|Knowledge Center|KnowledgeCenter|LLMsText|LlmsTxt|Mailing List|Mailing Lists|MailingLists|Node\\.js SDK|PHP SDK|Postman Collection|Privacy|Python SDK|Reference|Register|Registration|Ruby SDK|SDK|Security Policy|Sign Up|Source Code|Spectral|Spectral Rules|SpectralRuleset|Terms of Service|Terms of Use|TermsOfUse|Trust)$|^([Xx]-[A-Za-z0-9._\\-]*)$"
      mediaType:
        type: string
        description: IANA media type representing the property.
      url:
        type: string
        description: The URL for the property. * must be url or data.
      data:
        oneOf:
          - type: object
          - type: array
        description: The data for the property. * must be url or data
      tags:
        type: array
        items:
          type: string
          minLength: 1
        description: Tags to describe the property.
  tags:
    description: A consistent set of tag to apply to a description

  include:
    description: Include other APIs.json file
    required:
    - name
    - url
    properties:
      name:
        type: string
        minLength: 1
      url:
        type: string
  overlay:
    description: Overlay other APIs.json file
    required:
    - url
    properties:
      name:
        type: string
        minLength: 1
      url:
        type: string
  network:
    description: Network APIs.json file
    required:
    - name
    - url
    properties:
      name:
        type: string
        minLength: 1
      url:
        type: string
required:
- name
- description
- url
- apis
- maintainers
- tags

properties:

  aid:
    type: string
    description: unique identifier for APIs.json
  visibility:
    type: string
    description: The visibility for the APIs.json collection.
    enum:
      - Public
      - Private
      - Partner
  rating:
    type: string
    description: The rating for the APIs.json collection.
    enum:
      - A
      - B
      - C
      - D
      - F
  type:
    type: string
    description: The type of the APIs.json collection.
    enum:
      - Index
      - Template
      - Example
      - Collection
      - Sandbox
      - Knowledgebase
      - Blueprint
      - Contract
      - Search
      - Network
  kind:
    type: string
    description: The kind of entity the collection describes (e.g. company, government, opensource, standard, contract, topic).
  position:
    type: string
    description: The position of the maintainer of APIs.json.
    enum:
      - Producing
      - Consuming
  access:
    type: string
    description: The access level for the APIs in an APIs.json.
    enum:
      - Internal
      - 1st-Party
      - 3rd-Party
  name:
    type: string
    description: The name of the service described
    minLength: 3
    maxLength: 50
  description:
    type: string
    description: Description of the service
    minLength: 5
    maxLength: 1000
  url:
    type: string
    description: URL where the apis.json file will live
    pattern: "^(http)|(https)://(.*)$"
  image:
    type: string
    description: Image to represent the API
  created:
    type: string
    format: date
    description: Date when the file was created
  modified:
    type: string
    format: date
    description: Date when the file was modified
  specificationVersion:
    type: string
    description: APIs.json spec version, latest is 0.23
  apis:
    type: array
    items:
      "$ref": "#/$defs/apis"
    description: All the APIs of this service
  maintainers:
    type: array
    items:
      "$ref": "#/$defs/contact"
    description: Maintainers of the apis.json file
  tags:
    type: array
    items:
      "$ref": "#/$defs/tags"
    description: Tags to describe the service
  include:
    type: array
    items:
      "$ref": "#/$defs/include"
    description: Links to other apis.json definitions included in this service
  common:
    description: Common properties that apply across all APIs.
    type: array
    items:
      "$ref": "#/$defs/urls"
  prompts:
    description: AI prompts that apply across all APIs.
    type: array
    items:
      "$ref": "#/$defs/urls"
  rules:
    description: Governance rulesets (e.g. Spectral) that apply across all APIs.
    type: array
    items:
      "$ref": "#/$defs/urls"
  workflows:
    description: Arazzo (or other) workflows that apply across all APIs.
    type: array
    items:
      "$ref": "#/$defs/urls"
  overlays:
    type: array
    items:
      "$ref": "#/$defs/overlay"
    description: Links to other apis.json that will be overlaid original.
  network:
    type: array
    items:
      "$ref": "#/$defs/network"
    description: Links to other apis.json that will be included in discovery.