ruleset-all.yaml

description: Every single rule that is built-in to vacuum. The full monty
documentationUrl: https://quobix.com/vacuum/rulesets/all
rules:
  component-description:
    category:
      description: Documentation is really important, in OpenAPI, just about everything can and should have a description. This set of rules checks for absent descriptions, poor quality descriptions (copy/paste), or short descriptions.
      id: descriptions
      name: Descriptions
    description: Component description check
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Components are the inputs and outputs of a specification. A user needs to be able to understand each component and what id does. Descriptions are critical to understanding components. Add a description!
    id: component-description
    recommended: true
    resolved: true
    severity: warn
    then:
      function: oasComponentDescriptions
    type: validation
  contact-properties:
    category:
      description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
      id: information
      name: Contract Information
    description: Contact details are incomplete
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Complete specification contact information. Fill in the 'name', 'url' and 'email'properties so consumers of the spec know how to reach you.
    id: contact-properties
    resolved: true
    severity: info
    then:
      function: infoContactProperties
    type: validation
  description-duplication:
    category:
      description: Documentation is really important, in OpenAPI, just about everything can and should have a description. This set of rules checks for absent descriptions, poor quality descriptions (copy/paste), or short descriptions.
      id: descriptions
      name: Descriptions
    description: Description duplication check
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Descriptions are only useful, if they are meaningful. If a description is meaningful, then it won't be something you copy and paste. Please don't duplicate descriptions, make them deliberate and meaningful.
    id: description-duplication
    recommended: true
    severity: info
    then:
      function: oasDescriptionDuplication
    type: validation
  duplicate-paths:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Paths cannot be duplicated; only the last definition will be kept.
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Duplicate path definitions found in your OpenAPI specification. In YAML, duplicate keys are allowed, but only the last occurrence is used. This means earlier path definitions are silently ignored, which can lead to missing API endpoints in your specification.
    id: duplicate-paths
    recommended: true
    severity: error
    then:
      function: duplicatePaths
    type: validation
  duplicated-entry-in-enum:
    category:
      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
      id: schemas
      name: Schemas
    description: Enum values must not have duplicate entry
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Enums need to be unique, you can't duplicate them in the same definition. Please remove the duplicate value.
    id: duplicated-entry-in-enum
    recommended: true
    severity: error
    then:
      function: duplicatedEnum
    type: validation
  info-contact:
    category:
      description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
      id: information
      name: Contract Information
    description: Info section is missing contact details
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: The specification 'info' section doesn't contain a 'contact' object. Add it and make sure to complete 'name', 'url' and 'email' properties so consumers of the spec know how to reach you.
    id: info-contact
    resolved: true
    severity: warn
    then:
      function: infoContact
    type: validation
  info-description:
    category:
      description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
      id: information
      name: Contract Information
    description: Info section is missing a description
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: The 'info' section is missing a description, surely you want people to know what this spec is all about, right?
    id: info-description
    recommended: true
    resolved: true
    severity: error
    then:
      function: infoDescription
    type: validation
  info-license:
    category:
      description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
      id: information
      name: Contract Information
    description: Info section should contain a license
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $.info
    howToFix: The 'info' section is missing a 'license' object. Please add an appropriate one
    id: info-license
    resolved: true
    severity: info
    then:
      function: infoLicense
    type: style
  info-license-spdx:
    category:
      description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
      id: information
      name: Contract Information
    description: License section cannot contain both an identifier and a URL, they are mutually exclusive.
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: A license can contain either a URL or an SPDX identifier, but not both, They are mutually exclusive and cannot both be present. Choose one or the other
    id: info-license-spdx
    recommended: true
    resolved: true
    severity: error
    then:
      function: infoLicenseURLSPDX
    type: validation
  license-url:
    category:
      description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
      id: information
      name: Contract Information
    description: License should contain a URL
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $.info.license
    howToFix: The 'info' section license URL is missing. If you add a license, you need to make sure  that you link to an appropriate URL for that license.
    id: license-url
    resolved: true
    severity: info
    then:
      function: infoLicenseUrl
    type: style
  migrate-zally-ignore:
    category:
      description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
      id: validation
      name: Validation
    description: x-zally-ignore keys should be migrated to x-lint-ignore for compatibility with vacuum
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Migrate x-zally-ignore directives to vacuum's x-lint-ignore. Rename the key to x-lint-ignore and update the ignored rule id to the vacuum equivalent rule.
    id: migrate-zally-ignore
    recommended: true
    resolved: true
    severity: warn
    then:
      function: migrateZallyIgnore
    type: validation
  no-$ref-siblings:
    category:
      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
      id: schemas
      name: Schemas
    description: $ref values cannot be placed next to other properties (like a description)
    formats:
      - oas2
      - oas3_0
    given: $
    howToFix: $ref values must not be placed next to sibling nodes, There should only be a single node  when using $ref. A common mistake is adding 'description' next to a $ref. This is wrong. remove all siblings!
    id: no-$ref-siblings
    recommended: true
    severity: error
    then:
      function: refSiblings
    type: validation
  no-ambiguous-paths:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Paths need to resolve unambiguously from one another
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Paths must all resolve unambiguously, they can't be confused with one another (/{id}/ambiguous and /ambiguous/{id} are the same thing. Make sure every path and the variables used are unique and do conflict with one another. Check the ordering of variables and the naming of path segments.
    id: no-ambiguous-paths
    recommended: true
    resolved: true
    severity: error
    then:
      function: noAmbiguousPaths
    type: validation
  no-eval-in-markdown:
    category:
      description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
      id: validation
      name: Validation
    description: Markdown descriptions must not have `eval()` statements'
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Remove all references to 'eval()' in the description. These can be used by malicious actors to embed code in contracts that is then executed when read by a browser.
    id: no-eval-in-markdown
    recommended: true
    resolved: true
    severity: error
    then:
      function: noEvalDescription
      functionOptions:
        pattern: eval\(
    type: validation
  no-http-verbs-in-path:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Path segments must not contain an HTTP verb
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: When HTTP verbs (get/post/put etc) are used in path segments, it muddies the semantics of REST and creates a confusing and inconsistent experience. It's highly recommended that verbs are not used in path segments. Replace those HTTP verbs with more meaningful nouns.
    id: no-http-verbs-in-path
    recommended: true
    severity: warn
    then:
      function: noVerbsInPath
    type: style
  no-request-body:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: HTTP GET and DELETE should not accept request bodies
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Remove 'requestBody' from HTTP GET and DELETE methods
    id: no-request-body
    recommended: true
    severity: warn
    then:
      function: noRequestBody
    type: style
  no-script-tags-in-markdown:
    category:
      description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
      id: validation
      name: Validation
    description: Markdown descriptions must not have `<script>` tags'
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Remove all references to '<script>' tags from the description. These can be used by malicious actors to load remote code if the spec is being parsed by a browser.
    id: no-script-tags-in-markdown
    recommended: true
    resolved: true
    severity: error
    then:
      function: noEvalDescription
      functionOptions:
        pattern: <script
    type: validation
  no-unnecessary-combinator:
    category:
      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
      id: schemas
      name: Schemas
    description: Schema combinators (allOf, anyOf, oneOf) with only one item should be replaced with the item directly.
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Schema combinators (allOf, anyOf, oneOf) with only a single item are unnecessary and should be replaced with the item directly for cleaner, more readable schemas.
    id: no-unnecessary-combinator
    recommended: true
    resolved: true
    severity: warn
    then:
      function: oasUnnecessaryCombinator
    type: style
  nullable-enum-contains-null:
    category:
      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
      id: schemas
      name: Schemas
    description: Nullable enums must explicitly include null in the enum array
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: 'When a schema is marked as nullable (using ''nullable: true'' in OpenAPI 3.0 or ''type: [<type>, "null"]'' in OpenAPI 3.1), and also defines an enum array, the enum must explicitly contain a null value (without quotes). Simply marking the schema as nullable is not enough - the null value must be listed in the enum array. Add null (unquoted) to your enum array, for example: enum: [active, inactive, null]'
    id: nullable-enum-contains-null
    recommended: true
    resolved: true
    severity: warn
    then:
      function: nullableEnum
    type: validation
  oas-missing-type:
    category:
      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
      id: schemas
      name: Schemas
    description: All schemas and their properties should have a type field (unless using enum, const, or a composition)
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: "Add a `type` field to all schemas and properties. Valid types are: string, number, integer, boolean, array, object, or null."
    id: oas-missing-type
    recommended: true
    severity: info
    then:
      function: missingType
    type: validation
  oas-schema-check:
    category:
      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
      id: schemas
      name: Schemas
    description: All document schemas must have a valid type defined
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Make sure each schema has a value type defined. Without a type, the schema is useless
    id: oas-schema-check
    recommended: true
    severity: error
    then:
      function: schemaTypeCheck
    type: validation
  oas3-api-servers:
    category:
      description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications.
      id: validation
      name: Validation
    description: Check for valid API servers definition
    formats:
      - oas3
    given: $
    howToFix: Ensure server URIs are correct and valid, check the schemes, ensure descriptions are complete.
    id: oas3-api-servers
    recommended: true
    severity: warn
    then:
      function: oasAPIServers
    type: validation
  oas3-example-external-check:
    category:
      description: Examples help consumers understand how API calls should look. They are really important for automated tooling for mocking and testing. These rules check examples have been added to component schemas, parameters and operations. These rules also check that examples match the schema and types provided.
      id: examples
      name: Examples
    description: Examples cannot use both `value` and `externalValue` together.
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Examples are critical for consumers to be able to understand schemas and models defined by the spec. Without examples, developers can't understand the type of data the API will return in real life. Examples are turned into mocks and can provide a rich testing capability for APIs. Add detailed examples everywhere!
    id: oas3-example-external-check
    recommended: true
    severity: warn
    then:
      function: oasExampleExternal
    type: validation
  oas3-host-not-example:
    category:
      description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
      id: information
      name: Contract Information
    description: Server URL should not point at example.com
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $.servers[*].url
    howToFix: Remove 'example.com from the 'servers' URL, it's not going to work.
    id: oas3-host-not-example
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: example\.com
    type: style
  oas3-missing-example:
    category:
      description: Examples help consumers understand how API calls should look. They are really important for automated tooling for mocking and testing. These rules check examples have been added to component schemas, parameters and operations. These rules also check that examples match the schema and types provided.
      id: examples
      name: Examples
    description: Ensure everything that can have an example, contains one
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Examples are critical for consumers to be able to understand schemas and models defined by the spec. Without examples, developers can't understand the type of data the API will return in real life. Examples are turned into mocks and can provide a rich testing capability for APIs. Add detailed examples everywhere!
    id: oas3-missing-example
    recommended: true
    severity: warn
    then:
      function: oasExampleMissing
    type: validation
  oas3-no-$ref-siblings:
    category:
      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
      id: schemas
      name: Schemas
    description: "`$ref` values cannot be placed next to other properties, except `description` and `summary`"
    formats:
      - oas3_1
    given: $
    howToFix: $ref values must not be placed next to sibling nodes, except `description` and `summary` nodes.  This is wrong. remove all additional siblings!
    id: oas3-no-$ref-siblings
    recommended: true
    severity: error
    then:
      function: oasRefSiblings
    type: validation
  oas3-operation-security-defined:
    category:
      description: Security plays a central role in RESTful APIs. These rules make sure that the correct definitions have been used and put in the right places.
      id: security
      name: Security
    description: "`security` values must match a scheme defined in components.securitySchemes"
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: When defining security values for operations, you need to ensure they match the globally defined security schemes. Check $.components.securitySchemes to make sure your values align.
    id: oas3-operation-security-defined
    recommended: true
    resolved: true
    severity: error
    then:
      function: oasOpSecurityDefined
      functionOptions:
        schemesPath: $.components.securitySchemes
    type: validation
  oas3-parameter-description:
    category:
      description: Documentation is really important, in OpenAPI, just about everything can and should have a description. This set of rules checks for absent descriptions, poor quality descriptions (copy/paste), or short descriptions.
      id: descriptions
      name: Descriptions
    description: Parameter description checks
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: All parameters should have a description. Descriptions are critical to understanding how an API works correctly. Please add a description to all parameters.
    id: oas3-parameter-description
    recommended: true
    resolved: true
    severity: warn
    then:
      function: oasParamDescriptions
    type: style
  oas3-schema:
    category:
      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
      id: schemas
      name: Schemas
    description: OpenAPI 3+ specification is invalid
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: The schema isn't valid OpenAPI 3. Check the errors for more details
    id: oas3-schema
    recommended: true
    severity: error
    then:
      function: oasDocumentSchema
    type: validation
  oas3-server-trailing-slash:
    category:
      description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed.
      id: information
      name: Contract Information
    description: server URL should not contain a trailing slash
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $.servers[*]
    howToFix: Remove the trailing slash from the server URL. This may cause some tools to incorrectly add a double slash to paths.
    id: oas3-server-trailing-slash
    severity: warn
    then:
      field: url
      function: pattern
      functionOptions:
        notMatch: /$
    type: style
  oas3-unused-component:
    category:
      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
      id: schemas
      name: Schemas
    description: Check for unused components and bad references
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Unused components / definitions are generally the result of the OpenAPI contract being updated without considering references. Another reference could have been updated, or an operation changed that no longer references this component. Remove this component from the spec, or re-link to it from another component or operation to fix the problem.
    id: oas3-unused-component
    recommended: true
    severity: warn
    then:
      function: oasUnusedComponent
    type: validation
  oas3-valid-schema-example:
    category:
      description: Examples help consumers understand how API calls should look. They are really important for automated tooling for mocking and testing. These rules check examples have been added to component schemas, parameters and operations. These rules also check that examples match the schema and types provided.
      id: examples
      name: Examples
    description: If an example has been used, check the schema is valid
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Examples are critical for consumers to be able to understand schemas and models defined by the spec. Without examples, developers can't understand the type of data the API will return in real life. Examples are turned into mocks and can provide a rich testing capability for APIs. Add detailed examples everywhere!
    id: oas3-valid-schema-example
    recommended: true
    severity: warn
    then:
      function: oasExampleSchema
    type: validation
  openapi-tags:
    category:
      description: Tags are used as meta-data for operations. They are mainly used by tooling as a taxonomy mechanism to build navigation, search and more. Tags are important as they help consumers navigate the contract when using documentation, testing, code generation or analysis tools.
      id: tags
      name: Tags
    description: Top level spec `tags` must not be empty, and must be an array
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Add a global 'tags' object to the root of the spec. Global tags are used by operations to define taxonomy and information architecture by tools. Tags generate navigation in documentation as well as modules in code generation.
    id: openapi-tags
    resolved: true
    severity: warn
    then:
      field: tags
      function: schema
      functionOptions:
        forceValidation: true
        schema:
          items:
            minItems: 1
            type: object
          type: array
          uniqueItems: true
    type: validation
  openapi-tags-alphabetical:
    category:
      description: Tags are used as meta-data for operations. They are mainly used by tooling as a taxonomy mechanism to build navigation, search and more. Tags are important as they help consumers navigate the contract when using documentation, testing, code generation or analysis tools.
      id: tags
      name: Tags
    description: Tags must be in alphabetical order
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $.tags
    howToFix: The global tags defined in the spec are not listed alphabetically, Everything is much better when data is pre-sorted. Order the tags in alphabetical sequence.
    id: openapi-tags-alphabetical
    resolved: true
    severity: info
    then:
      function: alphabetical
      functionOptions:
        keyedBy: name
    type: style
  operation-4xx-response:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Make sure operations return at least one `4xx` error response to help with bad requests
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Make sure each operation defines at least one 4xx error response. 4xx Errors are used to inform clients they are using the API incorrectly, with bad input, or malformed requests. An API with no errorsdefined is really hard to navigate.
    id: operation-4xx-response
    resolved: true
    severity: warn
    then:
      function: oasOpErrorResponse
    type: validation
  operation-description:
    category:
      description: Documentation is really important, in OpenAPI, just about everything can and should have a description. This set of rules checks for absent descriptions, poor quality descriptions (copy/paste), or short descriptions.
      id: descriptions
      name: Descriptions
    description: Operation description checks
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: All operations must have a description. Descriptions explain how the operation works, and how users should use it and what to expect. Operation descriptions make up the bulk of API documentation. so please, add a description!
    id: operation-description
    recommended: true
    resolved: true
    severity: warn
    then:
      function: oasDescriptions
      functionOptions:
        minWords: "1"
    type: validation
  operation-operationId:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Every operation must contain an `operationId`.
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Every single operation needs an operationId. It's a critical requirement to be able to identify each individual operation uniquely. Please add an operationId to the operation.
    id: operation-operationId
    recommended: true
    severity: error
    then:
      function: oasOpId
    type: validation
  operation-operationId-unique:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Every operation must have unique `operationId`.
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $.paths
    howToFix: An operationId needs to be unique, there can't be any duplicates in the document, you can't re-use them. Make sure the ID used for this operation is unique.
    id: operation-operationId-unique
    recommended: true
    resolved: true
    severity: error
    then:
      function: oasOpIdUnique
    type: validation
  operation-operationId-valid-in-url:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: OperationId must use URL friendly characters
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $.paths[*][*]
    howToFix: An operationId is critical to correct code generation and operation identification. The operationId should really be designed in a way to make it friendly when used as part of a URL. Remove non-standard URL characters.
    id: operation-operationId-valid-in-url
    recommended: true
    resolved: true
    severity: error
    then:
      field: operationId
      function: pattern
      functionOptions:
        match: ^[A-Za-z0-9-._~:/?#\[\]@!\$&'()*+,;=]*$
    type: validation
  operation-parameters:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Operation parameters are unique and non-repeating.
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $.paths
    howToFix: Make sure that all the operation parameters are unique and non-repeating, don't duplicate names, don'tre-use parameter names in the same operation.
    id: operation-parameters
    recommended: true
    resolved: true
    severity: error
    then:
      function: oasOpParams
    type: validation
  operation-singular-tag:
    category:
      description: Tags are used as meta-data for operations. They are mainly used by tooling as a taxonomy mechanism to build navigation, search and more. Tags are important as they help consumers navigate the contract when using documentation, testing, code generation or analysis tools.
      id: tags
      name: Tags
    description: Operation cannot have more than a single tag defined
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Using tags as 'groups' for operations makes a lot of sense. It stops making sense when multiple tags are used for an operation. Reduce tag count down to one for the operation.
    id: operation-singular-tag
    severity: warn
    then:
      function: oasOpSingleTag
    type: validation
  operation-success-response:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Operation must have at least one `2xx` or a `3xx` response.
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Make sure that your operation returns a 'success' response via  2xx or 3xx response code. An API consumer will always expect a success response
    id: operation-success-response
    recommended: true
    resolved: true
    severity: warn
    then:
      field: responses
      function: oasOpSuccessResponse
    type: style
  operation-tag-defined:
    category:
      description: Tags are used as meta-data for operations. They are mainly used by tooling as a taxonomy mechanism to build navigation, search and more. Tags are important as they help consumers navigate the contract when using documentation, testing, code generation or analysis tools.
      id: tags
      name: Tags
    description: Operation tags must be defined in global tags.
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: This tag has not been defined in the global scope, you should always ensure that any tags used in operations, are defined globally in the root 'tags' definition.
    id: operation-tag-defined
    recommended: true
    resolved: true
    severity: warn
    then:
      function: oasTagDefined
    type: validation
  operation-tags:
    category:
      description: Tags are used as meta-data for operations. They are mainly used by tooling as a taxonomy mechanism to build navigation, search and more. Tags are important as they help consumers navigate the contract when using documentation, testing, code generation or analysis tools.
      id: tags
      name: Tags
    description: Operation `tags` are missing/empty
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Operations use tags to define the domain(s) they are apart of. Generally a single tag per operation is used, however some tools use multiple tags. The point is that you need tags! Add some tags to the operation that match the globally available ones.
    id: operation-tags
    recommended: true
    resolved: true
    severity: warn
    then:
      function: oasOperationTags
    type: validation
  path-declarations-must-exist:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Path parameter declarations must not be empty ex. `/api/{}` is invalid
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $.paths
    howToFix: Paths define the endpoint for operations. Without paths, there is no API. You need to add 'paths' to the root of the specification.
    id: path-declarations-must-exist
    recommended: true
    resolved: true
    severity: error
    then:
      function: pattern
      functionOptions:
        notMatch: "{}"
    type: validation
  path-item-refs:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Path items should not use references ($ref) values. They are technically not allowed.
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Path items should not use references for defining operations. It's technically allowed, but not great style
    id: path-item-refs
    recommended: true
    severity: info
    then:
      function: pathItemReferences
    type: validation
  path-keys-no-trailing-slash:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Path must not end with a slash
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $.paths
    howToFix: Paths should not end with a trailing slash, it can confuse tooling and isn't valid as a path Remove the trailing slash from the path.
    id: path-keys-no-trailing-slash
    recommended: true
    resolved: true
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: .+\/$
    type: validation
  path-not-include-query:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Path must not include query string
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $.paths
    howToFix: Query strings are defined as parameters for an operation, they should not be included in the path Please remove it and correctly define as a parameter.
    id: path-not-include-query
    recommended: true
    resolved: true
    severity: error
    then:
      function: pattern
      functionOptions:
        notMatch: \?
    type: validation
  path-params:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Path parameters must be defined and valid.
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $
    howToFix: Path parameters need to match up with the parameters defined for the path, or in an operation that sits under that path. Make sure variable names match up and are defined correctly.
    id: path-params
    recommended: true
    resolved: true
    severity: error
    then:
      function: oasPathParam
    type: validation
  paths-kebab-case:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: Path segments must only use kebab-case (no underscores or uppercase)
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Path segments should not contain any uppercase letters, punctuation or underscores. The only valid way to separate words in a segment, is to use a hyphen '-'. The elements that are violating the rule are highlighted in the violation description. These are the elements that need to change.
    id: paths-kebab-case
    recommended: true
    severity: warn
    then:
      function: pathsKebabCase
    type: validation
  post-response-success:
    category:
      description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth.
      id: operations
      name: Operations
    description: POST Operations should have a success response defined
    formats:
      - oas3
      - oas3_1
      - oas3_2
    given: $.paths.*.post.responses
    howToFix: "Make sure your POST operations return a 'success' response via 2xx or 3xx response code. "
    id: post-response-success
    severity: warn
    then:
      function: postResponseSuccess
      functionOptions:
        properties:
          - 2XX
          - 3XX
          - "200"
          - "201"
          - "202"
          - "204"
          - "205"
          - "206"
          - "207"
          - "208"
          - "226"
          - "300"
          - "301"
          - "302"
          - "303"
          - "304"
          - "305"
          - "306"
          - "307"
          - "308"
    type: validation
  tag-description:
    category:
      description: Tags are used as meta-data for operations. They are mainly used by tooling as a taxonomy mechanism to build navigation, search and more. Tags are important as they help consumers navigate the contract when using documentation, testing, code generation or analysis tools.
      id: tags
      name: Tags
    description: Tag must have a description defined
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Tags are used to group operations into meaningful domains. Without a description, how is anyone supposed to understand what the grouping means? Add a description to your global tag.
    id: tag-description
    resolved: true
    severity: warn
    then:
      function: tagDescription
    type: validation
  typed-enum:
    category:
      description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures.
      id: schemas
      name: Schemas
    description: Enum values must respect the specified type
    formats:
      - oas3
      - oas3_1
      - oas3_2
      - oas2
    given: $
    howToFix: Enum values lock down the number of variable inputs a parameter or schema can have. The problem here is that the Enum defined, does not match the specified type. Fix the type!
    id: typed-enum
    recommended: true
    resolved: true
    severity: warn
    then:
      function: typedEnum
    type: validation