Stoplight — spectral action rules

# harvested from https://github.com/stoplightio/spectral-action/blob/6416fd018ae38e60136775066eb3e98172143141/.spectral.json on 2026-10-09 — a Spectral ruleset published in the provider's own GitHub repository (stoplightio/spectral-action); found by GitHub code search, fetched verbatim and converted from JSON to YAML
x-method: harvested
x-stamped: 2026-10-09
x-source-url: https://github.com/stoplightio/spectral-action/blob/6416fd018ae38e60136775066eb3e98172143141/.spectral.json
description: ''
formats:
- oas2
- oas3
- oas3.0
- oas3.1
aliases:
  API_Document:
    description: 'The complete API specification document. This can be used to target
      any part of the OpenAPI document using **field**.


      *Use this if you don''t find specific targets that cater to your usecase.* '
    targets:
    - formats:
      - oas2
      given:
      - $
    - formats:
      - oas3
      given:
      - $
  API_Description:
    description: The top level description in an API document
    targets:
    - formats:
      - oas2
      given:
      - $.info.description
    - formats:
      - oas3
      given:
      - $.info.description
  Operation_Object:
    description: The complete operation object. Use it in combo with field object.
    targets:
    - formats:
      - oas2
      given:
      - '#Path_Item[get,put,post,delete,options,head,patch,trace]'
    - formats:
      - oas3
      given:
      - '#Path_Item[get,put,post,delete,options,head,patch,trace]'
  Operation_Responses:
    description: Responses for all operations including get, put, post, delete, options,
      head, patch, trace.
    targets:
    - formats:
      - oas2
      given:
      - '#Operation_Object.responses'
    - formats:
      - oas3
      given:
      - '#Operation_Object.responses'
  Path_Item:
    description: ''
    targets:
    - formats:
      - oas2
      given:
      - $.paths[*]
    - formats:
      - oas3
      given:
      - $.paths[*]
  API_Contact:
    description: The top level description in an API document
    targets:
    - formats:
      - oas2
      given:
      - $.info.contact
    - formats:
      - oas3
      given:
      - $.info.contact
  API_License:
    description: The top level description in an API document
    targets:
    - formats:
      - oas2
      given:
      - $.info.license
    - formats:
      - oas3
      given:
      - $.info.license
  All_Markdown:
    description: All markdown descriptions across the document.
    targets:
    - formats:
      - oas2
      given:
      - $..[description,title]
    - formats:
      - oas3
      given:
      - $..[description,title]
  API_Tags:
    description: Tags on an API object
    targets:
    - formats:
      - oas2
      given:
      - $.tags
    - formats:
      - oas3
      given:
      - $.tags
  API_Server:
    description: API hosts defined in the API specification
    targets:
    - formats:
      - oas3
      given:
      - $.servers
    - formats:
      - oas2
      given:
      - $.host
  Response_All_Object:
    description: All responses (object) in an API
    targets:
    - formats:
      - oas2
      given:
      - $.responses
      - '#Operation_Responses'
      - $..responses
    - formats:
      - oas3
      given:
      - $.components.responses
      - '#Operation_Responses'
      - $..responses
  API_Server_URL:
    description: API host urls defined in the API specification
    targets:
    - formats:
      - oas3
      given:
      - $.servers[*].url
    - formats:
      - oas2
      given:
      - $.host
  All_Ref:
    description: All references throughout the API
    targets:
    - formats:
      - oas2
      given:
      - $..[?(@property === '$ref')]
    - formats:
      - oas3
      given:
      - $..[?(@property === '$ref')]
  All_Enum:
    description: All references throughout the API
    targets:
    - formats:
      - oas2
      given:
      - $..[?(@ && @.enum && @.type)]
    - formats:
      - oas3
      given:
      - $..[?(@ && @.enum && @.type)]
  Request_Parameter_All:
    description: All request parameters
    targets:
    - formats:
      - oas2
      given:
      - $..parameters[*]
    - formats:
      - oas3
      given:
      - $..parameters[*]
  Request_Parameter_Query:
    description: All request query parameters
    targets:
    - formats:
      - oas2
      given:
      - $..parameters[?(@.in=="query")]
    - formats:
      - oas3
      given:
      - $..parameters[?(@.in=="query")]
  Request_Parameter_Header:
    description: All request header parameters
    targets:
    - formats:
      - oas2
      given:
      - $..parameters[?(@.in=="header")]
    - formats:
      - oas3
      given:
      - $..parameters[?(@.in=="header")]
  Request_Parameter_Cookie:
    description: All request cookie parameters
    targets:
    - formats:
      - oas2
      given:
      - $..parameters[?(@.in=="cookie")]
    - formats:
      - oas3
      given:
      - $..parameters[?(@.in=="cookie")]
  Request_Parameter_Path:
    description: All request path parameters
    targets:
    - formats:
      - oas2
      given:
      - $..parameters[?(@.in=="path")]
    - formats:
      - oas3
      given:
      - $..parameters[?(@.in=="path")]
  Path_Object:
    description: Path object. Usually used to target the Path key e.g. `/users/{userId}`
    targets:
    - formats:
      - oas2
      given:
      - $.paths
    - formats:
      - oas3
      given:
      - $.paths
  All_Example_Schema:
    description: All examples for schemas
    targets:
    - formats:
      - oas2
      given:
      - $..definitions..[?(@property !== 'properties' && @ && (@.example !== void
        0 || @['x-example'] !== void 0 || @.default !== void 0) && (@.enum || @.type
        || @.format || @.$ref || @.properties || @.items))]
      - $..parameters..[?(@property !== 'properties' && @ && (@.example !== void 0
        || @['x-example'] !== void 0 || @.default !== void 0) && (@.enum || @.type
        || @.format || @.$ref || @.properties || @.items))]
      - $..responses..[?(@property !== 'properties' && @ && (@.example !== void 0
        || @['x-example'] !== void 0 || @.default !== void 0) && (@.enum || @.type
        || @.format || @.$ref || @.properties || @.items))]
    - formats:
      - oas3
      given:
      - $.components.schemas..[?(@property !== 'properties' && @ && (@ && @.example
        !== void 0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref
        || @.properties || @.items))]
      - $..content..[?(@property !== 'properties' && @ && (@ && @.example !== void
        0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref || @.properties
        || @.items))]
      - $..headers..[?(@property !== 'properties' && @ && (@ && @.example !== void
        0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref || @.properties
        || @.items))]
      - $..parameters..[?(@property !== 'properties' && @ && (@ && @.example !== void
        0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref || @.properties
        || @.items))]
  API_Document_RecursiveSearch:
    description: 'The complete API specification document. This can be used to target
      any part of the OpenAPI document using **field**.


      *Use this if you don''t find specific targets that cater to your usecase.* '
    targets:
    - formats:
      - oas2
      given:
      - $..
    - formats:
      - oas3
      given:
      - $..
  All_Example:
    description: All examples across the API document
    targets:
    - formats:
      - oas2
      given:
      - $..examples[*]
    - formats:
      - oas3
      given:
      - $.components.examples[*]
      - $.paths[*][*]..content[*].examples[*]
      - $.paths[*][*]..parameters[*].examples[*]
      - $.components.parameters[*].examples[*]
      - $.paths[*][*]..headers[*].examples[*]
      - $.components.headers[*].examples[*]
  All_Example_Media:
    description: All examples for schemas
    targets:
    - formats:
      - oas2
      given:
      - $..responses..[?(@ && @.schema && @.examples)]
    - formats:
      - oas3
      given:
      - $..content..[?(@ && @.schema && (@.example !== void 0 || @.examples))]
      - $..headers..[?(@ && @.schema && (@.example !== void 0 || @.examples))]
      - $..parameters..[?(@ && @.schema && (@.example !== void 0 || @.examples))]
  API_Tags_Item:
    description: Tags on an API object
    targets:
    - formats:
      - oas2
      given:
      - $.tags[*]
    - formats:
      - oas3
      given:
      - $.tags[*]
rules:
  contact-url:
    given:
    - '#API_Contact'
    severity: warn
    then:
      function: truthy
      field: url
    description: Contact object should have "url"
    message: Contact object should have "url"
  contact-email:
    given:
    - '#API_Contact'
    severity: warn
    then:
      function: truthy
      field: email
    description: Contact object should have "email"
    message: Contact object should have "email"
  info-contact:
    given:
    - '#API_Document'
    severity: warn
    then:
      function: truthy
      field: info.contact
    description: Info object should have "contact" object.
    message: Info object should have "contact" object.
  info-description:
    given:
    - '#API_Document'
    severity: warn
    then:
      function: truthy
      field: info.description
    description: Info object should have "description" object.
    message: Info object should have "description" object.
  info-license:
    given:
    - '#API_Document'
    severity: warn
    then:
      function: truthy
      field: info.license
    description: Info object should have "license" object.
    message: Info object should have "license" object.
  license-url:
    given:
    - '#API_License'
    severity: warn
    then:
      function: truthy
      field: url
    description: License object should include "url".
    message: License object should include "url".
  no-eval-in-markdown:
    given:
    - '#All_Markdown'
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: eval\(
    description: Markdown descriptions must not have "eval(".
    message: Markdown descriptions must not have "eval(".
  no-script-tags-in-markdown:
    given:
    - '#All_Markdown'
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: <script
    description: Markdown descriptions must not have "eval(".
    message: Markdown descriptions must not have "<script>" tags.
  openapi-tags-alphabetical:
    given:
    - '#API_Tags'
    severity: warn
    then:
      function: alphabetical
      functionOptions:
        keyedBy: name
    description: OpenAPI object should have alphabetical "tags".
    message: OpenAPI object should have alphabetical "tags".
  openapi-tags:
    given:
    - '#API_Tags'
    severity: warn
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1
    description: OpenAPI object should have non-empty "tags" array.
    message: OpenAPI object should have non-empty "tags" array.
  operation-description:
    given:
    - '#Operation_Object'
    severity: warn
    then:
      function: truthy
      field: description
    description: Operation "description" should be present and non-empty string.
    message: Operation "description" should be present and non-empty string.
  operation-operationId:
    given:
    - '#Operation_Object'
    severity: warn
    then:
      function: truthy
      field: operationId
    description: Operation should have "operationId".
    message: Operation should have "operationId".
  operation-operationId-valid-in-url:
    given:
    - '#Operation_Object'
    severity: error
    then:
      function: pattern
      functionOptions:
        match: ^[A-Za-z0-9-._~:/?#\[\]@!\$&'()*+,;=]*$
      field: operationId
    description: operationId must not characters that are invalid when used in URL.
    message: OperationId should not have characters that are invalid when used in
      URL.
  operation-singular-tag:
    given:
    - '#API_Tags'
    severity: 'off'
    then:
      function: length
      functionOptions:
        max: 1
    description: Operation should not have more than a single tag.
    message: Operation should not have more than a single tag.
  operation-tags:
    given:
    - '#Operation_Object'
    severity: warn
    then:
      function: length
      functionOptions:
        max: 999
        min: 1
      field: tags
    description: Operation should have non-empty "tags" array.
    message: Operation should have non-empty "tags" array.
  path-declarations-must-exist:
    given:
    - '#Path_Item'
    severity: error
    then:
      function: pattern
      functionOptions:
        notMatch: '{}'
      field: '@key'
    description: Path parameter declarations must not be empty, ex.`/given/{}` is
      invalid.
    message: Path parameter declarations must not be empty, ex."/given/{}" is invalid.
  contact-name:
    given:
    - '#API_Contact'
    severity: warn
    then:
      function: truthy
      field: name
    description: Contact object should have "name"
    message: Contact object should have "name"
  path-keys-no-trailing-slash:
    given:
    - '#Path_Object'
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: .+\/$
      field: '@key'
    description: Path should not end with slash.
    message: Path should not end with slash.
  path-not-include-query:
    given:
    - '#Path_Object'
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: \?
      field: '@key'
    description: Path should not include query string.
    message: Path should not include query string.
  tag-description:
    given:
    - '#API_Tags_Item'
    severity: warn
    then:
      function: truthy
      field: description
    description: Tag object should have `description`.
    message: Tag object should have "description".
  api-servers:
    given:
    - '#API_Server'
    severity: warn
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1
          items:
            type: object
        dialect: draft7
    description: "OpenAPI document should have a server defined. \n\nThis can be localhost,\
      \ a development or production server. \n\n**OpenAPI V3 example**\n\n```json\n\
      {\n  \"servers\": [\n    {\n      \"url\": \"https://staging.myprodserver.com/v1\"\
      ,\n      \"description\": \"Staging server\"\n    },\n    {\n      \"url\":\
      \ \"https://myprodserver.com/v1\",\n      \"description\": \"Production server\"\
      \n    }\n  ]\n}\n```\n\n**OpenAPI V2 example**\n\n```json\n{\n  \"host\": \"\
      myprodserver.com\",\n  \"basePath\": \"/v2\",\n  \"schemes\": [\n    \"https\"\
      \n  ]\n}\n```\n\n"
    message: Server should be present.
  server-trailing-slash:
    given:
    - '#API_Server_URL'
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: /$
    description: Server URL should not have trailing slash.
    message: Server URL should not have trailing slash
  operation-success-response:
    given:
    - '#Operation_Object'
    severity: warn
    then:
      function: oasOpSuccessResponse
      field: responses
    description: Operation should have at least one "2xx" or "3xx" response.
    message: Operation should have at least one "2xx" or "3xx" response.
  path-params:
    given:
    - '#API_Document'
    severity: error
    then:
      function: oasPathParam
    description: Path parameters must be defined and valid.
    message: '{{error}}'
  operation-parameters:
    given:
    - '#Operation_Object'
    severity: warn
    then:
      function: oasOpParams
      field: parameters
    description: Operation parameters are unique and non-repeating.
    message: Operation parameters are unique and non-repeating.
  typed-enum:
    given:
    - '#All_Enum'
    severity: warn
    then:
      function: typedEnum
    description: Enum values should respect the specified type.
    message: '{{error}}'
  oas2-schema:
    given:
    - '#API_Document'
    severity: error
    then:
      function: oasDocumentSchema
    description: Validate structure of OpenAPI v2 specification.
    message: '{{error}}'
    formats:
    - oas2
  oas3-schema:
    given:
    - '#API_Document'
    severity: error
    then:
      function: oasDocumentSchema
    description: Validate structure of OpenAPI v3 specification.
    message: '{{error}}'
    formats:
    - oas3
  oas3-unused-component:
    given:
    - '#API_Document'
    severity: warn
    then:
      function: oasUnusedComponent
    description: Validate structure of OpenAPI v3 specification.
    message: '{{error}}'
    formats:
    - oas3
  operation-operationId-unique:
    given:
    - '#API_Document'
    severity: error
    then:
      function: oasOpIdUnique
    description: Every operation must have unique operationId.
    message: Every operation must have unique operationId
  oas2-operation-formData-consume-check:
    given:
    - '#Operation_Object'
    severity: error
    then:
      function: oasOpFormDataConsumeCheck
    description: 'Operations with "in: formData" parameter must include "application/x-www-form-urlencoded"
      or "multipart/form-data" in their "consumes" property.'
    message: 'Operations with "in: formData" parameter must include "application/x-www-form-urlencoded"
      or "multipart/form-data" in their "consumes" property.'
    formats:
    - oas2
  operation-tag-defined:
    given:
    - '#API_Document'
    severity: warn
    then:
      function: oasTagDefined
    description: Operation tags must be defined in global tags.
    message: Operation tags must be defined in global tags
  no-$ref-siblings:
    given:
    - '#All_Ref'
    severity: error
    then:
      function: refSiblings
    description: Property must not be placed among $ref
    message: '{{error}}'
    formats:
    - oas3.0
    - oas2
  oas2-operation-security-defined:
    given:
    - '#API_Document'
    severity: warn
    then:
      function: oasOpSecurityDefined
      functionOptions:
        schemesPath:
        - securityDefinitions
    description: Operation "security" values must match a scheme defined in the "securityDefinitions"
      object.
    message: '{{error}}'
    formats:
    - oas2
  oas3-operation-security-defined:
    given:
    - '#API_Document'
    severity: warn
    then:
      function: oasOpSecurityDefined
      functionOptions:
        schemesPath:
        - components
        - securitySchemes
    description: Operation `security` values must match a scheme defined in the `components.securitySchemes`
      object.
    message: '{{error}}'
    formats:
    - oas3
  duplicated-entry-in-enum:
    given:
    - '#All_Enum'
    severity: warn
    then:
      function: oasSchema
      functionOptions:
        schema:
          type: array
          uniqueItems: true
      field: enum
    description: Enum values should not have duplicate entry.
    message: '{{error}}'
  oas2-api-schemes:
    given:
    - '#API_Document'
    severity: error
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1
          items:
            type: string
        dialect: draft7
      field: schemes
    description: OpenAPI host "schemes" must be present and non-empty array.
    message: OpenAPI host "schemes" must be present and non-empty array.
    formats:
    - oas2
  oas2-discriminator:
    given:
    - '#API_Document'
    severity: error
    then:
      function: oasDiscriminator
      field: definitions[?(@.discriminator)]
    description: Discriminator property must be defined and required
    message: Discriminator property must be defined and required
    formats:
    - oas2
  server-not-example:
    given:
    - '#API_Server_URL'
    severity: warn
    then:
      function: pattern
      functionOptions:
        notMatch: example.com
    message: Server URL must not point at example.com.
  parameter-description:
    given:
    - '#Request_Parameter_All'
    severity: warn
    then:
      function: truthy
      field: description
    message: Parameter objects must have "description".
  oas2-anyOf:
    given:
    - '#API_Document_RecursiveSearch'
    severity: warn
    then:
      function: undefined
      field: anyOf
    description: anyOf is not available in OpenAPI v2, it was added in OpenAPI v3
    message: anyOf is not available in OpenAPI v2, it was added in OpenAPI v3
    formats:
    - oas2
  oas2-oneOf:
    given:
    - '#API_Document_RecursiveSearch'
    severity: warn
    then:
      function: undefined
      field: oneOf
    description: anyOf is not available in OpenAPI v2, it was added in OpenAPI v3
    message: oneOf is not available in OpenAPI v2, it was added in OpenAPI v3
    formats:
    - oas2
  oas3-examples-value-or-externalValue:
    given:
    - '#All_Example'
    severity: warn
    then:
      function: xor
      functionOptions:
        properties:
        - externalValue
        - value
    description: Examples must have either "value" or "externalValue" field.
    message: Examples must have either "value" or "externalValue" field.
    formats:
    - oas3
  oas2-valid-schema-example:
    given:
    - '#All_Example_Schema'
    severity: error
    then:
      function: oasExample
      functionOptions:
        oasVersion: '2'
        schemaField: $
        type: schema
    description: Examples must be valid against their defined schema.
    message: '{{error}}'
    formats:
    - oas2
  oas3-valid-schema-example:
    given:
    - '#All_Example_Schema'
    severity: error
    then:
      function: oasExample
      functionOptions:
        oasVersion: '3'
        schemaField: $
        type: schema
    description: Examples must be valid against their defined schema.
    message: '{{error}}'
    formats:
    - oas3
  oas2-valid-media-example:
    given:
    - '#All_Example_Media'
    severity: error
    then:
      function: oasExample
      functionOptions:
        oasVersion: '2'
        schemaField: schema
        type: media
    description: Examples must be valid against their defined schema.
    message: '{{error}}'
    formats:
    - oas2
  oas3-valid-media-example:
    given:
    - '#All_Example_Media'
    severity: error
    then:
      function: oasExample
      functionOptions:
        oasVersion: '3'
        schemaField: schema
        type: media
    description: Examples must be valid against their defined schema.
    message: '{{error}}'
    formats:
    - oas3
functions:
- oasDocumentSchema
- oasDiscriminator
- oasExample
- oasOpFormDataConsumeCheck
- oasOpIdUnique
- oasOpParams
- oasOpSecurityDefined
- oasOpSuccessResponse
- oasPathParam
- oasSchema
- oasTagDefined
- oasUnusedComponent
- refSiblings
- typedEnum
functionsDir: .stoplight/custom-functions
overrides:
- files:
  - fixtures/test.oas.yml#/paths/~1todos/get
  - fixtures/non_existent.yml#/paths/~1todos/get
  rules:
    some-inherited-rule: 'off'
- files:
  - fixtures/non_existent.yml#
  rules:
    oas3-api-servers: 'off'
    openapi-tags: 'off'
- files:
  - fixtures/non_existent.yml#/info
  rules:
    info-contact: 'off'