extends:
  - spectral:oas
  - spectral:asyncapi
functions:
  - consistent-response-body
  - error-response
  - onlyOneServerVersion
  - operation-id
  - operation-security
  - pagination-parameters
  - pagination-response
  - param-names
  - param-names-unique
  - param-order
  - path-param-names
  - path-param-schema
  - property-default-not-allowed
  - readonly-in-response-schema
  - schema-type-and-format
aliases:
  JWT:
    description: ''
    targets:
    - formats:
      - oas3
      given:
      - $.components.securitySchemes[?(@ && @.type=="oauth2")]
      - $.components.securitySchemes[?(@ && (@.bearerFormat=="jwt" || @.bearerFormat=="JWT"))]
    - formats:
      - oas2
      given:
      - $.components.securitySchemes[?(@ && @.type=="oauth2")]
      - $.components.securitySchemes[?(@ && (@.bearerFormat=="jwt" || @.bearerFormat=="JWT"))]
  ArrayProperties:
    description: ''
    targets:
    - formats:
      - oas2
      given:
      - $..[?(@ && @.type=="array")]
    - formats:
      - oas3.0
      given:
      - $..[?(@ && @.type=="array")]
    - formats:
      - oas3.1
      given:
      - $..[?(@ && @.type=="array")]
      - $..[?(@ && @.type && @.type.constructor.name === "Array" && @.type.includes("array"))]
  IntegerProperties:
    description: ''
    targets:
    - formats:
      - oas2
      given:
      - $..[?(@ && @.type=="integer")]
    - formats:
      - oas3.0
      given:
      - $..[?(@ && @.type=="integer")]
    - formats:
      - oas3.1
      given:
      - $..[?(@ && @.type=="integer")]
      - $..[?(@ && @.type && @.type.constructor.name === "Array" && @.type.includes("integer"))]
  StringProperties:
    description: ''
    targets:
    - formats:
      - oas2
      given:
      - $..[?(@ && @.type=="string")]
    - formats:
      - oas3.0
      given:
      - $..[?(@ && @.type=="string")]
    - formats:
      - oas3.1
      given:
      - $..[?(@ && @.type=="string")]
      - $..[?(@ && @.type && @.type.constructor.name === "Array" && @.type.includes("string"))]
functionsDir: functions
rules:
  # Info object should contain contact object
  info-contact: error
  # Each value of an enum must be unique
  duplicated-entry-in-enum: error
  # OpenAPI servers must be present and non-empty array
  oas3-api-servers: error
  # OpenAPI object info description must be present and non-empty string
  info-description: error
  # This rule protects against an edge case, for anyone bringing in description
  # documents from third parties and using the parsed content rendered in HTML/JS.
  # If one of those third parties does something shady like injecting eval()
  # JavaScript statements, it could lead to an XSS attack.
  no-eval-in-markdown: error
  # This rule protects against a potential hack, for anyone bringing in description
  # documents from third parties and then generating HTML documentation.
  # If one of those third parties does something shady like injecting <script> tags,
  # they could easily execute arbitrary code on your domain, which if it's the same
  # as your main application could be all sorts of terrible.
  no-script-tags-in-markdown: error
  # OpenAPI object should have non-empty tags array.
  openapi-tags: error
  # OpenAPI object should have alphabetical tags. This will be sorted by the name property.
  openapi-tags-alphabetical: error
  # OpenAPI object must not have duplicated tag names (identifiers).
  openapi-tags-uniqueness: error
  # Every operation must have a unique operationId.
  operation-operationId-unique: error
  # Avoid non-URL-safe characters in operation ids
  operation-operationId-valid-in-url: error
  # Use just one tag for an operation, which is helpful for some documentation systems which
  # use tags to avoid duplicate content.
  operation-singular-tag: error
  # Operation must have at least one 2xx or 3xx response. Any API operation (endpoint) can fail
  # but presumably, it is also meant to do something constructive at some point.
  operation-success-response: error
  # Operation should have non-empty tags array
  operation-tags: error
  # Operation tags should be defined in global tags
  operation-tag-defined: error
  # Path parameter declarations cannot be empty, ex./given/{} is invalid.
  path-declarations-must-exist: error
  # Keep trailing slashes off of paths, as it can cause some confusion. Some web tooling
  # (like mock servers, real servers, code generators, application frameworks, etc.) will
  # treat example.com/foo and example.com/foo/ as the same thing, but other tooling will not.
  path-keys-no-trailing-slash: error
  # Don't put query string items in the path, they belong in parameters with in: query.
  path-not-include-query: error
  # Path parameters are correct and valid.
  # For every parameter referenced in the path string (i.e: /users/{userId}), the parameter
  # must be defined in either path.parameters, or operation.parameters objects
  # (non-standard HTTP operations will be silently ignored.)
  # every path.parameters and operation.parameters parameter must be used in the path string.
  path-params: error
  # Tags alone are not very descriptive. Give folks a bit more information to work with.
  tag-description: error
  # Enum values should respect the type specifier.
  typed-enum: error
  # Examples for requestBody or response examples can have an externalValue or a value,
  # but they cannot have both.
  oas3-examples-value-or-externalValue: error
  # Operation security values must match a scheme defined in the components.securitySchemes object.
  oas3-operation-security-defined: error
  # Parameter objects should have a description.
  oas3-parameter-description: error
  # Validate structure of OpenAPI v3 specification.
  oas3-schema: error
  # Server URL should not point to example.com.
  oas3-server-not-example.com: error
  # Server URL should not have a trailing slash.
  oas3-server-trailing-slash: error
  # Examples must be valid against their defined schema. This rule is applied to Media Type objects.
  oas3-valid-media-example: error


  oas3-always-use-https:
    given:
    - "$.servers[*].url"
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "(http:\\/\\/localhost)|(https).*"
    description: "Servers must use the HTTPS protocol, except when localhost is used.\n\n`Applies
      to: OpenAPI 3.0 and 3.1`\n\n**Invalid Example**\n\n```json lineNumbers\n{  \n
      \ \"servers\": [\n    {\n      \"url\": \"http://acme.org/api/2.5\"\n    }\n
      \ ]\n}\n```\n**Valid Examples**\n\nHTTPS example:\n\n```json lineNumbers\n{
      \ \n  \"servers\": [\n    {\n      \"url\": \"https://acme.org/api/2.5\"\n    }\n
      \ ],\n}\n```\nLocalhost example:\n\n```json lineNumbers\n{\n  \"servers\": [\n
      \   {\n      \"url\": \"http://localhost:3000\"\n    }\n  ],\n}\n"
    message: Servers must use the HTTPS protocol except when using localhost
    formats:
    - oas3

  owasp:api1:2019-no-numeric-ids:
    given:
    - $.paths..parameters[*][?(@property === "name" && (@ === "id" || @.match(/(_id|Id)$/)))]^.schema
    severity: error
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          not:
            properties:
              type:
                const: integer
          properties:
            format:
              const: uuid
    description: |-
      Path parameters must use random IDs that cannot be guessed, such as UUIDs.

      **Invalid Example**

      In this example, the `{userId}` parameter has a type of `integer`.

      ```yaml lineNumbers
      paths:
        '/users/{userId}':
          parameters:
            - schema:
                type: integer
              name: userId
              in: path
              required: true
              description: Id of an existing user.
      ```

      **Valid Example**

      In this example, the `{userId}` parameter has a type of `string` with a format of `uuid`.

      ```yaml lineNumbers
      paths:
        '/users/{userId}':
          parameters:
            - schema:
                type: string
                format: uuid
              name: userId
              in: path
              required: true
              description: Id of an existing user.
      ```
    message: Use random IDs that cannot be guessed (UUIDs)

  owasp:api2:2019-no-http-basic:
    given:
    - "$.components.securitySchemes[*]"
    severity: error
    then:
      function: pattern
      functionOptions:
        notMatch: basic
      field: scheme
    description: "Security scheme must not use basic auth. Use a more secure authentication
      method, such as OAuth 2.0.\r\n\r\n**Invalid Example**\r\n\r\n``` yaml lineNumbers\r\nsecuritySchemes:\r\n
      \   basicAuth:\r\n      type: http\r\n      scheme: basic\r\n```\r\n\r\n**Valid
      Example**\r\n\r\n``` yaml lineNumbers\r\nsecuritySchemes:\r\n    OAuth2:\r\n
      \     type: oauth2\r\n      flows:\r\n        ...\r\n          ...\r\n          ...\r\n
      \         ...\r\n          ...\r\n```"
    message: "{{property}} uses basic auth. Use a more secure authentication method,
      like OAuth 2.0."

  api2:2019-no-api-keys-in-url:
    given:
    - $.components.securitySchemes[?(@ && @.type=="apiKey")].in
    severity: error
    then:
      function: pattern
      functionOptions:
        notMatch: "^(query)$"
    description: |-
      Security scheme must not contain API Keys in query parameters.

      API Keys are (usually opaque) strings that can be eavesdropped, especially when they are passed as URL parameters.

      **Invalid Example**

      The `in:query` setting makes this example invalid.

      ```yaml lineNumbers
        securitySchemes:
          API Key:
            name: API Key
            type: apiKey
            in: query
      ```

      **Valid Example**

      The `in:header` makes this example valid.

      ```yaml lineNumbers
        securitySchemes:
          API Key:
            name: API Key
            type: apiKey
            in: header
      ```
    message: 'ApiKey passed in URL: {{error}}'
    formats:
    - oas3

  owasp:api2:2019-no-credentials-in-url:
    given:
    - "$..parameters[?(@ && @.in && @.in.match(/query|path/))].name"
    severity: error
    then:
      function: pattern
      functionOptions:
        notMatch: "/^.*(password|secret|apikey).*$/i"
    description: "Path parameter must not contain credentials, such as API key, password,
      or secret.\n\n**Invalid Example**\n\nThis example is invalid because the path
      parameter includes a string with the name `password`. \n\n```yaml lineNumbers\npaths:\n
      \ '/user/{password}':\n    parameters:\n      - schema:\n          type: string\n
      \         format: password\n        name: password\n        in: path\n        required:
      true\n```\n\n**Valid Example**\n\nRemove the invalid path parameter. \n\n```yaml
      lineNumbers\npaths:\n  '/user/\n```"
    message: 'Security credentials detected in path parameter: {{value}}.'
    formats:
    - oas3

  owasp:api2:2019-auth-insecure-schemes:
    given:
    - $.components.securitySchemes[?(@.type=="http")].scheme
    severity: error
    then:
      function: pattern
      functionOptions:
        notMatch: "^(negotiate|oauth)$"
    description: "Security scheme must use a secure method.\r\n\r\n`negotiate` and
      `auth2` are considered to be insecure security schemes.\r\n\r\n**Invalid Example**\r\n\r\nThis
      example is invalid because `oauth` is considered an insecure scheme.\r\n\r\n```yaml
      lineNumbers\r\nsecuritySchemes:\r\n   Oauth1:\r\n     type: http\r\n     scheme:
      oauth\r\n```\r\n\r\n**Valid Example**\r\n\r\n```yaml lineNumbers\r\nsecuritySchemes:\r\n
      \  Bearer:\r\n     type: http\r\n     scheme: bearer\r\n```"
    message: 'Authentication scheme is considered outdated or insecure: {{value}}.'
    formats:
    - oas3

  owasp:api2:2019-jwt-best-practices:
    given:
    - "#JWT"
    severity: error
    then:
    - function: truthy
      field: description
    - function: pattern
      functionOptions:
        match: ".*RFC8725.*"
      field: description
    description: |-
      Security scheme description must state that the implementation conforms with JSON Web Tokens RFC7519, the JSON Web Token standard.

      **Invalid Example**

      This example is invalid because RFC8726 is not included in the security scheme description.

      ```yaml lineNumbers
      JWTBearer:
            type: oauth2
            flows:
              authorizationCode:
                ...
                ...
                ...
                ...
            description: A bearer token in the format of a JWS.
      ```

      **Valid Example**

      ```yaml lineNumbers
      JWTBearer:
            type: oauth2
            flows:
              authorizationCode:
                ...
                ...
                ...
                ...
            description: A bearer token in the format of a JWS and conforms to the specifications included in RFC8725.
      ```

  owasp:api4:2019-array-limit:
    given:
    - "#ArrayProperties"
    severity: error
    then:
      function: defined
      field: maxItems
    description: Array size should be limited to mitigate resource exhaustion attacks.
      This can be done using `maxItems`. You should ensure that the subschema in `items`
      is constrained too.
    message: Schema of type array must specify maxItems.

  owasp:api4:2019-string-limit:
    given:
    - "#StringProperties"
    severity: error
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          oneOf:
          - required:
            - maxLength
          - required:
            - enum
          - required:
            - const
    description: String size should be limited to mitigate resource exhaustion attacks.
      This can be done using `maxLength`.
    message: Schema of type string, enum or const must specify maxLength.


  owasp:api4:2019-integer-limit:
    given:
    - "#IntegerProperties"
    severity: error
    then:
    - function: xor
      functionOptions:
        properties:
        - minimum
        - exclusiveMaximum
    - function: xor
      functionOptions:
        properties:
        - maximum
        - exclusiveMaximum
    description: Array size should be limited to mitigate resource exhaustion attacks.
      This can be done using `maxItems`. You should ensure that the subschema in `items`
      is constrained too.
    message: Schema of type integer must specify minimum and maximum.
    formats:
    - oas3.1

  owasp:api4:2019-integer-limit-legacy:
    given:
    - "#IntegerProperties"
    severity: error
    then:
    - function: defined
      field: minimum
    - function: defined
      field: maximum
    description: Array size should be limited to mitigate resource exhaustion attacks.
      This can be done using `maxItems`. You should ensure that the subschema in `items`
      is constrained too.
    message: Schema of type integer must specify minimum and maximum.
    formats:
    - oas3.0
    - oas2

  owasp:api4:2019-integer-format:
    given:
    - "#IntegerProperties"
    severity: error
    then:
      function: defined
      field: format
    description: Integers should be limited to mitigate resource exhaustion attacks.
      Specifying whether int32 or int64 is expected via `format`.
    message: Schema of type integer must specify format (int32 or int64).

  az-version-convention:
    description: API version should be a date in YYYY-MM-DD format, optionally suffixed with '-preview'.
    severity: error
    formats: ['oas2', 'oas3']
    given: $.info.version
    then:
      function: pattern
      functionOptions:
        match: '^\d\d\d\d-\d\d-\d\d(-preview)?$'

  # All success responses except 204 should define a response body
  # ref: https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#1321-put
  az-success-response-body:
    description: All success responses except 204 should define a response body.
    severity: warn
    formats: ['oas2']
    # list http methods explicitly to exclude head
    # exclude 202 to avoid duplication with az-lro-response-schema rule
    given: $.paths[*][get,put,post,patch,delete].responses[?(@property >= 200 && @property < 300 && @property != '202' && @property != '204')]
    then:
      field: schema
      function: truthy

  az-security-min-length:
    description: Security property should specify at least one security requirement.
    severity: warn
    formats: ['oas2', 'oas3']
    given:
    - $.security
    - $.paths.*[get,put,post,patch,delete,options,head].security
    then:
      function: length
      functionOptions:
        min: 1


  az-schema-type-and-format:
    description: Schema should use well-defined type and format.
    message: '{{error}}'
    severity: warn
    formats: ['oas2']
    given:
    - $.paths[*].[put,post,patch].parameters.[?(@.in == 'body')].schema
    - $.paths[*].[get,put,post,patch,delete].responses[*].schema
    then:
      function: schema-type-and-format

  az-security-definition-description:
    description: A security definition should have a description.
    message: Security definition should have a description.
    severity: warn
    formats: ['oas2', 'oas3']
    given:
    - $.securityDefinitions[*]
    - $.components.securitySchemes[*]
    then:
      field: description
      function: truthy

  az-schema-description-or-title:
    description: All schemas should have a description or title.
    message: Schema should have a description or title.
    severity: warn
    formats: ['oas2', 'oas3']
    given:
    - $.definitions[?(!@.description && !@.title)]
    - $.components.schemas[?(!@.description && !@.title)]
    then:
      function: falsy

  az-schema-names-convention:
    description: Schema names should be Pascal case.
    message: Schema name should be Pascal case.
    severity: info
    formats: ['oas2']
    given: $.definitions.*~
    then:
      # Pascal case with optional "." separator
      function: pattern
      functionOptions:
        match: '^([A-Z][a-z0-9]+\.?)*[A-Z][a-z0-9]+$'

  az-response-body-type:
    description: Response body schema must not be a bare array.
    severity: warn
    formats: ['oas2', 'oas3']
    given: $.paths[*][*][responses][*].schema
    then:
      field: type
      function: pattern
      functionOptions:
        notMatch: '/^array$/'

  # https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#172-casing
  az-property-names-convention:
    description: Property names should be camel case.
    message: Property name should be camel case.
    severity: warn
    # This rule can report false positives if run on the resolved spec.
    # Issue: https://github.com/stoplightio/spectral/issues/1316
    resolved: false
    given: $..[?(@.type === 'object' && @.properties)].properties.*~
    then:
      function: casing
      functionOptions:
        type: camel

  az-property-type:
    description: All schema properties should have a defined type.
    message: Property should have a defined type.
    severity: warn
    resolved: false
    # Exclude properties that contains allOf to avoid false positives.
    given: $..properties[?(@object() && @.$ref == undefined && @.allOf == undefined)]
    then:
      field: type
      function: truthy

  az-put-path:
    description: Put on a path that does not end with a path parameter is uncommon.
    severity: info
    formats: ['oas2', 'oas3']
    given: $.paths[*].put^~
    then:
      function: pattern
      functionOptions:
        match: '/\}$/'

  az-request-body-not-allowed:
    description: A get or delete operation must not accept a body parameter.
    severity: error
    formats: ['oas2']
    given:
    - $.paths[*].[get,delete].parameters[*]
    then:
      field: in
      function: pattern
      functionOptions:
        notMatch: '/^body$/'

  az-request-body-optional:
    description: Flag optional request body -- common oversight.
    message: The body parameter is not marked as required.
    severity: info
    formats: ['oas2']
    given:
    - $.paths[*].[put,post,patch].parameters.[?(@.in == 'body')]
    then:
      field: required
      function: truthy

  az-path-parameter-schema:
    description: 'Path parameter should be type: string and specify maxLength and pattern.'
    message: '{{error}}'
    severity: info
    formats: ['oas2', 'oas3']
    given:
    - $.paths[*].parameters[?(@.in == 'path')]
    - $.paths[*][get,put,post,patch,delete,options,head].parameters[?(@.in == 'path')]
    then:
      function: path-param-schema

  az-post-201-response:
    description: Using post for a create operation is discouraged.
    message: Using post for a create operation is discouraged.
    severity: warn
    formats: ['oas2']
    given: $.paths[*].post.responses
    then:
      field: '201'
      function: falsy

  az-property-default-not-allowed:
    description: A required property should not specify a default value.
    message: '{{error}}'
    severity: warn
    formats: ['oas2']
    given:
    - $.paths[*].[put,post,patch].parameters.[?(@.in == 'body')].schema
    - $.paths[*].[get,put,post,patch,delete].responses[*].schema
    then:
      function: property-default-not-allowed

  az-property-description:
    description: All schema properties should have a description.
    message: Property should have a description.
    severity: warn
    resolved: false
    given: $..properties[?(@object() && @.$ref == undefined)]
    then:
      field: description
      function: truthy


  # Static path segments should be kebab-case
  az-path-case-convention:
    description: Static path segments should be kebab-case.
    message: Static path segments should be kebab-case.
    severity: info
    formats: ['oas2', 'oas3']
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        # Check each path segment individually and ignore param segments
        # Note: the ':' is only allowed in the final path segment
        match: '^(\/([a-z][a-z0-9-]+|{[^}]+}))*\/([a-z][a-z0-9-]+|{[^}]*})?(:[a-z][a-z0-9-]+)?$'

  # DO limit your URLs characters to 0-9 A-Z a-z - . _ ~ :
  az-path-characters:
    description: Path should contain only recommended characters.
    message: Path contains non-recommended characters.
    severity: info
    formats: ['oas2', 'oas3']
    given: $.paths.*~
    then:
      function: pattern
      functionOptions:
        # Check each path segment individually and ignore param segments
        # Note: the ':' is only allowed in the final path segment
        match: '^(\/([0-9A-Za-z._~-]+|{[^}]+}))*\/([0-9A-Za-z._~-]+|{[^}]*})?(:[0-9A-Za-z._~-]+)?$'

  az-path-parameter-names:
    description: Path parameter names should be consistent across all paths.
    message: '{{error}}'
    severity: warn
    formats: ['oas2', 'oas3']
    given: $.paths
    then:
      function: path-param-names


  az-parameter-default-not-allowed:
    description: A required parameter should not specify a default value.
    severity: warn
    # oas3 support has broken - restrict to oas2 for now
    formats: ['oas2']
    given:
    - $.paths[*].parameters.[?(@.required)]
    - $.paths.*[get,put,post,patch,delete,options,head].parameters.[?(@.required)]
    then:
      field: default
      function: falsy

  az-parameter-description:
    description: All parameters should have a description.
    message: Parameter should have a description.
    severity: warn
    given:
    - $.paths[*].parameters.*
    - $.paths.*[get,put,post,patch,delete,options,head].parameters.*
    then:
      field: description
      function: truthy

  az-parameter-names-convention:
    description: Parameter names should conform to Azure naming conventions.
    message: '{{error}}'
    severity: warn
    given:
    - $.paths[*].parameters.*
    - $.paths.*[get,put,post,patch,delete,options,head].parameters.*
    then:
      function: param-names

  az-parameter-names-unique:
    description: All parameter names for an operation should be case-insensitive unique.
    message: '{{error}}'
    severity: warn
    formats: ['oas2', 'oas3']
    given: $.paths[*]
    then:
      function: param-names-unique

  az-parameter-order:
    description: Path parameters must be in the same order as in the path.
    message: '{{error}}'
    severity: warn
    formats: ['oas2', 'oas3']
    given: $.paths
    then:
      function: param-order

  az-pagination-response:
    description: An operation that returns a list that is potentially large should support pagination.
    message: '{{error}}'
    severity: warn
    formats: ['oas2']
    given:
    - $.paths.*[get,post]
    then:
      function: pagination-response

  az-pagination-parameters:
    description: Pagination parameters must conform to Azure guidelines.
    message: '{{error}}'
    severity: warn
    formats: ['oas2']
    given:
    - $.paths.*[get,post]
    then:
      function: pagination-parameters

  az-operation-id:
    description: OperationId should conform to Azure API Guidelines
    message: '{{error}}'
    severity: warn
    given:
    - $.paths.*[get,put,post,patch,delete,options,head]
    then:
      function: operation-id

  # az-operation-security:
  #   description: Operation should have a security requirement or globally.
  #   message: Operation should have a security requirement.
  #   severity: warn
  #   formats: ['oas2', 'oas3']
  #   given: $.paths.*[get,put,post,patch,delete,options,head]
  #   then:
  #     function: operation-security


  az-204-no-response-body:
    description: A 204 response should have no response body.
    severity: warn
    formats: ['oas2']
    given: $.paths[*][*].responses.204
    then:
      field: schema
      function: falsy


  az-lro-put-response-codes:
    description: Long-running PUT should not return a 202 response.
    severity: warn
    formats: ['oas2','oas3']
    given: $.paths[*].put.responses.202
    then:
      function: falsy

  az-lro-response-codes:
    description: An operation that returns 202 should not return other 2XX responses.
    severity: warn
    formats: ['oas2','oas3']
    # The responses object of an operation that includes a 202 response
    # Exclude get, put and patch since the 202 for these will be flagged in other rules
    given: $.paths[*].[post,delete].responses[?(@property == '202')]^
    then:
      function: schema
      functionOptions:
        schema:
          not:
            anyOf:
              - required: ['200']
              - required: ['201']
              - required: ['204']

  az-error-response:
    description: Error response body should conform to Microsoft Azure API Guidelines.
    message: '{{error}}'
    severity: warn
    formats: ['oas2']
    given: $.paths[*][*].responses
    then:
      function: error-response

  az-formdata:
    description: Check for appropriate use of formData parameters.
    severity: info
    formats: ['oas2']
    given: $.paths.*[get,put,post,patch,delete,options,head].parameters.[?(@.in == "formData")]
    then:
      function: falsy

  az-header-disallowed:
    description: Authorization, Content-type, and Accept headers should not be defined explicitly.
    message: 'Header parameter "{{value}}" should not be defined explicitly.'
    severity: warn
    # oas3 support has broken - disable for now
    formats: ['oas2']
    given:
    - $.paths[*].parameters.[?(@.in == 'header')]
    - $.paths.*[get,put,post,patch,delete,options,head].parameters.[?(@.in == 'header')]
    then:
      function: pattern
      field: name
      functionOptions:
        notMatch: '/^(authorization|content-type|accept)$/i'



  az-lro-get-not-allowed:
    description: Get operations should not be long-running.
    severity: warn
    formats: ['oas2','oas3']
    given: $.paths[*].get.responses.202
    then:
      function: falsy

  az-delete-response-codes:
    description: A delete operation should have a 204 response.
    message: A delete operation should have a `204` response.
    severity: warn
    formats: ['oas2','oas3']
    # The responses object of a delete operation
    given: $.paths[*].delete.responses
    then:
      function: schema
      functionOptions:
        schema:
          oneOf:
          - required: ['202']
          - required: ['204']
            not:
              required: ['200']

  az-api-version-enum:
    description: The api-version parameter should not be an enum.
    severity: warn
    # oas3 support has broken - disable for now
    formats: ['oas2']
    given:
    - $.paths[*].parameters.[?(@.name == 'api-version')]
    - $.paths.*[get,put,post,patch,delete,options,head].parameters.[?(@.name == 'api-version')]
    then:
      field: enum
      function: falsy

  az-consistent-response-body:
    description: Ensure the get, put, and patch response body schemas are consistent.
    message: '{{error}}'
    severity: warn
    formats: ['oas2']
    given: $.paths.*
    then:
      function: consistent-response-body


  should-prefer-standard-media-type-names:
    given:
    - "$.paths.*.*.responses.*.content.*~"
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^application\\/(problem\\+)?json$|^[a-zA-Z0-9_]+\\/[-+.a-zA-Z0-9_]+;(v|version)=[0-9]+$"
    description: "Response content should use a standard media type `application/json`
      or `application/problem+json` (required for problem schemas).\r\n\r\n**Invalid
      Example**\r\n\r\n```yaml lineNumbers\r\n'204':\r\n      description: No Content\r\n
      \     content:\r\n        application/xml:\r\n          schema:\r\n            type:
      object\r\n            properties:\r\n              name:\r\n                type:
      string\r\n              url:\r\n                type: string\r\n                format:
      uri-reference\r\n```\r\n**Valid Example**\r\n\r\n```yaml lineNumbers\r\n'204':\r\n
      \     description: No Conten\r\n      content:\r\n        application/json:\r\n
      \         schema:\r\n            type: object\r\n            properties:\r\n
      \             name:\r\n                type: string\r\n              url:\r\n
      \               type: string\r\n                format: uri-reference\r\n```\r\n\r\n[Zalando
      Guideline 172](https://opensource.zalando.com/restful-api-guidelines/#172)"
    message: Custom media types should only be used for versioning


  must-define-a-format-for-integer-types:
    given:
    - "$.paths.*.*..schema..properties..[?(@ && @.type=='integer')]"
    severity: error
    then:
    - function: defined
      field: format
    - function: pattern
      functionOptions:
        match: "^(int32|int64|bigint)$"
      field: format
    description: "`integer` properties must have a format defined (`int32`, `int64`,
      or `bigint`).\r\n\r\n**Invalid Example**\r\n\r\n``` yaml lineNumbers\r\nrequestBody:\r\n
      \   content:\r\n      application/json:\r\n        schema:\r\n          type:
      object\r\n          properties:\r\n            range:\r\n              type:
      integer\r\n```\r\n\r\n**Valid Example**\r\n\r\n``` yaml lineNumbers\r\nrequestBody:\r\n
      \ content:\r\n    application/json:\r\n      schema:\r\n        type: object\r\n
      \       properties:\r\n          range:\r\n            type: integer\r\n            format:
      int32\r\n```\r\n\r\n[Zalando Guideline 171](https://opensource.zalando.com/restful-api-guidelines/#171)\r\n"
    message: Numeric properties must have valid format specified


  must-define-a-format-for-number-types:
    given:
    - "$.paths.*.*..schema..properties..[?(@ && @.type=='number')]"
    severity: error
    then:
    - function: defined
      field: format
    - function: pattern
      functionOptions:
        match: "^(float|double|decimal)$"
      field: format
    description: "`number` properties must have a format defined (`float`, `double`,
      or `decimal`).\r\n\r\n**Invalid Example**\r\n\r\n``` yaml lineNumbers\r\nrequestBody:\r\n
      \   content:\r\n      application/json:\r\n        schema:\r\n          type:
      object\r\n          properties:\r\n            range:\r\n              type:
      number\r\n```\r\n\r\n**Valid Example**\r\n\r\n``` yaml lineNumbers\r\nrequestBody:\r\n
      \ content:\r\n    application/json:\r\n      schema:\r\n        type: object\r\n
      \       properties:\r\n          range:\r\n            type: number\r\n            format:
      float\r\n```\r\n\r\n[Zalando Guideline 171](https://opensource.zalando.com/restful-api-guidelines/#171)\r\n"
    message: Numeric properties must have valid format specified

  should-use-standard-http-status-codes:
    given:
    - "$.paths.*.*.responses.*~"
    severity: warn
    then:
      function: enumeration
      functionOptions:
        values:
        - '100'
        - '101'
        - '200'
        - '201'
        - '202'
        - '203'
        - '204'
        - '205'
        - '206'
        - '207'
        - '300'
        - '301'
        - '302'
        - '303'
        - '304'
        - '305'
        - '307'
        - '400'
        - '401'
        - '402'
        - '403'
        - '404'
        - '405'
        - '406'
        - '407'
        - '408'
        - '409'
        - '410'
        - '411'
        - '412'
        - '413'
        - '414'
        - '415'
        - '416'
        - '417'
        - '423'
        - '426'
        - '428'
        - '429'
        - '431'
        - '500'
        - '501'
        - '502'
        - '503'
        - '504'
        - '505'
        - '511'
        - default
    description: "`response` should use standard HTTP status codes.\r\n\r\n**Invalid
      Example**\r\n\r\n`Error-500` is not a valid HTTP status code.\r\n\r\n```yaml
      lineNumbers\r\n  /weather:\r\n    get:\r\n      responses:\r\n        'Error-500':\r\n
      \         description: Internal Server Error\r\n```\r\n**Valid Example**\r\n\r\n`500`
      is a valid HTTP status code.\r\n\r\n```yaml lineNumbers\r\n  /weather:\r\n    get:\r\n
      \     responses:\r\n        '500':\r\n          description: Internal Server
      Error\r\n```\r\n\r\n[Zalando Guideline 150](https://opensource.zalando.com/restful-api-guidelines/#150)"
    message: "{{property}} is not a standardized response code"


  must-use-lowercase-with-hypens-for-path-segments:
    given:
    - "$.paths.*~"
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "^(([\\/a-z][a-z0-9\\-\\/]*)?({[^}]*})?)+$"
    description: "Path segments must use lowercase letters and hyphens to separate
      words.\r\n\r\n**Invalid Example**\r\n\r\n```yaml\r\n/BeachReport:\r\n```\r\n**Valid
      Example**\r\n\r\n```yaml\r\n/beach-report:\r\n```\r\n\r\n[Zalando Guideline
      129](https://opensource.zalando.com/restful-api-guidelines/#129)"
    message: Path segments have to be lowercase separate words with hyphens

  one-api-version-per-document:
    given:
    - "$.servers"
    severity: error
    then:
      function: onlyOneServerVersion
    description: "Server URLs should not contain multiple API versions.\r\n\r\nMixing
      multiple global API versions into a single description document can lead to
      confusion. Instead of describing multiple APIs together in a single document,
      split them into multiple APIs so no accidental changes can leak between different
      versions.\r\n\r\n**Invalid Example**\r\n\r\nThis example incorrectly includes
      multiple versions. \r\n\r\n```yaml\r\nservers:\r\n  - description: ''\r\n    url:
      'https://api.openweathermap.org/data/2'\r\n  - description: \r\n    url: 'https://api.openweathermap.org/data/3'\r\n```\r\n\r\n**Valid
      Example**\r\n\r\nThis example correctly includes a single version. \r\n\r\n```yaml\r\nservers:\r\n
      \ - description: ''\r\n    url: 'https://api.openweathermap.org/data/2'\r\n```"
    message: Server URLs contains multiple API versions. {{message}}
    formats:
    - oas3

  paths-no-http-verbs:
    given:
    - "$.paths"
    severity: error
    then:
      function: pattern
      functionOptions:
        notMatch: "\\b(GET|PUT|POST|DELETE|LIST|CREATE|REMOVE|get|put|post|delete|list|create|remove|Get|Put|Post|Delete|List|Create|Remove)\\b"
      field: "@key"
    description: "Verbs such as `get`, `delete`, and `put` must not be included in
      paths because this information is conveyed by the HTTP method.\n\n**Invalid
      Example**\n\nThe path contains the verb `get`. \n\n```json\n{\n    \"/getUsers\":
      {\n       \"post: }\n       ....\n}\n``` \n\n**Valid Example**\n\n```json\n{\n
      \   \"/user\": {\n       \"post: }\n       ....\n}\n```"
    message: Paths must not have HTTP verbs in them


  paths-avoid-special-characters:
    given:
    - "$.paths"
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: "^(.*)([\\$&+,;=?@%]+)(.*)$"
        match: ''
      field: "@key"
    description: "Paths should not contain special characters, such as `$` `&` `+`
      `,` `;` `=` `?` and `@%`.\n\n**Invalid Example**\n\nThe path contains an ampersand.
      \n\n```json\n{\n    \"/user&info\": {\n       \"post: }\n       ....\n}\n```
      \n\n**Valid Example**\n\n```json\n{\n    \"/user\": {\n       \"post: }\n       ....\n}\n```"
    message: Avoid using special characters in paths


  paths-no-file-extensions:
    given:
    - "$.paths"
    severity: error
    then:
      function: pattern
      functionOptions:
        notMatch: "\\b(JSON|json|XML|xml)\\b"
      field: "@key"
    description: "Paths must not include `json` or `xml` file extensions.\n\n**Invalid
      Example**\n\nThe path contains a `.json` extension. \n\n```json\n{\n    \"/user.json\":
      {\n       \"post: }\n       ....\n}\n``` \n\n**Valid Example**\n\n```json\n{\n
      \   \"/user\": {\n       \"post: }\n       ....\n}\n```"
    message: Paths must not have file extensions


  resource-names-plural:
    given:
    - "$.paths"
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^((\\/v\\d+)*((\\/[\\w+-]*s)(\\/\\{.*\\})*)*)$"
      field: "@key"
    description: "Resource names should generally be plural. \n\n**Invalid Example**\n\n```json\n{\n
      \   \"paths\": {\n      \"/user\": \n    }\n  }\n```\n\n**Valid Example**\n\n```json\n{\n
      \   \"paths\": {\n      \"/users\": \n    }\n}\n```"
    message: Resource names should generally be plural

  path-casing:
    given:
    - "$.paths"
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "^\\/([a-z0-9]+(-[a-z0-9]+)*)?(\\/[a-z0-9]+(-[a-z0-9]+)*|\\/{.+})*$"
      field: "@key"
    description: "Paths must be `kebab-case`, with hyphens separating words.\n\n**Invalid
      Example**\n\n`userInfo` must be separated with a hyphen.\n\n```json\n{\n    \"/userInfo\":
      {\n        \"post: }\n       ....\n}\n``` \n\n**Valid Example**\n\n```json\n{\n
      \   \"/user-info\": {\n       \"post: }\n       ....\n}\n```"
    message: Paths must be kebab-case


  server-has-api:
    given:
    - "$.servers[*].url"
    severity: info
    then:
      function: pattern
      functionOptions:
        match: "^.*\\/api/?.*"
    description: Server must have /api
    message: Server must have /api in it
    formats:
    - oas3

  server-lowercase:
    given:
    - "$.servers[*].url"
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "^[^A-Z]*$"
    description: |-
      Server URLs must be lowercase. This standard helps meet industry best practices.

      **Invalid Example**

      The `name` property on line 8 (`user-Id`) must be separated by an underscore character and the `I` must be lowercase.

      ```json
      {
          "servers": [
            {
              "url": "https://ACME.com/api"
            }
          ]
      }
      ```

      **Valid Example**

      ```json
      {
          "servers": [
            {
              "url": "https://acme.com/api"
            }
          ]
      }
      ```
    message: Server URL must be lowercase
    formats:
    - oas3