---
rules:
  openapi-security-schemes-error:
    description: Having components security schemes ensures that the security
      definition for an API have been standardized and are able to be applied
      across APIs. You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#security-scheme-object">security
      schemes object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/security.html"
      target="_blank">OpenAPI security</a> via API Evangelist guidance.
    message: Components MUST Have a Security Schemes
    severity: error
    given: $.components
    then:
      field: securitySchemes
      function: truthy

  openapi-components-parameters-error:
    description: Having a components parameters object allows all parameters used
      across an API to be centralized, allowing for reuse and easier governance
      of the parameters used to configure API requests. You can find details
      about the <a
      href="https://spec.openapis.org/oas/latest.html#parameter-object">parameters
      object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/parameters.html"
      target="_blank">OpenAPI parameters</a> via API Evangelist guidance.
    message: Components MUST Have a Parameters Property
    severity: error
    given: $.components
    then:
      field: parameters
      function: truthy
  openapi-components-parameters-name-error:
    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. You can find details about the
      <a
      href="https://spec.openapis.org/oas/latest.html#parameter-object">parameters
      object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-parameter-names.html"
      target="_blank">OpenAPI parameter names</a> via API Evangelist guidance.
    message: Parameters MUST Have a Name
    severity: error
    given: $.components.parameters.*
    then:
      field: name
      function: truthy

  openapi-components-examples-error:
    description: Utilizing an example object in the centralized OpenAPI components
      library helps make examples reusable across API requests and responses.
      Having examples centralized makes it easier to define, use, but also
      govern and analyze the examples provided across APIs. You can find details
      about the <a
      href="https://spec.openapis.org/oas/latest.html#components-object">components
      example object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/components-examples.html"
      target="_blank">components examples</a> via API Evangelist guidance.
    message: Components MUST Have a Examples Property
    severity: error
    given: $.components
    then:
      field: examples
      function: truthy

  openapi-components-schemas-error:
    description: Utilizing the schema object in the centralized OpenAPI components
      library helps make schema reusable across API requests and responses.
      Having schema centralized makes it easier to define, use, but also govern
      and analyze the schema provided across APIs. You can find details about
      the <a
      href="https://spec.openapis.org/oas/latest.html#components-object">components
      example object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/components-schema.html"
      target="_blank">components examples</a> via API Evangelist guidance.
    message: Components MUST Have a Schema Property
    severity: error
    given: $.components
    then:
      field: schemas
      function: truthy

  openapi-components-headers-error:
    description: Utilizing the headers object in the centralized OpenAPI components
      library helps make headers reusable across API requests and responses.
      Having headers centralized makes it easier to define, use, but also govern
      and analyze the headers provided across APIs. You can find details about
      the <a
      href="https://spec.openapis.org/oas/latest.html#components-object">components
      example object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/components-headers.html"
      target="_blank">components examples</a> via API Evangelist guidance.
    message: Components MUST Have a Headers Property
    severity: error
    given: $.components
    then:
      field: headers
      function: truthy

  openapi-info-error:
    description: Having an info object provides much of the metadata needed for the
      collection of APIs described in an OpenAPI. Title, description, tags,
      version, and other properties are available for describing what value APIs
      provide to consumers. You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#info-object">info object
      for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/info.html"
      target="_blank">info object</a> via API Evangelist guidance.
    message: Info Object MUST Exist
    severity: error
    given: $
    then:
      field: info
      function: truthy

  openapi-info-title-error:
    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. Your title should be about what the API does and not how you built
      the API, focusing on how the consumers will see things. You can find
      details about the <a
      href="https://spec.openapis.org/oas/latest.html#info-object">info object
      for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/info-title.html"
      target="_blank">API title</a> via API Evangelist guidance.
    message: Info MUST Have Title
    severity: error
    given: $.info
    then:
      field: title
      function: truthy
  openapi-operation-security-definitions-error:
    description: Each API operation should have a security definition referencing
      the central security scheme express for an OpenAPI. This property
      configures the gateway for any API being published. You can find details
      about the <a
      href="https://spec.openapis.org/oas/latest.html#security-scheme-object">security
      schemes object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-security.html"
      target="_blank">operation security</a> via API Evangelist guidance.
    message: Operations MUST Have a Security Definition
    severity: error
    given: $.paths.*[get,post,patch,put,delete]
    then:
      field: security
      function: truthy
  openapi-operations-description-error:
    description: Having a paragraph or two description of each API operation helps
      API consumers understand what is possible with each API request. Keep the
      description as narrative and plain languge as possible, relying on
      examples and other operation properties to share the full story. You can
      find details about the <a
      href="https://spec.openapis.org/oas/latest.html#operation-object">operation
      object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-description.html"
      target="_blank">operation descriptions</a> via API Evangelist guidance.
    message: Operation MUST Have Description
    severity: error
    given: $.paths.*[get,post,patch,put,delete]
    then:
      - field: description
        function: truthy

  openapi-operations-operation-ids-error:
    description: Operation identifiers provide a unique way to identify each
      individual API, which then used for SDK generation and other automation.
      The operation identifier for each of your APIs should be unique across
      your operations. You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#operation-object">operation
      object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-identifier.html"
      target="_blank">operation identifier</a> via API Evangelist guidance.
    message: Operation MUST Have Identifier
    severity: error
    given: $.paths.*[get,post,patch,put,delete]
    then:
      - field: operationId
        function: truthy
  openapi-operations-operation-ids-camel-case-error:
    description: Operation identifiers provide a unique way to identify each
      individual API, and requiring them to have consistent casing reduces
      friction when generating SDKs and automating around APIs. You can find
      details about the <a
      href="https://spec.openapis.org/oas/latest.html#operation-object">operation
      object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-identifier.html"
      target="_blank">operation identifier</a> via API Evangelist guidance.
    message: Operation Identifier MUST Be camelCase
    severity: error
    given: $.paths.*.*.operationId
    then:
      function: casing
      functionOptions:
        type: camel


  openapi-operations-summary-error:
    description: Having short and intuitive summary for each API operation helps API
      consumers understand what is possible with each API request. Keep the
      summary reflecting a combination of nouns and verbs that reflect what is
      possible with each API. You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#operation-object">operation
      object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-description.html"
      target="_blank">operation summaries</a> via API Evangelist guidance.
    message: Operation MUST Have a Summary
    severity: error
    given: $.paths.*[get,post,patch,put,delete]
    then:
      - field: summary
        function: truthy
  openapi-operations-tags-error:
    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. Each API should have at least one tag available describing
      what the API does for a consumer. You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#tag-object">tag object for
      OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-tags.html"
      target="_blank">operation tags</a> via API Evangelist guidance.
    message: Operations MUST Have Tags
    severity: error
    given: $.paths.*[get,post,patch,put,delete]
    then:
      - field: tags
        function: truthy
  openapi-operations-tags-one-error:
    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. Each API should have at least one tag available describing
      what the API does for a consumer. You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#tag-object">tag object for
      OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-tags.html"
      target="_blank">operation tags</a> via API Evangelist guidance.
    message: MUST Be At Least One Operation Tag
    given: $.paths.*[get,post,patch,put,delete]
    severity: error
    then:
      field: tags
      function: length
      functionOptions:
        min: 1
  openapi-operations-tags-upper-case-error:
    description: Having the first letter of each word applied as a tag to API
      operations helps keep a consistent layout when published via search,
      documentation, and other ways APIs are made available. You can find
      details about the <a
      href="https://spec.openapis.org/oas/latest.html#tag-object">tag object for
      OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-tags.html"
      target="_blank">operation tags</a> via API Evangelist guidance.
    message: Operation Tag Names MUST Have First Letter in Each Word Capitalized
    severity: error
    given: $.paths.*[get,post,patch,put,delete].tags.*
    then:
      function: pattern
      functionOptions:
        match: "[A-Z]\\w*"

  openapi-request-body-have-schema-error:
    description: POST, PUT, and PATCH request bodies should have schema defined,
      providing more detail on what the structure of the API request body should
      be. You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#request-body-object">request
      body object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-request-bodies-schema.html"
      target="_blank">request bodies</a> via API Evangelist guidance.
    message: Request Body Schema
    given: $.paths.*.*.requestBody.content.*
    severity: error
    then:
      field: schema
      function: truthy
      
  openapi-request-body-have-examples-error:
    description: POST, PUT, and PATCH request bodies should have examples, providing
      one or more examples of what should be submitted for different types of
      requests. You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#request-body-object">request
      body object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-request-bodies-schema.html"
      target="_blank">request bodies examples</a> via API Evangelist guidance.
    message: Request Bodies MUST Have Examples
    given: $.paths.*.*.requestBody.content.*
    severity: error
    then:
      field: examples
      function: truthy
  openapi-request-body-have-examples-ref-error:
    description: POST, PUT, and PATCH request bodies should have examples using
      references to centralized component examples, providing one or more
      examples of what should be submitted for different types of requests. You
      can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#request-body-object">request
      body object for OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/operation-request-bodies-schema.html"
      target="_blank">request bodies examples</a> via API Evangelist guidance.
    message: Request Bodies MUST Use Examples Reference
    severity: error
    given: $.paths.*.*.requestBody.content.*.examples
    then:
      field: $ref
      function: falsy

  openapi-tags-description-error:
    description: Tags used as part of an OpenAPI should have descriptions, providing
      more of a narrative behind what a tag means when it is applied to an API.
      You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#tag-object">tag object for
      OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/tags.html"
      target="_blank">tags</a> via API Evangelist guidance.
    message: Tags MUST Have a Description
    given: $.tags[*]
    severity: error
    then:
      field: description
      function: truthy
  openapi-tags-name-error:
    description: Tags used as part of an OpenAPI should have names, providing a
      simple key word or phrase that represents the tag being applied to APIs.
      You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#tag-object">tag object for
      OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/tags.html"
      target="_blank">tags</a> via API Evangelist guidance.
    message: Tags MUST Have a Name
    given: $.tags[*]
    severity: error
    then:
      field: name
      function: truthy
  openapi-tags-object-error:
    description: There needs to be a central tags object applied to the OpenAPI,
      providing central tags that can be applied across all operations within an
      OpenAPI. You can find details about the <a
      href="https://spec.openapis.org/oas/latest.html#tag-object">tag object for
      OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/tags.html"
      target="_blank">tags</a> via API Evangelist guidance.
    message: OpenAPIs MUST Have a Tag Object
    given: $
    severity: error
    then:
      field: tags
      function: truthy
  openapi-tags-one-error:
    description: There needs to be at least one tag applied to an OpenAPI, providing
      a key word or phrase that can be applied to API operations. You can find
      details about the <a
      href="https://spec.openapis.org/oas/latest.html#tag-object">tag object for
      OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/tags.html"
      target="_blank">tags</a> via API Evangelist guidance.
    message: MUST Be At Least One Tag
    given: $
    severity: error
    then:
      field: tags
      function: length
      functionOptions:
        min: 1
  openapi-tags-upper-case-error:
    description: The first letter of each word in a tag being applied to APIs needs
      to be capitalized, keeping the tags being applied across APIs the same
      look and feel for organizing and publishing to documentation. You can find
      details about the <a
      href="https://spec.openapis.org/oas/latest.html#tag-object">tag object for
      OpenAPI</a>, and explore <a
      href="https://guidance.apievangelist.com/guidance/openapi/tags.html"
      target="_blank">tags</a> via API Evangelist guidance.
    message: Tag Names MUST Have First Letter in Each Word Capitalized
    severity: error
    given: $.tags.*.name
    then:
      function: pattern
      functionOptions:
        match: "[A-Z]\\w*"

  openapi-response-examples-error:
    description: >-
      Have examples to show one or many
      examples of responses for different types of API requests
    message: Response MUST Have Examples
    given: $.paths[*].get.responses.200.content["application/json"]
    severity: error
    then:
      - field: examples
        function: truthy

  openapi-response-examples-ref-error:
    description: >-
      Have example references to show one or
      many examples of responses for different types of API requests
    message: Responses MUST Use Examples Reference
    severity: error
    given: $.paths[*].get.responses.200.content["application/json"].examples.*['$ref']
    then:
      function: truthy   

  openapi-response-schemas-error:
    description: >-
      Have schemas to show one or many
      schemas of responses for different types of API requests
    message: Response MUST Have Schema
    severity: error
    given: $.paths[*].*.responses.200.content["application/json"]
    severity: error
    then:
      - field: schema
        function: truthy  

  openapi-response-schemas-ref-error:
    description: >-
      Have example references to show one or
      many schemas of responses for different types of API requests
    message: Responses MUST Use Schema Reference
    severity: error
    given: $.paths[*].*.responses.200.content["application/json"].schema['$ref']
    then:
      function: truthy      