daveshanley / vacuum Goto Github PK

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
        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
    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
            - 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
    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, checkingrequired fields and validating correct use of structures.
            id: schemas
            name: Schemas
        description: Enum values must not have duplicate entry
        formats:
            - oas3
            - oas3_1
            - 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-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
            - oas2
        given: $.info
        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:
            field: description
            function: truthy
        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, checkingrequired 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:
            - oas3
            - oas3_1
            - oas2
        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
            - 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: ambiguousPaths
        type: validation
    no-eval-in-markdown:
        category:
            description: Validation rules make sure that certain characters or patterns have not been used that may causeissues when rendering in different types of applications.
            id: validation
            name: Validation
        description: Markdown descriptions must not have `eval()` statements'
        formats:
            - oas3
            - oas3_1
            - 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
            - 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-script-tags-in-markdown:
        category:
            description: Validation rules make sure that certain characters or patterns have not been used that may causeissues when rendering in different types of applications.
            id: validation
            name: Validation
        description: Markdown descriptions must not have `<script>` tags'
        formats:
            - oas3
            - oas3_1
            - 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
    oas2-anyOf:
        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, checkingrequired fields and validating correct use of structures.
            id: schemas
            name: Schemas
        description: "`anyOf` was introduced in OpenAPI 3.0, cannot be used un OpenAPI 2 specs"
        formats:
            - oas2
        given: $
        howToFix: You can't use 'anyOf' in Swagger/OpenAPI 2 specs. It was added in version 3. You have to remove it
        id: oas2-anyOf
        recommended: true
        severity: error
        then:
            function: oasPolymorphicAnyOf
        type: validation
    oas2-api-host:
        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: OpenAPI `host` must be present and a non-empty string
        formats:
            - oas2
        given: $
        howToFix: The 'host' value is missing. How is a user supposed to know where the API actually lives? The host is critical in order for consumers to be able to call the API. Add an API host!
        id: oas2-api-host
        recommended: true
        severity: info
        then:
            field: host
            function: truthy
        type: style
    oas2-api-schemes:
        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: OpenAPI host `schemes` must be present and non-empty array
        formats:
            - oas2
        given: $
        howToFix: Add an array of supported host 'schemes' to the root of the specification. These are the available API schemes (like https/http).
        id: oas2-api-schemes
        recommended: true
        severity: warn
        then:
            field: schemes
            function: schema
            functionOptions:
                forceValidation: true
                schema:
                    items:
                        minItems: 1
                        type: string
                    type: array
                    uniqueItems: true
        type: validation
    oas2-discriminator:
        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, checkingrequired fields and validating correct use of structures.
            id: schemas
            name: Schemas
        description: discriminators are used correctly in schemas
        formats:
            - oas2
        given: $
        howToFix: When using polymorphism, a discriminator should also be provided to allow tools to understand how to compose your models when generating code. Add a correct discriminator.
        id: oas2-discriminator
        recommended: true
        resolved: true
        severity: error
        then:
            function: oasDiscriminator
        type: validation
    oas2-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: Host URL should not point at example.com
        formats:
            - oas2
        given: $.host
        howToFix: Remove 'example.com' from the host URL, it's not going to work.
        id: oas2-host-not-example
        recommended: true
        severity: warn
        then:
            function: pattern
            functionOptions:
                notMatch: example\.com
        type: style
    oas2-host-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: Host URL should not contain a trailing slash
        formats:
            - oas2
        given: $.host
        howToFix: Remove the trailing slash from the host URL. This may cause some tools to incorrectly add a double slash to paths.
        id: oas2-host-trailing-slash
        recommended: true
        severity: warn
        then:
            function: pattern
            functionOptions:
                notMatch: /$
        type: style
    oas2-oneOf:
        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, checkingrequired fields and validating correct use of structures.
            id: schemas
            name: Schemas
        description: "`oneOf` was introduced in OpenAPI 3.0, cannot be used un OpenAPI 2 specs"
        formats:
            - oas2
        given: $
        howToFix: You can't use 'oneOf' in Swagger/OpenAPI 2 specs. It was added in version 3. You have to remove it
        id: oas2-oneOf
        recommended: true
        severity: error
        then:
            function: oasPolymorphicOneOf
        type: validation
    oas2-operation-formData-consume-check:
        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: "Operations with `in: formData` parameter must include `application/x-www-form-urlencoded` or `multipart/form-data` in their `consumes` property."
        formats:
            - oas2
        given: $
        howToFix: When using 'formData', the parameter must include the correct mime-types. Make sure you use 'application/x-www-form-urlencoded' or 'multipart/form-data' as the 'consumes' value in your parameter.
        id: oas2-operation-formData-consume-check
        recommended: true
        resolved: true
        severity: warn
        then:
            function: oasOpFormDataConsumeCheck
        type: validation
    oas2-operation-security-defined:
        category:
            description: Security plays a central role in RESTful APIs. These rules make sure that the correct definitionshave been used and put in the right places.
            id: security
            name: Security
        description: "`security` values must match a scheme defined in securityDefinitions"
        formats:
            - oas2
        given: $
        howToFix: When defining security definitions for operations, you need to ensure they match the globally defined security schemes. Check $.securityDefinitions to make sure your values align.
        id: oas2-operation-security-defined
        recommended: true
        resolved: true
        severity: error
        then:
            function: oas2OpSecurityDefined
        type: validation
    oas2-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:
            - oas2
        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: oas2-parameter-description
        recommended: true
        resolved: true
        severity: warn
        then:
            function: oasParamDescriptions
        type: style
    oas2-schema:
        category:
            description: Validation rules make sure that certain characters or patterns have not been used that may causeissues when rendering in different types of applications.
            id: validation
            name: Validation
        description: OpenAPI 2 specification is invalid
        formats:
            - oas2
        given: $
        howToFix: The schema isn't valid Swagger/OpenAPI 2. Check the errors for more details
        id: oas2-schema
        recommended: true
        severity: error
        then:
            function: oasDocumentSchema
        type: validation
    oas2-unused-definition:
        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, checkingrequired fields and validating correct use of structures.
            id: schemas
            name: Schemas
        description: Check for unused definitions and bad references
        formats:
            - oas2
        given: $
        howToFix: Orphaned components are not used by anything. You might have plans to use them later, or they could be older schemas that never got cleaned up. A clean spec is a happy spec. Prune your orphaned components.
        id: oas2-unused-definition
        recommended: true
        severity: warn
        then:
            function: oasUnusedComponent
        type: validation
    oas2-valid-schema-example:
        category:
            description: Examples help consumers understand how API calls should look. They are really important forautomated 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 must be present and valid for operations and components
        formats:
            - oas2
        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: oas2-valid-schema-example
        recommended: true
        resolved: true
        severity: warn
        then:
            function: oasExample
        type: validation
    oas3-api-servers:
        category:
            description: Validation rules make sure that certain characters or patterns have not been used that may causeissues 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: error
        then:
            function: oasAPIServers
        type: validation
    oas3-operation-security-defined:
        category:
            description: Security plays a central role in RESTful APIs. These rules make sure that the correct definitionshave 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
        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
        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, checkingrequired fields and validating correct use of structures.
            id: schemas
            name: Schemas
        description: OpenAPI 3 specification is invalid
        formats:
            - oas3
        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-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, checkingrequired fields and validating correct use of structures.
            id: schemas
            name: Schemas
        description: Check for unused components and bad references
        formats:
            - oas3
            - oas3_1
        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 forautomated 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 must be present and valid for operations and components
        formats:
            - oas3
            - oas3_1
        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
        resolved: true
        severity: warn
        then:
            function: oasExample
        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
            - 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
            - 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
            - 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
            - 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 an 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
            - 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-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
            - 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
            - 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: error
        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
            - 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
            - 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-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
            - 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
            - 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
            - oas2
        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
    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, checkingrequired fields and validating correct use of structures.
            id: schemas
            name: Schemas
        description: Enum values must respect the specified type
        formats:
            - oas3
            - oas3_1
            - 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

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  description: The Petstore REST API.
  contact:
    name: API team
    url: https://smartbear.com/contact-us/
    email: [email protected]
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        200:
          description: An paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        201:
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        200:
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

components:
  schemas:
    ErrSomething:
      # ...
paths:
  /fish/paste:
    get:
      responses:
        default:
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ErrSomething"
                  # ...
                discriminator:
                  # ...

---
openapi: 3.0.3
info:
  title: My service
  description: Nil pointer dereference service.
  version: 1.0.0
  contact:
    name: Me
    email: [email protected]

tags:
  - name: Devices
    description: Device operations

paths:
  /v1/devices:
    post:
      tags:
        - Devices
      summary: Create a device
      description: Create a device resource.
      operationId: devices::create
      parameters:
        - $ref: 'common/parameters/authorization.yaml'
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: 'OK'

name: Authorization
in: header
required: true
schema:
  type: string
  example: Bearer <JWT token>

openapi: "3.1.0"
info: "test"

paths:
  /items/{type}/{id}:
    parameters:
      # ...
    get:
      # ...
    post:
      # ...

openapi: 3.0.3

info:
  version: 1.0.0
  title: Example

tags:
  - name: my-tag
    description: A description for My Tag

servers:
  - url: 'http://127.0.0.1:8080'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

paths:
  /v1/users:
    get:
      summary: Some summary
      operationId: users.get
      responses:
        '204':
          description: No content

    head:
      summary: Some summary
      operationId: users.head
      responses:
        '204':
          description: No content

    post:
      summary: Some summary
      operationId: users.post
      responses:
        '204':
          description: No content

    patch:
      summary: Some summary
      # operationId: users.patch
      responses:
        '204':
          description: No content

---
openapi: 3.0.3

info:
  version: '1.0'
  title: Products API
  description: Example API to test Specmatic features.

servers:
  - description: Localhost
    url: http://127.0.0.1:5000

tags:
  - name: products
    description: Products related API.

components:
  parameters:
    AcceptHeader:
      in: header
      name: Accept
      description: Accept Header
      schema:
        type: string
        enum: [application/json, '*/*']
      example: application/json
    IdParam:
      in: path
      name: id
      description: Entity ID param
      schema:
        type: integer
        format: int32
        minimum: 1
      required: true
      example: 42

  schemas:
    Product:
      title: Product
      allOf:
        - $ref: '#/components/schemas/ProductId'
        - $ref: '#/components/schemas/ProductDetails'
    ProductId:
      title: Product ID
      type: object
      properties:
        id:
          type: integer
          format: int32
          minimum: 1
          example: 42
      required: [id]
    ProductDetails:
      title: Product Details
      type: object
      properties:
        title:
          type: string
          example: iPhone 9
        description:
          type: string
          example: An apple mobile which is nothing like apple
        price:
          type: number
          minimum: 0
          example: 549
        discount:
          type: number
          minimum: 0.0
          example: 12.96
        rating:
          type: number
          minimum: 0.0
          maximum: 5.0
          example: 4.69
        stock:
          type: integer
          format: int32
          minimum: 0
          example: 856
        brand:
          type: string
          example: Apple, Inc.
        category:
          $ref: '#/components/schemas/ProductCategory'
      required:
        - title
        - description
        - price
        - discount
        - rating
        - stock
        - brand
        - category
    ProductCategory:
      title: Product Category
      type: string
      enum:
        - smartphones
        - laptops
      example: smartphones

paths:
  /v1/products:
    get:
      summary: List of all products.
      operationId: products.index
      tags: [products]
      parameters:
        - $ref: '#/components/parameters/AcceptHeader'
        - name: category
          description: Filter by product category.
          in: query
          required: false
          schema:
            type: string
          allowEmptyValue: true
          example: laptops
        - name: q
          description: Search term.
          in: query
          required: false
          schema:
            type: string
          allowEmptyValue: true
          example: samsung
      responses:
        '200':
          description: List of products
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'

  '/v1/products/{id}':
    get:
      summary: Get product.
      operationId: products.get
      tags: [products]
      parameters:
        - $ref: '#/components/parameters/AcceptHeader'
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Get product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    example: 400
                  description:
                    type: string
                    example: Invalid product ID data type
                  name:
                    type: string
                    example: Bad Request
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    example: 404
                  description:
                    type: string
                    example: Product not found
                  name:
                    type: string
                    example: Not Found

enum:
  - media_key
  - duration_ms
  - height
  - preview_image_url
  - type
  - url
  - width
  - public_metrics
  - non_public_metrics
  - organic_metrics
  - promoted_metrics
  - alt_text
type: string

paths:
  /items/{type}/{id}:
    post:
      requestBody:
        content:
        # ...

extends: [[spectral:oas, recommended]]

rules:
  must-use-paths-kebab-case:
    description: MUST use lowercase and separate words with hyphens for path segments (kebab-case).
    message: "{{description}}"
    formats: [oas3]
    type: style
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\/|[a-z0-9-.]+|{[a-zA-Z0-9]+})+$"

        match: ^(\/|[a-z0-9-.]+|{[a-zA-Z0-9]+})+$

paths:
  /some/path:
    post:
      requestBody:
        # no description here

paths:
  /some/path/{id}:
    parameters:
      - in: path
        name: id
        type: string
    post:
      requestBody:
        # no description here, but no warning emitted

openapi: 3.0.3
info:
  title: Test
  version: 0.0.1
  description: test
servers:
  - url: https://httpbin.org
paths:
  /test:
    get:
      operationId: test
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Item'

openapi: 3.0.3
info:
  title: Test
  version: 0.0.1
  description: A test API
servers:
  - url: https://example.com
security:
  - basicAuth: []
tags:
  - name: tag1
paths:
  /update/{something}:
    post:
      operationId: postSomething
      summary: Post something
      tags:
        - tag1
      responses:
        '200':
          description: Post OK
    get:
      operationId: getSomething
      summary: Get something
      tags:
        - tag1
      responses:
        '200':
          description: Get OK
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

components:
  schemas:
    NotAuthorized:
      type: integer
      enum: [401]
      example: 401

securityDefinitions:
  basicAuth:
    type: basic
  sessionAuth:
    type: apiKey
    in: header
    name: X-API-Key

security:
  - basicAuth: []
  - sessionAuth: []

# openapi.yaml
# ...
paths:
  /foo:
    get:
      parameters:
        - $ref: "./bar.yaml"

# bar.yaml

in: query
name: bar
schema:
  type: string
description: ...
allowEmptyValue: true

# ...

components:
  parameters:
    CategoryFilter:
      in: query
      name: category
      description: Filter by product category.
      required: false
      schema:
        type: string
      examples:
        single:
          value: laptops
          summary: A sample category to filter products.

paths:
  /v1/products:
    get:
      summary: Get products
      description: Returns a list of all products.
      operationId: products.index
      tags: [products]
      parameters:
        - $ref: '#/components/parameters/categoryFilter'

# ...