APIs.json · API Governance Rules

APIs.json API Rules

Spectral linting rules defining API design standards and conventions for APIs.json.

34 Rules error 15 warn 12 info 7
Authorship not recorded No authorship marker is recorded for this file. It is not presented as the provider's; it was most likely written by an API Evangelist pass before outputs were stamped.
View Rules File View on GitHub

Rule Categories

api common documentation maintainer no openapi property root specification

Rules

error
root-name-required
APIs.json root must have a name field
$
error
root-description-required
APIs.json root must have a description field
$
error
root-url-required
APIs.json root must have a url field pointing to the file location
$
warn
root-url-https
APIs.json root url should use HTTPS
$.url
error
root-created-required
APIs.json root must have a created date
$
error
root-modified-required
APIs.json root must have a modified date
$
error
root-specification-version-required
APIs.json root must have a specificationVersion field
$
warn
root-aid-recommended
APIs.json root should have an aid (unique identifier) field
$
warn
root-aid-format
APIs.json aid should follow the format domain:string
$.aid
warn
root-maintainers-recommended
APIs.json root should have maintainers defined
$
info
root-tags-recommended
APIs.json root should have tags for discoverability
$
info
root-image-recommended
APIs.json root should have an image URL for visual representation
$
error
maintainer-fn-required
Maintainer entries must have an FN (full name) field
$.maintainers[*]
error
maintainer-fn-not-empty
Maintainer FN must not be empty
$.maintainers[*].FN
warn
maintainer-email-format
Maintainer email should be a valid email format
$.maintainers[*].email
error
api-aid-required
Each API entry must have an aid (unique identifier)
$.apis[*]
warn
api-aid-format
API aid should follow the format domain:string
$.apis[*].aid
error
api-name-required
Each API entry must have a name
$.apis[*]
error
api-description-required
Each API entry must have a description
$.apis[*]
warn
api-description-min-length
API description should be descriptive (at least 20 characters)
$.apis[*].description
warn
api-human-url-required
Each API entry should have a humanURL
$.apis[*]
warn
api-human-url-https
API humanURL should use HTTPS
$.apis[*].humanURL
warn
api-base-url-https
API baseURL should use HTTPS
$.apis[*].baseURL
info
api-tags-recommended
Each API entry should have tags for discoverability
$.apis[*]
warn
api-properties-recommended
Each API entry should have at least one property
$.apis[*]
info
common-website-recommended
Common properties should include a Website entry
$.common
error
property-type-required
Each property entry must have a type field
$..properties[*]
error
property-url-or-data-required
Each property entry must have either a url or data field
$..properties[*]
warn
property-url-https
Property URLs should use HTTPS
$..properties[*].url
error
no-empty-names
Name fields must not be empty strings
$..name
error
no-empty-descriptions
Description fields must not be empty strings
$..description
info
specification-version-current
specificationVersion should use the latest stable version (0.19)
$.specificationVersion
info
documentation-property-recommended
APIs should have a Documentation property for human-readable reference
$.apis[*].properties[*].type
info
openapi-property-recommended
APIs should have an OpenAPI property for machine-readable interface definition
$.apis[*].properties[*].type

Spectral Ruleset

apis-json-spectral-rules.yml Raw ↑ 
rules:
  # ROOT LEVEL — REQUIRED FIELDS
  root-name-required:
    description: APIs.json root must have a name field
    severity: error
    given: "$"
    then:
      field: name
      function: truthy

  root-description-required:
    description: APIs.json root must have a description field
    severity: error
    given: "$"
    then:
      field: description
      function: truthy

  root-url-required:
    description: APIs.json root must have a url field pointing to the file location
    severity: error
    given: "$"
    then:
      field: url
      function: truthy

  root-url-https:
    description: APIs.json root url should use HTTPS
    severity: warn
    given: "$.url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  root-created-required:
    description: APIs.json root must have a created date
    severity: error
    given: "$"
    then:
      field: created
      function: truthy

  root-modified-required:
    description: APIs.json root must have a modified date
    severity: error
    given: "$"
    then:
      field: modified
      function: truthy

  root-specification-version-required:
    description: APIs.json root must have a specificationVersion field
    severity: error
    given: "$"
    then:
      field: specificationVersion
      function: truthy

  root-aid-recommended:
    description: APIs.json root should have an aid (unique identifier) field
    severity: warn
    given: "$"
    then:
      field: aid
      function: truthy

  root-aid-format:
    description: APIs.json aid should follow the format domain:string
    severity: warn
    given: "$.aid"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z0-9.-]+:[a-z0-9._-]+$"

  root-maintainers-recommended:
    description: APIs.json root should have maintainers defined
    severity: warn
    given: "$"
    then:
      field: maintainers
      function: truthy

  root-tags-recommended:
    description: APIs.json root should have tags for discoverability
    severity: info
    given: "$"
    then:
      field: tags
      function: truthy

  root-image-recommended:
    description: APIs.json root should have an image URL for visual representation
    severity: info
    given: "$"
    then:
      field: image
      function: truthy

  # MAINTAINERS
  maintainer-fn-required:
    description: Maintainer entries must have an FN (full name) field
    severity: error
    given: "$.maintainers[*]"
    then:
      field: FN
      function: truthy

  maintainer-fn-not-empty:
    description: Maintainer FN must not be empty
    severity: error
    given: "$.maintainers[*].FN"
    then:
      function: minLength
      functionOptions:
        limit: 1

  maintainer-email-format:
    description: Maintainer email should be a valid email format
    severity: warn
    given: "$.maintainers[*].email"
    then:
      function: pattern
      functionOptions:
        match: "^[^@]+@[^@]+\\.[^@]+$"

  # APIs ENTRIES
  api-aid-required:
    description: Each API entry must have an aid (unique identifier)
    severity: error
    given: "$.apis[*]"
    then:
      field: aid
      function: truthy

  api-aid-format:
    description: API aid should follow the format domain:string
    severity: warn
    given: "$.apis[*].aid"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z0-9.-]+:[a-z0-9._-]+$"

  api-name-required:
    description: Each API entry must have a name
    severity: error
    given: "$.apis[*]"
    then:
      field: name
      function: truthy

  api-description-required:
    description: Each API entry must have a description
    severity: error
    given: "$.apis[*]"
    then:
      field: description
      function: truthy

  api-description-min-length:
    description: API description should be descriptive (at least 20 characters)
    severity: warn
    given: "$.apis[*].description"
    then:
      function: minLength
      functionOptions:
        limit: 20

  api-human-url-required:
    description: Each API entry should have a humanURL
    severity: warn
    given: "$.apis[*]"
    then:
      field: humanURL
      function: truthy

  api-human-url-https:
    description: API humanURL should use HTTPS
    severity: warn
    given: "$.apis[*].humanURL"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  api-base-url-https:
    description: API baseURL should use HTTPS
    severity: warn
    given: "$.apis[*].baseURL"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  api-tags-recommended:
    description: Each API entry should have tags for discoverability
    severity: info
    given: "$.apis[*]"
    then:
      field: tags
      function: truthy

  api-properties-recommended:
    description: Each API entry should have at least one property
    severity: warn
    given: "$.apis[*]"
    then:
      field: properties
      function: truthy

  # COMMON PROPERTIES
  common-website-recommended:
    description: Common properties should include a Website entry
    severity: info
    given: "$.common"
    then:
      function: truthy

  # PROPERTY ENTRIES
  property-type-required:
    description: Each property entry must have a type field
    severity: error
    given: "$..properties[*]"
    then:
      field: type
      function: truthy

  property-url-or-data-required:
    description: Each property entry must have either a url or data field
    severity: error
    given: "$..properties[*]"
    then:
      function: truthy

  property-url-https:
    description: Property URLs should use HTTPS
    severity: warn
    given: "$..properties[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  # GENERAL QUALITY
  no-empty-names:
    description: Name fields must not be empty strings
    severity: error
    given: "$..name"
    then:
      function: pattern
      functionOptions:
        match: ".+"

  no-empty-descriptions:
    description: Description fields must not be empty strings
    severity: error
    given: "$..description"
    then:
      function: pattern
      functionOptions:
        match: ".+"

  specification-version-current:
    description: specificationVersion should use the latest stable version (0.19)
    severity: info
    given: "$.specificationVersion"
    then:
      function: pattern
      functionOptions:
        match: "^0\\.(1[5-9]|[2-9][0-9])"

  documentation-property-recommended:
    description: APIs should have a Documentation property for human-readable reference
    severity: info
    given: "$.apis[*].properties[*].type"
    then:
      function: enumeration
      functionOptions:
        values:
          - Documentation
          - APIReference

  openapi-property-recommended:
    description: APIs should have an OpenAPI property for machine-readable interface definition
    severity: info
    given: "$.apis[*].properties[*].type"
    then:
      function: enumeration
      functionOptions:
        values:
          - OpenAPI
          - Swagger
          - AsyncAPI

Work with this as data

Every ruleset here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for spectral rules

4 MCP tools reach this
  • find_rulesBrowse and filter every ruleset in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This ruleset 
curl "https://apis.io/api/v1/rules/apis-json-spectral-rules"
All spectral rules 
curl "https://apis.io/api/v1/rules?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.