---
"$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.20
type: object
additionalProperties: false
patternProperties:
  "^X-":
    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
      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:
      "^X-":
        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
    - url
    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 or a custom one prefixed with x-.
        pattern: "^(Swagger)$|^(OpenAPI)$|^(JSONSchema)$|^(GraphQLSchema)$|^(PostmanCollection)$|^(PostmanWorkspace)$|^(AsyncAPI)$|^(RAML)$|^(Blueprint)$|^(WADL)$|^(WSDL)$|^(GettingStarted)$|^(Documentation)$|^(Authentication)$|^(Versioning)$|^(Signup)$|^(Login)$|^(TermsOfService)$|^(InterfaceLicense)$|^(PrivacyPolicy)$|^(DeprecationPolicy)$|^(ServiceLevelAgreement)$|^(Security)$|^(SDKs)$|^(StatusPage)$|^(Pricing)$|^(RateLimits)$|^(Blog)$|^(BlogFeed)$|^(Forums)$|^(Support)$|^(ChangeLog)$|^(RoadMap)$|^(Contact)$|^(ErrorCodes)$|^(GitHubOrg)$|^(GitHubRepo)$|^(Twitter)$|^(AlertsTwitterHandle)$|^(Webhooks)$|^(Integrations)$|^(OpenAIPluginManifest)$|^(MockRestServer)$|^(MockMCPServer)$|^(BackstageApi)$|^(ModelContextProtocol)$|^(ApiExamples)$|^(ApiExamples)$|^(LlmsText)$|^(JsonStructure)$|^(Summary)$|^(AgentSkills)$|^(GitHubHttpUrl)$|^(GitHubSshUrl)$|^(GitHubIssues)$|^(GitHubDiscussions)$|^(Standards)$|^(Services)$|^(X-[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
  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.19
  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"     
  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.