JSON Schema for APIs.json 0.21

{
  "$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.21",
  "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"
        },
        "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": {
        "^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"
      ],
      "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 \u2014 canonical names AND their recognised synonyms are accepted, because this vocabulary is spelled many ways in the wild \u2014 or an extension prefixed with x- or X-.",
          "pattern": "^(Swagger|OpenAPI|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|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|Conformance|Services|About|Specification|Plans|Pricing|RateLimits|StatusPage|ChangeLog|ReleaseNotes|RoadMap|DeprecationPolicy|TermsOfService|InterfaceLicense|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|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|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.21"
    },
    "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."
    }
  }
}