documentationUrl: https://spec.openlint.org/
functions:
- digitalocean-ensurePropertiesExample
- microcks-aas-verify-mocks
- microcks-oas-verify-mocks
- trimble-check-description-for-all-error-responses
- trimble-check-description-for-all-success-responses
- trimble-check-for-path-parameter
- trimble-check-for-response-in-every-request
- trimble-operation-summary-description
functionsDir: ./functions
rules:
  openapi-channel-parameter-require-examples:
    description: Parameter must have examples.
    message: Parameter must have examples
    severity: info
    given: $.channels.*.parameters.*.schema
    then:
      field: examples
      function: truthy
    formats:
    - aas2
    documentationUrl: https://apicommons.org/rules/#openapi-channel-parameter-require-examples
  openapi-component-message-require-examples:
    description: Message must have examples.
    message: Message must have examples
    severity: info
    given: $.components.messages.*
    then:
      field: examples
      function: truthy
    formats:
    - aas3
    documentationUrl: https://apicommons.org/rules/#openapi-component-message-require-examples
  openapi-document-cache-control-parameter:
    description: 'Cache usage SHOULD be extensively detailed in the `description` property to avoid data leaks or the usage
      of stale data. This rule should ensure in some way that the api provider documented extensively the cache usage to avoid
      data leaks or usage of stale data. For now this ruleset tests: * the presence of following keywords in the `description`:
      `max-age`, `private`, `no-store`, `no-cache`. * that one and only one between Expires and Cache-Control is used. `Cache-Control`
      and `Expires` should not be used in conjuction, because `Cache-Control` overrides `Expires` when `max-age` is set. Instead
      if neither `Cache-Control` or `Expires` are set, clients MAY use euristic cache like described in RFC7234.'
    message: Cache usage SHOULD be documented when used.
    severity: info
    given: $..[parameters][?(@.in == "header" && @.name.match(/Cache-Control/i))]
    then:
    - field: description
      function: truthy
    - field: description
      function: pattern
      functionOptions:
        match: .*(max-age|private|no-store|no-cache).*
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-document-cache-control-parameter
  openapi-document-cache-response-header:
    description: 'Cache usage SHOULD be extensively detailed in the `description` property to avoid data leaks or the usage
      of stale data. This rule should ensure in some way that the api provider documented extensively the cache usage to avoid
      data leaks or usage of stale data. For now this ruleset tests: * the presence of following keywords in the `description`:
      `max-age`, `private`, `no-store`, `no-cache`. * that one and only one between Expires and Cache-Control is used. `Cache-Control`
      and `Expires` should not be used in conjuction, because `Cache-Control` overrides `Expires` when `max-age` is set. Instead
      if neither `Cache-Control` or `Expires` are set, clients MAY use euristic cache like described in RFC7234.'
    message: Cache usage in responses SHOULD be documented in Cache-Control and/or Expires. {{error}}
    severity: info
    given: $.[responses][?(@property[0] == "2" )][headers].[?(@property.match(/Cache-Control|Expires/i))]]
    then:
    - field: description
      function: truthy
    - field: description
      function: pattern
      functionOptions:
        match: .*(max-age|private|no-store|no-cache).*
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-document-cache-response-header
  openapi-document-require-external-docs:
    description: Defining external documentation provides a link to detailed API guides, tutorials, and reference material
      beyond the OpenAPI spec. Analysis shows 57.1% of APIs include external docs.
    message: External Docs MUST Be Defined
    severity: info
    given: $
    then:
      field: externalDocs
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-document-require-external-docs
  openapi-document-require-realistic-examples:
    description: API design SHOULD include real-like examples for request and response definitions.
    message: The {{property}} SHOULD include a real-like example. Add realistic examples to improve API usability.
    severity: info
    given: $..[?(@.example || @.examples)]
    then:
      field: example
      function: truthy
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-document-require-realistic-examples
  openapi-header-require-examples:
    description: Headers must include examples.
    message: '{{description}}; missing {{property}}'
    severity: info
    given: $..headers.*
    then:
      function: digitalocean-ensurePropertiesExample
    documentationUrl: https://apicommons.org/rules/#openapi-header-require-examples
  openapi-info-contact-require-email:
    description: Having a contact email address associated with the technical contract ensures that anyone who comes across
      the API has someone to email and get more information.
    message: Info MUST Have Contact Email
    severity: info
    given: $.info.contact
    then:
      field: email
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-info-contact-require-email
  openapi-info-contact-require-name:
    description: Having a contact name associated with the technical contract ensures that anyone who comes across the API
      knows who to contact.
    message: Info MUST Have Contact Name
    severity: info
    given: $.info.contact
    then:
      field: name
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-info-contact-require-name
  openapi-info-contact-require-url:
    description: Having a contact url associated with the technical contract ensures that anyone who comes across the API
      knows where to go to contact someone.
    message: Info MUST Have Contact URL
    severity: info
    given: $.info.contact
    then:
      field: url
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-info-contact-require-url
  openapi-info-description-length-limit:
    description: Having a restriction on the length of the API description expressed as the OpenAPI info description helps
      provide constraints for consumers when adding a description, and keeps portals, landing pages, documentation, and discovery
      results more consistent.
    message: Info description MUST be less than 500 characters.
    severity: info
    given: $.info
    then:
      field: description
      function: length
      functionOptions:
        max: 500
    documentationUrl: https://apicommons.org/rules/#openapi-info-description-length-limit
  openapi-info-description-no-eval-tag:
    description: Eval functions MUST not be included in the description of an API, keeping descriptions to just the text that
      is needed, and relying on the rest of the OpenAPI to describe what is possible.
    message: Info Description MUST NOT Have Eval Tag
    severity: info
    given: $.info
    then:
      field: description
      function: pattern
      functionOptions:
        notMatch: ^\b(<eval)\b
    documentationUrl: https://apicommons.org/rules/#openapi-info-description-no-eval-tag
  openapi-info-description-no-script-tag:
    description: Script tags MUST not be included in the description of an API, keeping descriptions to just the text that
      is needed, and relying on the rest of the OpenAPI to describe what is possible.
    message: Info Description MUST NOT Have Script Tag
    severity: info
    given: $.info
    then:
      field: description
      function: pattern
      functionOptions:
        notMatch: ^\b(<script)\b
    documentationUrl: https://apicommons.org/rules/#openapi-info-description-no-script-tag
  openapi-info-license-require-name:
    description: The license object should include a name property identifying the license type, such as Apache 2.0, MIT,
      or a proprietary license.
    message: Info License MUST Have Name
    severity: info
    given: $.info.license
    then:
      field: name
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-info-license-require-name
  openapi-info-license-require-url:
    description: The license object should include a URL linking to the full license text so API consumers can review the
      terms.
    message: Info License MUST Have URL
    severity: info
    given: $.info.license
    then:
      field: url
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-info-license-require-url
  openapi-info-require-contact-2:
    description: Having a contact object associated with the technical contract ensures that anyone who comes across the API
      has someone to contact and get more information.
    message: Info MUST Have Contact Object
    severity: info
    given: $.info
    then:
      field: contact
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-info-require-contact-2
  openapi-info-require-description:
    description: Info section is missing a description.
    message: Info section is missing a description.
    severity: info
    given: $.info
    then:
      field: description
      function: truthy
    formats:
    - oas3
    - oas3_1
    documentationUrl: https://apicommons.org/rules/#openapi-info-require-description
  openapi-info-require-license:
    description: Having a license defined in the info object clarifies the terms under which the API can be used. Analysis
      shows only 44.4% of APIs define a license, but it is essential for API governance and compliance.
    message: Info MUST Have License
    severity: info
    given: $.info
    then:
      field: license
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-info-require-license
  openapi-info-require-summary:
    description: 'The `#/info/x-summary` can be used to specify a brief, one-liner description of your API: this is very useful
      for catalog purposes (eg. this can be shown as your API subtitle in catalogs and developer portals). In OAS3.1 you can
      use the standard `#/info/summary` field.'
    message: 'API MUST have an one-liner #/info/x-summary field containing a brief description.'
    severity: info
    given: $
    then:
      field: info.x-summary
      function: truthy
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-info-require-summary
  openapi-info-require-terms-of-service:
    description: API MUST reference the URL of the Terms of Service in `#/info/termsOfService`.
    message: 'API MUST reference the URL of the Terms of Service  in #/info/termsOfService.'
    severity: info
    given: $
    then:
      field: info.termsOfService
      function: truthy
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-info-require-terms-of-service
  openapi-info-require-title:
    description: Having a intuitive and helpful title for your API using the OpenAPI info title is the first impression you
      will make on the consumers of your API.
    message: Info MUST Have Title
    severity: info
    given: $.info
    then:
      field: title
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-info-require-title
  openapi-info-title-max-length:
    description: Having a limitation on the length of the title for your API helps provide constraints for teams naming it,
      but also keep consistent with other APIs from across teams.
    message: Info Title MUST Be Less Than 50 Characters
    severity: info
    given: $.info
    then:
      field: title
      function: length
      functionOptions:
        max: 50
    documentationUrl: https://apicommons.org/rules/#openapi-info-title-max-length
  openapi-message-examples-form-complete-mocks:
    description: Message example must match params examples to form full mocks.
    message: '{{error}}'
    severity: info
    given: $.channels.*
    then:
      function: microcks-aas-verify-mocks
    formats:
    - aas2
    documentationUrl: https://apicommons.org/rules/#openapi-message-examples-form-complete-mocks
  openapi-message-require-examples:
    description: Message must have examples.
    message: Message must have examples
    severity: info
    given: $.channels.*.[publish,subscribe].message
    then:
      field: examples
      function: truthy
    formats:
    - aas2
    documentationUrl: https://apicommons.org/rules/#openapi-message-require-examples
  openapi-operation-deprecated-require-description:
    description: Deprecated operations should have a description explaining the deprecation and the migration path / successor.
    message: Deprecated operation should describe the deprecation and successor.
    given: $.paths[*][?(@ && @.deprecated == true)]
    severity: info
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-operation-deprecated-require-description
  openapi-operation-description-max-length:
    severity: info
    description: Having a length limitation for each description of each API operation helps apply constraints to how you
      describe your APIs, while helping drive consistency across APIs when it comes to search, documentation, and other ways
      an API is made available.
    message: Operation Description MUST Be Less Than 250 Characters
    given: $.paths.*[get,post,patch,put,delete]
    then:
    - field: description
      function: length
      functionOptions:
        max: 250
    documentationUrl: https://apicommons.org/rules/#openapi-operation-description-max-length
  openapi-operation-examples-form-complete-mocks:
    description: Response example must match required params examples to form full mocks.
    message: '{{error}}'
    severity: info
    given: $.paths.*.*
    then:
      function: microcks-oas-verify-mocks
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-operation-examples-form-complete-mocks
  openapi-operation-require-description:
    description: Having a paragraph or two description of each API operation helps API consumers understand what is possible
      with each API request.
    message: Operation MUST Have Description
    severity: info
    given: $.paths.*[get,post,patch,put,delete]
    then:
    - field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-operation-require-description
  openapi-operation-require-response:
    description: Check if every request has their respective responses.
    message: '{{error}}'
    severity: info
    given: $.paths.*
    then:
      function: trimble-check-for-response-in-every-request
    documentationUrl: https://apicommons.org/rules/#openapi-operation-require-response
  openapi-operation-require-summary:
    description: Having short and intuitive summary for each API operation helps API consumers understand what is possible
      with each API request.
    message: Operation MUST Have a Summary
    severity: info
    given: $.paths.*[get,post,patch,put,delete]
    then:
    - field: summary
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-operation-require-summary
  openapi-operation-require-tag:
    description: Having tags applied to each API operations helps organize and group APIs in portals, documentation, search,
      and other ways in which APIs are made available.
    message: Operations MUST Have Tags
    severity: info
    given: $.paths.*[get,post,patch,put,delete]
    then:
    - field: tags
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-operation-require-tag
  openapi-operation-summary-description-differ:
    description: Operation summaries and description should not match.
    message: '{{error}}'
    severity: info
    given:
    - $.paths[*].[get,post,put,patch,delete]
    then:
      function: trimble-operation-summary-description
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-operation-summary-description-differ
  openapi-operation-summary-max-length:
    severity: info
    description: Apply length constraints to the operation summary helps keep them consistent for publishing in documentation.
    message: Operation Summary MUST Be Less Than 50 Characters
    given: $.paths.*[get,post,patch,put,delete]
    then:
    - field: summary
      function: length
      functionOptions:
        max: 50
    documentationUrl: https://apicommons.org/rules/#openapi-operation-summary-max-length
  openapi-operation-summary-no-period:
    description: Operation summaries should not have a period, keeping the primary summary for each API as consistent as possible
      for publishing in documentation.
    message: Operation MUST Not Have a Period.
    severity: info
    given: $.paths[*][*].summary
    then:
      function: pattern
      functionOptions:
        notMatch: \.$
    documentationUrl: https://apicommons.org/rules/#openapi-operation-summary-no-period
  openapi-parameter-deprecated-require-description:
    description: Deprecated parameters should have a description explaining the deprecation and what to use instead.
    message: Deprecated parameter should describe the deprecation.
    given: $..parameters[?(@ && @.deprecated == true)]
    severity: info
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-deprecated-require-description
  openapi-parameter-description-max-length:
    severity: info
    description: Limiting the length of parameters description forces us to be more concise in how we describe each parameter,
      while keeping our documentation and other ways descriptions show up in discovery and portals more consistent.
    message: Parameters Description MUST Be Less Than 500 Characters
    given:
    - $.components.parameters.*
    - $.parameters.*
    then:
      field: summary
      function: length
      functionOptions:
        max: 500
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-description-max-length
  openapi-parameter-optional-include-examples:
    description: Optional param should have examples.
    message: Optional param should have examples
    severity: info
    given: $..parameters[?(@ && @.required != true)]
    then:
      field: examples
      function: truthy
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-optional-include-examples
  openapi-parameter-require-description:
    severity: info
    description: Having a parameters description provides more depth to what a parameter does and will be displayed via documentation,
      and other tooling used across the API lifecycle.
    message: Parameters MUST Have a Description
    given: $.paths.*.*.parameters.*
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-require-description
  openapi-parameter-require-examples:
    description: Parameters must include examples.
    message: '{{description}}; missing {{property}}'
    severity: info
    given: $..parameters.*
    then:
      function: xor
      functionOptions:
        properties:
        - example
        - examples
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-require-examples
  openapi-parameter-require-in:
    severity: info
    description: Providing an in property for parameters gets explicit about whether a parameter is in the path, query, or
      a header, making it clear to consumers where they can configure their request.
    message: Parameters In Property MUST Be Set
    given:
    - $.components.parameters.*
    - $.parameters.*
    then:
      field: in
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-require-in
  openapi-parameter-require-name:
    description: Providing a simple, intuitive, and consistent names for your parameters helps make it easier for API consumers
      to understand how they are able to configure their API requests.
    message: Parameters MUST Have a Name
    severity: info
    given:
    - $.components.parameters.*
    - $.parameters.*
    then:
      field: name
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-require-name
  openapi-parameter-require-required-flag:
    description: Providrequiredg an required property for parameters gets explicit about whether a parameter is required the
      path, query, or a header, making it clear to consumers where they can configure their request.
    message: Parameters Required Property MUST Be Set
    severity: info
    given:
    - $.components.parameters.*
    - $.parameters.*
    then:
      field: required
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-require-required-flag
  openapi-parameter-require-schema:
    formats:
    - oas3
    severity: info
    description: Parameters must always possess a schema to help define the format and shape of the parameter, setting expections
      with consumers about what should be passed in.
    message: Parameters MUST Have Schema
    given: $.components.parameters.*
    then:
      field: schema
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-require-schema
  openapi-parameter-require-schema-oas2:
    formats:
    - oas2
    severity: info
    description: 'In Swagger 2.0 only body parameters carry a `schema`; every reusable `in: body` parameter must possess a
      schema to define the shape of the payload, setting expectations with consumers about what should be passed in.'
    message: Body Parameters MUST Have Schema
    given: $.parameters[?(@.in=='body')]
    then:
      field: schema
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-require-schema-oas2
  openapi-parameter-required-require-examples:
    description: Required param must have examples.
    message: Required param must have examples
    severity: info
    given: $..parameters[?(@ && @.required == true)]
    then:
      field: examples
      function: truthy
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-parameter-required-require-examples
  openapi-path-params-declared-in-block:
    description: Check for the path parameter in the parameter block.
    message: '{{error}}'
    severity: info
    given: $.paths
    then:
      function: trimble-check-for-path-parameter
    documentationUrl: https://apicommons.org/rules/#openapi-path-params-declared-in-block
  openapi-path-success-response-require-description:
    description: Check if the response description is appropriate for all requests.
    message: '{{error}}'
    severity: info
    given: $.paths.*
    then:
      function: trimble-check-description-for-all-success-responses
    documentationUrl: https://apicommons.org/rules/#openapi-path-success-response-require-description
  openapi-request-content-require-examples:
    description: Request with content must have examples.
    message: Request with content must have examples
    severity: info
    given: $.paths..requestBody..content.*
    then:
      field: examples
      function: truthy
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-request-content-require-examples
  openapi-response-400-require-body:
    description: All 400 responses must include a response body.
    message: All 400 responses must include a response body.
    severity: info
    given:
    - $.paths.*.*.responses['400']
    then:
      field: content
      function: truthy
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-response-400-require-body
  openapi-response-content-require-examples:
    description: Response with content must have examples.
    message: Response with content must have examples
    severity: info
    given: $.paths..responses..content.*
    then:
      field: examples
      function: truthy
    formats:
    - oas3
    documentationUrl: https://apicommons.org/rules/#openapi-response-content-require-examples
  openapi-response-define-401:
    description: Responses should contain common response - 401 (unauthorized).
    message: '{{description}}. Missing {{property}}'
    severity: info
    given: $.paths..responses
    then:
      field: '401'
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-response-define-401
  openapi-response-define-404:
    description: Responses should contain common response - 404 (not found).
    message: '{{description}}. Missing {{property}}'
    severity: info
    given: $.paths[?(@property.match(/.*\/{.*}.*/))]..responses
    then:
      field: '404'
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-response-define-404
  openapi-response-error-require-description:
    description: Check if the response description is appropriate for all requests.
    message: '{{error}}'
    severity: info
    given: $.paths.*.*.responses
    then:
      function: trimble-check-description-for-all-error-responses
    documentationUrl: https://apicommons.org/rules/#openapi-response-error-require-description
  openapi-response-include-ratelimit-header:
    description: Response must include ratelimit-x headers.
    message: '{{description}}; missing {{property}}'
    severity: info
    given: $..responses.*
    then:
    - field: headers.ratelimit-limit
      function: truthy
    - field: headers.ratelimit-remaining
      function: truthy
    - field: headers.ratelimit-reset
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-response-include-ratelimit-header
  openapi-schema-deprecated-property-require-description:
    description: Deprecated schema properties should have a description explaining the deprecation and the replacement field.
    message: Deprecated property should describe the deprecation.
    given: $..properties[?(@ && @.deprecated == true)]
    severity: info
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-schema-deprecated-property-require-description
  openapi-schema-description-max-length:
    description: Schema should have a length limit applied, restricting how long schema descriptions can be, helping keep
      them concise and consistent.
    message: Schema Description MUST be Less Than 250 Characters
    severity: info
    given:
    - $.components.schemas.*
    - $.definitions.*
    then:
      field: description
      function: length
      functionOptions:
        max: 250
    documentationUrl: https://apicommons.org/rules/#openapi-schema-description-max-length
  openapi-schema-property-description-max-length:
    description: Schema property descriptions should have a length limit applied, applying constraints to writing descriptions,
      and keeping consistent across APIs.
    message: Schema Properties Description MUST Have 250 Characters
    severity: info
    given:
    - $.components.schemas.*.properties[?(@.type == 'string')]
    - $.definitions.*.properties[?(@.type == 'string')]
    then:
      field: description
      function: length
      functionOptions:
        max: 250
    documentationUrl: https://apicommons.org/rules/#openapi-schema-property-description-max-length
  openapi-schema-property-require-description:
    description: Schema properties should have descriptions that provide a narrative of the property contains, and how it
      can be used.
    message: Schema Properties MUST Have Description
    severity: info
    given:
    - $.components.schemas.*.properties[?(@.type == 'string')]
    - $.definitions.*.properties[?(@.type == 'string')]
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-schema-property-require-description
  openapi-schema-property-require-examples:
    description: Object properties must include examples.
    message: '{{description}}; {{property}}'
    severity: info
    given: $..properties..properties.*
    then:
      function: digitalocean-ensurePropertiesExample
    documentationUrl: https://apicommons.org/rules/#openapi-schema-property-require-examples
  openapi-schema-require-description:
    description: Schema should have descriptions that provide a narrative of what a schema object is for, and how it can be
      used, leaving examples to demonstrate what can actually be expected.
    message: Schema MUST Have a Description.
    severity: info
    given:
    - $.components.schemas.*
    - $.definitions.*
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-schema-require-description
  openapi-schema-require-info-object:
    description: Having an info object provides much of the metadata needed for the collection of APIs described in an OpenAPI.
    message: Info Object MUST Exist
    severity: info
    given: $
    then:
      field: info
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-schema-require-info-object
  openapi-security-jwt-scheme-require-description:
    severity: info
    description: 'Json Web Tokens RFC7519 is a compact, URL-safe means of representing claims to be transferred between two
      parties. JWT can be enclosed in encrypted or signed tokens like JWS and JWE. The [JOSE IANA registry](https://www.iana.org/assignments/jose/jose.xhtml)
      provides algorithms information. RFC8725 describes common pitfalls in the JWx specifications and in their implementations,
      such as: - the ability to ignore algorithms, eg. `{"alg": "none"}`; - using insecure algorithms like `RSASSA-PKCS1-v1_5`
      eg. `{"alg": "RS256"}`. An API using JWT should explicit in the `description` that the implementation conforms to RFC8725.
      ``` components: securitySchemes: JWTBearer: type: http scheme: bearer bearerFormat: JWT description: |- A bearer token
      in the format of a JWS and conformato to the specifications included in RFC8725. ```.'
    message: JWT usage should be detailed in `description` {{error}}.
    given:
    - $.[securitySchemes][?(@.bearerFormat=="jwt" || @.bearerFormat=="JWT")]
    then:
    - field: description
      function: truthy
    - field: description
      function: pattern
      functionOptions:
        match: .*RFC8725.*
    documentationUrl: https://apicommons.org/rules/#openapi-security-jwt-scheme-require-description
  openapi-security-oauth-scheme-require-description:
    severity: info
    description: 'Json Web Tokens RFC7519 is a compact, URL-safe means of representing claims to be transferred between two
      parties. JWT can be enclosed in encrypted or signed tokens like JWS and JWE. The [JOSE IANA registry](https://www.iana.org/assignments/jose/jose.xhtml)
      provides algorithms information. RFC8725 describes common pitfalls in the JWx specifications and in their implementations,
      such as: - the ability to ignore algorithms, eg. `{"alg": "none"}`; - using insecure algorithms like `RSASSA-PKCS1-v1_5`
      eg. `{"alg": "RS256"}`. An API using JWT should explicit in the `description` that the implementation conforms to RFC8725.
      ``` components: securitySchemes: JWTBearer: type: http scheme: bearer bearerFormat: JWT description: |- A bearer token
      in the format of a JWS and conformato to the specifications included in RFC8725. ```.'
    message: JWT usage should be detailed in `description` {{error}}.
    given:
    - $.[securitySchemes][?(@.type=="oauth2")]
    then:
    - field: description
      function: truthy
    - field: description
      function: pattern
      functionOptions:
        match: .*RFC8725.*
    documentationUrl: https://apicommons.org/rules/#openapi-security-oauth-scheme-require-description
  openapi-server-require-description:
    formats:
    - oas3
    description: Servers must have a description.
    message: Server {{path}} must have a description.
    severity: info
    given:
    - $.servers[*]
    - $.paths..servers
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#openapi-server-require-description
  apis-json-api-contact-include-email:
    description: The contact object in an APIs.json file allows for referencing the email address of a person or group. This
      property provides a convenient way for users to seek support for an API, using email as the default method to reach
      the team managing the API in production.
    message: API contact COULD have email.
    severity: info
    given: $.apis.*.contact.*
    then:
      field: email
      function: truthy
    documentationUrl: https://apicommons.org/rules/#apis-json-api-contact-include-email
  apis-json-api-contact-include-full-name:
    description: The contact object in an APIs.json file includes a full name (FN) property, which specifies the formatted
      text corresponding to the contact name in the vCard for an API. This provides a quick and clear way to assign a person,
      group, or other point of contact to an API for addressing questions and providing support.
    message: Contact Could Have FN
    severity: info
    given: $.apis.*.contact.*
    then:
      field: FN
      function: truthy
    documentationUrl: https://apicommons.org/rules/#apis-json-api-contact-include-full-name
  apis-json-api-include-about-page:
    description: This property ensures provides a reference to an about page, either for the company, organization, or government
      agency behind an API, or specifically about the domain, team, and the APIs they produce.
    message: Has About
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(about|About)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-include-about-page
  apis-json-api-include-contact:
    description: The contact object in an APIs.json file allows for associating a vCard that represents an individual or organizational
      entity. It includes common contact information such as a name, email, or other references, offering a standardized method
      for providing support for an API.
    message: API COULD have a contact.
    severity: info
    given: $.apis.*
    then:
      field: contact
      function: truthy
    documentationUrl: https://apicommons.org/rules/#apis-json-api-include-contact
  apis-json-api-property-require-road-map:
    description: This property ensures there is a reference to the road map for an API or for the entire API operations within
      domain, line of business, or teams.
    message: Has a Road Map
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(api-road-map|road-map|Roadmap|Road Map|RoadMap)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-require-road-map
  apis-json-api-property-require-sandbox:
    description: This property ensures that an API has a reference to a sandbox for individual APIs or as part of common properties,
      providing sandbox, synthetic data, and mock servers for use in making test requests.
    message: Has a Blog
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(sandbox|Sandbox)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-require-sandbox
  apis-json-api-property-require-security-page:
    description: This property ensures there is a URL to the security page, providing details about how security is handled
      for an API.
    message: Has Security Path
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(Security|SecurityTesting)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-require-security-page
  apis-json-api-property-require-support-email:
    description: This property ensures that an API has email support, providing a valid email address that can be used to
      get API support.
    message: Has Support Email
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(support-email|SupportEmail)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-require-support-email
  apis-json-api-property-require-support-issues-url:
    description: This property ensures that there are Git issues available to support an API, using the issues capability
      of GitHub, GitLab, or Bitbucket to support API consumers.
    message: Has Support Issues URL
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(SupportIssues|SupportGitHubIssues)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-require-support-issues-url
  apis-json-api-property-require-support-page:
    description: This property ensures that there is a support page available for an API, providing direct and in-direct support
      opportunities for each API or for entire API platform.
    message: Has Support Page
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(support|Support)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-require-support-page
  apis-json-api-property-require-team:
    description: This property ensures that there is a reference to the team behind an API, providing a reference to business
      and engineering stakeholders.
    message: Has a Team Defined
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(team|teams|Team|Teams)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-require-team
  apis-json-api-property-require-terms-of-service:
    description: This property ensures that an API has a reference to a terms of service, covering the legal side of using
      an API.
    message: Has an API Terms of Service
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(api-terms-of-service|terms-of-service|Terms of Service|TOS|TermsOfService)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-require-terms-of-service
  apis-json-api-property-require-use-cases:
    description: This property ensures there is a reference to the use cases for an API, helping align an API with the who,
      what, how, and why of putting an API to work.
    message: Has Use Cases
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(UseCases)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-require-use-cases
  apis-json-api-property-skill-require-versioning:
    description: This property ensures there is a reference to how APIs are versioned, providing a single place where teams
      can learn about how change is communicated.
    message: Has Versioning for API
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(versions|Versions|Versioning|versioning)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-skill-require-versioning
  apis-json-api-property-require-video:
    description: This property ensures there is a reference to a video page or channel for an API.
    message: Has Videos for API
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(videos|Videos)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-api-property-require-video
  apis-json-document-include-business-impact-canvas:
    description: This ensures that an API has had the APIOps Business Impact Canvas applied to the API, requiring that the
      canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.
    message: Has APIOps Cycles Business Impact Canvas
    severity: info
    given:
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(APIOpsBusinessImpactCanvas)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-document-include-business-impact-canvas
  apis-json-document-include-business-model-canvas:
    description: This ensures that an API has had the APIOps Business Model Canvas applied to the API, requiring that the
      canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.
    message: Has APIOps Cycles Business Model Canvas
    severity: info
    given:
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(APIOpsBusinessModelCanvas)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-document-include-business-model-canvas
  apis-json-document-include-capacity-canvas:
    description: This ensures that an API has had the APIOps Capacity Canvas applied to the API, requiring that the canvas
      is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.
    message: Has APIOps Cycles Capacity Canvas
    severity: info
    given:
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(APIOpsCapacityCanvas)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-document-include-capacity-canvas
  apis-json-document-include-customer-journey-canvas:
    description: This ensures that an API has had the APIOps Customer Journey Canvas applied to the API, requiring that the
      canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.
    message: Has APIOps Cycles Customer Journey Canvas
    severity: info
    given:
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(APIOpsCustomerJourneyCanvas)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-document-include-customer-journey-canvas
  apis-json-document-include-domain-canvas:
    description: This ensures that an API has had the APIOps Domain Canvas applied to the API, requiring that the canvas is
      present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.
    message: Has APIOps Cycles Domain Canvas
    severity: info
    given:
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(APIOpsDomainCanvas)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-document-include-domain-canvas
  apis-json-document-include-event-canvas:
    description: This ensures that an API has had the APIOps Event Canvas applied to the API, requiring that the canvas is
      present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.
    message: Has APIOps Cycles Event Canvas
    severity: info
    given:
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(APIOpsEventCanvas)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-document-include-event-canvas
  apis-json-document-include-locations-canvas:
    description: This ensures that an API has had the APIOps Locations Canvas applied to the API, requiring that the canvas
      is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.
    message: Has APIOps Cycles Locations Canvas
    severity: info
    given:
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(APIOpsLocationsCanvas)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-document-include-locations-canvas
  apis-json-document-include-rest-canvas:
    description: This ensures that an API has had the APIOps Locations Canvas applied to the API, requiring that the canvas
      is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.
    message: Has APIOps Cycles Locations Canvas
    severity: info
    given:
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(APIOpsRestCanvas)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-document-include-rest-canvas
  apis-json-document-include-value-proposition-canvas:
    description: This ensures that an API has had the APIOps Value Proposition Canvas applied to the API, requiring that the
      canvas is present in the repository and registered in the APIs.json index for the API, helping with discovery and governance.
    message: Has APIOps Cycles Value Proposition Canvas
    severity: info
    given:
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(APIOpsValuePropositionCanvas)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-document-include-value-proposition-canvas
  apis-json-schema-include-api-plan:
    description: This property provides a link to the dedicated plans page that applies to an API, providing information about
      access tiers, rate limits, and features available for an API as part of a wider API business plan.
    message: Has API Plans
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(api-plans|Plans)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-api-plan
  apis-json-schema-include-authentication-page:
    description: This property ensures that there is a human readable authentication page available that will provide what
      type of authentication is used and how it can be applied, as well as any services or tooling that API consumers can
      use to troubleshoot authentication with APIs.
    message: Has Authentication
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(Authentication)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-authentication-page
  apis-json-schema-include-blog:
    description: This property ensures that an API has a reference to a blog where anyone can find updates and other stories
      that will help keep API consumers and other stakeholders up to speed on what is happening with an API, and the larger
      operations.
    message: Has a Blog
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(blog|Blogs)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-blog
  apis-json-schema-include-blog-feed:
    description: This property ensures that blogs in support of APIs have an Atom or RSS feed of posts, allowing for the syndication
      of updates and information around individual APIs and the operations around them.
    message: Has a Blog Feed
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(blog-feed|BlogFeeds)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-blog-feed
  apis-json-schema-include-change-log:
    description: This property ensures that than an individual API or API operations possesses a change log that catalogs
      all the changes that have occurred in a recent time frame, with historical and version information available if possible.
    message: Has Change Log
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(api-change-log|change-log|Change Log|Changelog|ChangeLog)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-change-log
  apis-json-schema-include-documentation:
    description: This property ensures that there is documentation published for an API, and API consumers will have a set
      of human-readable instructions for onboarding and integrating with HTTP APIs in their applications.
    message: Has Documentation
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(documentation|Documentation)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-documentation
  apis-json-schema-include-examples:
    description: This property ensures that an API has a reference to a examples for individual APIs or as part of common
      properties, providing examples and synthentic data that can be used for APIs.
    message: Has a Blog
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(examples|Examples)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-examples
  apis-json-schema-include-feedback-email:
    description: This property ensures that there is an email available for API consumers to provide feedback.
    message: Has Feedback Email
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(feedback-email|FeedbackEmail)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-feedback-email
  apis-json-schema-include-feedback-issues-url:
    description: This property ensures there is a URL to Git issues specifically for providing feedback.
    message: Has Feedback Issues URL
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(FeedbackIssues|FeedbackGitHubIssues)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-feedback-issues-url
  apis-json-schema-include-getting-started:
    description: This property ensures that there is a getting started link available, providing a reference for API consumers
      to get started with an API is as few steps as possible.
    message: Has Getting Started
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(GettingStarted)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-getting-started
  apis-json-schema-include-github-organization:
    description: This property ensures that an API is associated with GitHub organization, providing the URL to where you
      can engage with the operations surrounding an API.
    message: Has a GitHub Organization
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(github-organization|GitHubOrganization)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-github-organization
  apis-json-schema-include-github-repository:
    description: This property ensures that an API possess a reference to a dedicated GitHub repository that is used to manage
      the Open, but also possible server and client code.
    message: Has a GitHub Repository
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(github-repository|GitHubRepository)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-github-repository
  apis-json-schema-include-insomnia-collection:
    description: This property defines an Insomnia collection available for each API, providing executable artifacts that
      can be used in the Insomnia client for making calls, and executing automation workflows.
    message: Has Insomnia Collection
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(RunInInsomnia)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-insomnia-collection
  apis-json-schema-include-interface-license:
    description: This property ensures that an API Commons interface license exists for an API, providing a machine-readable
      reference for an API, as well as data, backend, and front-end code.
    message: Has Interface License
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(api-license|License|license|InterfaceLicense)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-interface-license
  apis-json-schema-include-mock-server:
    description: This property ensures that an API has a reference to a mock servers for individual APIs or as part of common
      properties, providing mocked deployments of an API that can be used for making test API calls.
    message: Has a Mock Server
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(mocks|Mocks|MockServers)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-mock-server
  apis-json-schema-include-openapi-definition:
    description: This property ensures that there is an OpenAPI present for an API, providing the technical contract that
      describes the surface area of an API.
    message: Has An OpenAPI
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(openapi|OpenAPI)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-openapi-definition
  apis-json-schema-include-performance-testing:
    description: This property ensures that an API has performance testing in place, providing a URL to the performance testing,
      dashboard, or other resource.
    message: Has API Performance
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(Performance|PerformanceTesting)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-performance-testing
  apis-json-schema-include-postman-collection:
    description: This property ensures that an API has at least one Postman Collection associated with it, providing automation,
      tests, and other executable derivatives of an APIs OpenAPI.
    message: Has a Postman Collection
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(PostmanCollection)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-postman-collection
  apis-json-schema-include-pricing:
    description: This property provides a link to a pricing page that applies to an API, providing a breakdown of the costs
      associated with using an API.
    message: Has Pricing
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(Pricing)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-pricing
  apis-json-schema-include-privacy-policy:
    description: This property provides a link to the privacy policy for an API, providing the legal details of how privacy
      is approached for each API.
    message: Has an API Privacy Policy
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(api-privacy-policy|privacy-policy|Privacy|Privacy Policy|PrivacyPolicy)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-privacy-policy
  apis-json-schema-include-questions-issues-url:
    description: This property ensures that an API has a dedicated link to Git issues for asking questions.
    message: Has Questions Issues URL
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(QuestionsIssues|QuestionsGitHubIssues)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-questions-issues-url
  apis-json-schema-include-rate-limit-reference:
    description: This property ensures there is an API rate limits reference associated with API, ensuring the rate limits
      applied to an API are clearly communicated.
    message: Has an API Terms of Services
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(rate-limits|RateLimits|Rate Limits)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-rate-limit-reference
  apis-json-schema-include-version-comparison:
    description: This property ensures that an API has the ability to compare two different versions of an API and see what
      the difference are between them.
    message: Has an API Comparison
    severity: info
    given:
    - $.apis.*.properties.*
    - $.common.*
    then:
    - field: type
      function: pattern
      functionOptions:
        notMatch: \b(compare|Compare)\b
    documentationUrl: https://apicommons.org/rules/#apis-json-schema-include-version-comparison
  asyncapi-channel-asyncapi-require-description:
    description: Channels should have a description of the messages they carry.
    message: Channel should have a description.
    given: $.channels[*]
    severity: info
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#asyncapi-channel-asyncapi-require-description
  asyncapi-component-asyncapi-message-require-name:
    description: Messages should declare a name.
    message: Message should declare a name.
    given: $.components.messages[*]
    severity: info
    then:
      field: name
      function: truthy
    documentationUrl: https://apicommons.org/rules/#asyncapi-component-asyncapi-message-require-name
  asyncapi-component-asyncapi-message-require-title:
    description: Messages should declare a human-readable title.
    message: Message should declare a title.
    given: $.components.messages[*]
    severity: info
    then:
      field: title
      function: truthy
    documentationUrl: https://apicommons.org/rules/#asyncapi-component-asyncapi-message-require-title
  asyncapi-info-asyncapi-require-title:
    description: The API should declare an info.title.
    message: AsyncAPI info should have a title.
    given: $.info
    severity: info
    then:
      field: title
      function: truthy
    documentationUrl: https://apicommons.org/rules/#asyncapi-info-asyncapi-require-title
  asyncapi-operation-asyncapi-require-summary:
    description: Operations should have a short summary.
    message: Operation should have a summary.
    given: $.operations[*]
    severity: info
    then:
      field: summary
      function: truthy
    documentationUrl: https://apicommons.org/rules/#asyncapi-operation-asyncapi-require-summary
  asyncapi-operation-asyncapi-require-tag:
    description: Operations should declare tags for grouping.
    message: Operation should declare tags.
    given: $.operations[*]
    severity: info
    then:
      field: tags
      function: truthy
    documentationUrl: https://apicommons.org/rules/#asyncapi-operation-asyncapi-require-tag
  asyncapi-schema-asyncapi-property-require-description:
    description: Schema properties should be documented with a description.
    message: Schema property should have a description.
    given: $.components.schemas[*].properties[*]
    severity: info
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#asyncapi-schema-asyncapi-property-require-description
  asyncapi-server-asyncapi-require-description:
    description: Servers should have a description identifying the environment/broker.
    message: Server should have a description.
    given: $.servers[*]
    severity: info
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#asyncapi-server-asyncapi-require-description
  arazzo-info-arazzo-require-title:
    description: The Arazzo description should declare an info.title.
    message: Arazzo info should have a title.
    given: $.info
    severity: info
    then:
      field: title
      function: truthy
    documentationUrl: https://apicommons.org/rules/#arazzo-info-arazzo-require-title
  arazzo-source-arazzo-description-require-name:
    description: Each source description should declare a name used to reference it from steps.
    message: Source description should have a name.
    given: $.sourceDescriptions[*]
    severity: info
    then:
      field: name
      function: truthy
    documentationUrl: https://apicommons.org/rules/#arazzo-source-arazzo-description-require-name
  json-schema-document-require-description:
    description: The `description` property should be present.
    message: description should be present
    severity: info
    given: $
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#json-schema-document-require-description
  json-schema-document-require-title:
    description: The `title` property should be present.
    message: title should be present
    severity: info
    given: $
    then:
      field: title
      function: truthy
    documentationUrl: https://apicommons.org/rules/#json-schema-document-require-title
  json-schema-schema-property-require-description:
    description: The `description` property of each property should be present.
    message: description should be present
    severity: info
    given: $.properties[*]
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#json-schema-schema-property-require-description
  json-structure-schema-json-structure-property-require-description:
    description: Properties should be documented with a description.
    message: Property should have a description.
    given: $.properties[*]
    severity: info
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#json-structure-schema-json-structure-property-require-description
  mcp-document-mcp-description-meaningful:
    description: The server description should be specific (at least 40 characters) so agents can decide when to use it.
    message: MCP description should be at least 40 characters.
    given: $.description
    severity: info
    then:
      function: schema
      functionOptions:
        schema:
          type: string
          minLength: 40
    documentationUrl: https://apicommons.org/rules/#mcp-document-mcp-description-meaningful
  mcp-document-require-description:
    description: The `description` property should be present.
    message: description should be present
    severity: info
    given: $
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#mcp-document-require-description
  mcp-document-require-instructions:
    description: The `instructions` property should be present.
    message: instructions should be present
    severity: info
    given: $
    then:
      field: instructions
      function: truthy
    documentationUrl: https://apicommons.org/rules/#mcp-document-require-instructions
  plans-document-require-description:
    description: The `description` property should be present.
    message: description should be present
    severity: info
    given: $
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#plans-document-require-description
  plans-plan-features-non-empty:
    description: If a plan lists features, the list should not be empty.
    message: Plan features should not be empty.
    given: $.plans[*].features
    severity: info
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1
    documentationUrl: https://apicommons.org/rules/#plans-plan-features-non-empty
  plans-plan-require-description:
    description: The `description` property of each plan should be present.
    message: description should be present
    severity: info
    given: $.plans[*]
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#plans-plan-require-description
  plans-plan-require-features:
    description: The `features` property of each plan should be present.
    message: features should be present
    severity: info
    given: $.plans[*]
    then:
      field: features
      function: truthy
    documentationUrl: https://apicommons.org/rules/#plans-plan-require-features
  rate-limits-document-require-description:
    description: The `description` property should be present.
    message: description should be present
    severity: info
    given: $
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#rate-limits-document-require-description
  finops-document-finops-require-description:
    description: The `description` property should be present.
    message: description should be present
    severity: info
    given: $
    then:
      field: description
      function: truthy
    documentationUrl: https://apicommons.org/rules/#finops-document-finops-require-description
  agent-skill-skill-body-present:
    description: A skill must have body content, not just frontmatter — the body is the instruction set the agent actually
      follows.
    message: A skill must have body content.
    severity: info
    given: $.words
    then:
      function: schema
      functionOptions:
        schema:
          type: integer
          minimum: 1
    documentationUrl: https://apicommons.org/rules/#agent-skill-skill-body-present