Skip to content

Latest commit

 

History

History
5539 lines (5353 loc) · 144 KB

ibm-cloud-rules.md

File metadata and controls

5539 lines (5353 loc) · 144 KB

IBM Cloud Validation Ruleset

This document outlines how to configure and use the IBM Cloud Validation Ruleset, which is delivered in the @ibm-cloud/openapi-ruleset NPM package.

Table of contents

Ruleset Contents

The IBM Cloud Validation Ruleset consists of:

  • IBM Cloud validation rules: a collection of rules that implement and enforce the best practices found in the IBM Cloud API Handbook.
  • Spectral's “oas" ruleset: the IBM Cloud Validation Ruleset extends the spectral:oas ruleset, so all of the rules contained in that ruleset are also available to users of the @ibm-cloud/openapi-ruleset package as well.

Overview of IBM Cloud validation rules

This table provides an overview of the IBM Cloud validation rules. More detailed information for each rule is provided in the Reference section below.

Rule IdSeverityDescriptionOpenAPI Versions
accept-parameter warn Operations should not explicitly define the Accept header parameter oas2, oas3
array-boundary warn Array schemas should define the minItems and maxItems fields oas3
array-items warn Array schemas must specify the items property oas3
array-of-arrays warn Array schemas with items of type array should be avoided oas3
array-responses error Operations should not return an array as the top-level structure of a response. oas3
authorization-parameter warn Operations should not explicitly define the Authorization header parameter oas2, oas3
binary-schemas warn Makes sure that binary schemas are used only in proper locations within the API definition oas3
circular-refs warn Makes sure that the API definition doesn't contain any circular references oas3
collection-array-property warn The [API Handbook](https://cloud.ibm.com/docs/api-handbook?topic=api-handbook-collections-overview#response-format) states that the response to a "list" operation returning a collection must be an object that contains an array property whose name matches the plural form of the resource type. For example, the "GET /v1/things" operation should return an object with an array property named "things" (which is presumably defined as an array of Thing instances).

This rule enforces this requirement by checking each operation that appears to be a "list"-type operation (with or without support for pagination) to make sure that the operation's response schema defines an array property whose name matches the last path segment within the operation's path string, which should also match the plural form of the resource type.

oas2, oas3
composed-schema-restrictions warn Verifies that schema compositions involving oneOf and anyOf comply with best practices associated with SDK generation. oas3
consecutive-path-param-segments error Checks each path string in the API definition to detect the presence of two or more consecutive path segments that contain a path parameter reference (e.g. /v1/foos/{foo_id}/{bar_id}), which is not allowed. oas2, oas3
content-entry-contains-schema warn Content entries must specify a schema oas3
content-entry-provided warn Request bodies and non-204 responses should define a content field oas3
content-type-parameter warn Operations should not explicitly define the Content-Type header parameter oas2, oas3
delete-body warn "delete" operations should not contain a requestBody. oas3
description-mentions-json warn Schema descriptions should avoid mentioning JSON oas3
discriminator error The discriminator property must be defined in the schema oas3
discriminator error Common path parameters should be defined on the path object. oas3
enum-case-convention error Enum values should follow a specific case convention oas2, oas3
examples-name-contains-space warn The name of an entry in an examples field should not contain a space oas3
ibm-content-type-is-specific warn */* should only be used when all content types are supported oas3
ibm-error-content-type-is-json warn Error response should support application/json oas3
ibm-sdk-operations warn Validates the structure of the x-sdk-operations object oas3
if-modified-since-parameter warn Operations should avoid supporting the If-Modified-Since header parameter oas2, oas3
if-unmodified-since-parameter warn Operations should avoid supporting the If-Unmodified-Since header parameter oas2, oas3
inline-property-schema warn Nested objects should be defined as a $ref to a named schema oas3
inline-request-schema warn Request body schemas should be defined as a $ref to a named schema oas3
inline-response-schema warn Response schemas should be defined as a $ref to a named schema oas3
major-version-in-path warn All paths must contain the API major version as a distinct path segment oas2, oas3
merge-patch-optional-properties warn JSON merge-patch requestBody schemas should have no required properties oas3
missing-required-property error A schema property defined as required must be defined within the schema oas2, oas3
no-etag-header error Verifies that the ETag response header is defined in the GET operation for any resources (paths) that support the If-Match and/or If-None-Match header parameters. oas2, oas3
operation-id-case-convention warn Operation ids should follow a specific case convention oas2, oas3
operation-id-naming-convention warn Operation ids should follow a naming convention oas2, oas3
operation-summary warn Operation summary must be present and non-empty string. oas3
optional-request-body info An optional requestBody with required properties should probably be required oas3
pagination-style warn List operations should have correct pagination style oas3
parameter-case-convention error Parameter names should follow a specific case convention oas2, oas3
parameter-default warn Required parameters should not define a default value oas2, oas3
parameter-description warn Parameters should have a non-empty description oas2, oas3
parameter-order warn All required operation parameters should be listed before optional parameters. oas2, oas3
parameter-schema-or-content error Parameters must provide either a schema or content oas3
patch-request-content-type" error Verifies that PATCH operations support only requestBody content types application/json-patch+json or application/merge-patch+json. oas3
path-param-not-crn warn Verifies that path parameters are not defined as CRN (Cloud Resource Name) values oas2, oas3
path-segment-case-convention error Path segments must follow a specific case convention oas2, oas3
precondition-header error Operations that return a 412 status code must support at least one of the following header parameters: If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since oas3
prohibit-summary-sentence-style warn An operation's summary field should not have a trailing period oas3
property-attributes error Performs a series of checks on the attributes defined for various schema types oas3
property-case-collision error Avoid duplicate property names within a schema, even if they differ by case convention oas2, oas3
property-case-convention error Schema property names should follow a specific case convention oas2, oas3
property-description warn Schema properties should have a non-empty description oas2, oas3
property-inconsistent-name-and-type off Avoid using the same property name for properties of different types. This rule is disabled by default. oas2, oas3
ref-pattern warn Ensures that $ref values follow the correct patterns. oas3
ref-sibling-duplicate-description warn Ensures that the "ref-sibling" allOf pattern is not used unnecessarily to define a duplicate description. oas3
request-body-name warn An operation should specify a request body name (with the x-codegen-request-body-name extension) if its requestBody has non-form content. oas3
request-body-object warn A request body should be defined as an object oas3
response-error-response-schema warn Error response schemas should comply with API Handbook guidance oas3
response-example-provided warn Response should provide an example oas3
response-status-codes warn Performs multiple checks on the status codes used in operation responses. oas3
schema-description warn Schemas should have a non-empty description oas2, oas3
schema-type off Schemas and schema properties should have a non-empty type field. This rule is disabled by default. oas2, oas3
security-schemes warn Performs a series of validations on the content within security schemes oas3
security-schemes warn Verifies the security schemes and security requirement objects oas3
server-variable-default-value warn Server variables should have a default value oas3
string-boundary warn String schema properties should define the pattern, minLength and maxLength fields oas3
unused-tag warn Verifies that each defined tag is referenced by at least one operation oas3
valid-path-segments error Checks each path string in the API to make sure path parameter references are valid within path segments oas2, oas3
valid-type-format error Schema must use a valid combination of type and format oas3

Overview of spectral:oas rules

As mentioned above, the IBM Cloud Validation Ruleset (@ibm-cloud/openapi-ruleset) extends the spectral:oas ruleset.
While all of the spectral:oas rules are included, only the following rules are enabled by default:

'operation-operationId-unique': true,
'operation-parameters': true,
'operation-tag-defined': true,
'info-description': 'off',
'no-script-tags-in-markdown': true,
'openapi-tags': true,
'operation-description': true,
'operation-operationId': true,
'operation-tags': true,
'path-params': true,
'path-declarations-must-exist': true,
'path-keys-no-trailing-slash': true,
'path-not-include-query': true,
'no-$ref-siblings': true,
'typed-enum': true,
'oas2-operation-formData-consume-check': true,
'oas2-api-host': true,
'oas2-api-schemes': true,
'oas2-host-trailing-slash': true,
'oas2-valid-schema-example': 'warn',
'oas2-anyOf': true,
'oas2-oneOf': true,
'oas2-unused-definition': true,
'oas3-api-servers': true,
'oas3-examples-value-or-externalValue': true,
'oas3-server-trailing-slash': true,
'oas3-valid-media-example': 'warn',
'oas3-valid-schema-example': 'warn',
'oas3-schema': true,
'oas3-unused-component': true

Customization

You can customize any of the rules contained in the @ibm-cloud/openapi-ruleset (including the rules in the spectral:oas ruleset) by creating a custom ruleset. For detailed information on creating your own ruleset and how to extend other rulesets, please read the Spectral Rulesets documentation.

There are two different ways that you can supply your custom ruleset file to the IBM OpenAPI Validator:

  1. Name your custom ruleset file with one of the names (.spectral.yaml, .spectral.yml, .spectral.json or .spectral.js) and place it in the current directory where you will be running the validator.
  2. Use an arbitrary filename for your custom ruleset file (e.g. /User/myuser/rules/my-rules.yaml) and use the --ruleset command line option to specify the name when running the validator. Example:
    lint-openapi --ruleset /User/myuser/rules/my-rules.yaml my-service-api.yaml

In this document, we'll focus on how to customize and extend the rules found in the IBM Cloud Validation Ruleset.

There are a few different ways in which you can customize and extend rules. The customization options available to you will depend on the type of customization that you need to do. This is described in the following sections.

Note: If you extend the @ibm-cloud/openapi-ruleset package in your custom ruleset file, you MUST install the npm package first, using a command like this:

npm install @ibm-cloud/openapi-ruleset

Modify a rule's severity

If you would simply like to modify a rule's severity or disable a rule altogether, follow the instructions in this section.

Any rule in the @ibm-cloud/openapi-ruleset package can be configured to trigger an error, warning, info, or hint message in the validator output.
For example, to configure the schema-description rule to trigger an info message instead of a warning, specify the following in your custom ruleset file (this example uses the yaml format):

extends: '@ibm-cloud/openapi-ruleset'
rules:
  schema-description: info

To completely disable a rule, use the severity of off. For example, to disable the schema-description rule, specify the following in your custom ruleset file:

extends: '@ibm-cloud/openapi-ruleset'
rules:
  schema-description: off

Since the @ibm-cloud/openapi-ruleset package includes all the rules in spectral:oas, you can also enable rules from that ruleset that are disabled by default. For example, to enable the info-contact rule with its default severity (warning), specify the following in your custom ruleset file:

extends: '@ibm-cloud/openapi-ruleset'
rules:
  info-contact: true

You could also set the severity of info-contact explicitly to error, warn, info, or hint.

Advanced rule customization

You can customize more than just a rule's severity. You can also customize a rule's configuration to select non-default options, etc. Not all rules support a configuration, but some do (for details about which rules support a configuration object, please see the Reference section below).

In order to customize the configuration of a rule, you will need to re-define the entire rule within your custom ruleset. For these types of customizations, please follow the instructions in the Custom Rules section below.

Define custom rules

If you would like to modify the configuration of an existing rule or define your own new rule, you can define custom rules within your own ruleset.

For reference information on how to define your own custom rules, please read the Spectral custom rulesets documentation.

Replace a rule from @ibm-cloud/openapi-ruleset

In this section, we'll focus on the goal of defining a new custom rule that replaces the property-case-convention rule within the @ibm-cloud/openapi-ruleset package. Specifically, we'll configure our custom rule to enforce camel case within schema property names rather than the default snake case.

In this scenario, we will re-define the property-case-convention rule within our custom ruleset, but we will re-use the propertyCaseConvention custom function within the @ibm-cloud/openapi-ruleset package that implements the logic of this rule. For this reason, we must implement our custom ruleset using javascript instead of yaml.

Here is our custom ruleset file (.spectral.js):

const ibmCloudValidationRules = require('@ibm-cloud/openapi-ruleset');                           // Note 1
const { propertyCaseConvention } = require('@ibm-cloud/openapi-ruleset/src/functions');
const { schemas } = require('@ibm-cloud/openapi-ruleset/src/collections');

module.exports = {
  extends: ibmCloudValidationRules,
  rules: {
    'property-case-convention': {                                                                // Note 2
      description: 'Property names must follow camel case',
      message: '{{error}}',
      resolved: true,                                                                            // Note 3
      given: schemas,                                                                            // Note 4
      severity: 'warn',
      then: {
        function: propertyCaseConvention,                                                        // Note 5
        functionOptions: {                                                                       // Note 6
          type: 'camel'
        }
      }
    }
  }
};

Notes:

  1. This custom ruleset extends @ibm-cloud/openapi-ruleset and also references the propertyCaseConvention function and the schemas JSONPath collection, so we need to import each of these with require statements. In addition, be sure to install the @ibm-cloud/openapi-ruleset package: npm install @ibm-cloud/openapi-ruleset.
  2. This custom rule is re-defining (overriding) the property-case-convention rule from the @ibm-cloud/openapi-ruleset package so we need to use the same rule id (property-case-convention). Alternatively, we could have used a different rule id of our choosing, but we would then need to separately disable the existing property-case-convention rule so that we don't end up using both rules which would result in the simultaneous enforcement of two competing case conventions.
  3. The resolved=true setting means that the rule will be invoked on the resolved version of the API definition (i.e. each $ref will be resolved by replacing with the referenced entity).
  4. The use of the schemas collection for the value of the given field is a convenient way to express that the rule should be invoked on each location within the resolved API definition where a schema might appear.
  5. Our custom rule uses the same function (propertyCaseConvention) that is used by the original property-case-convention rule within the @ibm-cloud/openapi-ruleset package.
  6. We set the functionOptions field to configure the rule to enforce camel case instead of the default snake case.

Define a new rule

To define a new rule as part of your custom ruleset, please read the Spectral Custom Rulesets documentation.

Spectral Overrides

Rather than turning off a Spectral rule entirely, Spectral overrides allow you to customize ruleset usage for different files and projects without having to duplicate any rules. For details on how to add overrides to your custom ruleset, please read the Spectral overrides documentation.

Reference

This section provides reference documentation about the IBM Cloud Validation Rules contained in the @ibm-cloud/openapi-ruleset package.

Rule: accept-parameter

Rule id: accept-parameter
Description: Operations should not explicitly define the Accept header parameter. Instead, the value of the Accept parameter is inferred from the responses field.
Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/things':
    get:
      operationId: list_things
      parameters:
        - name: Accept
          in: header
          description: The expected content type within the response.
          schema:
            type: string
      responses:
        '200':
          description: 'Success response!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingCollection'
Compliant example: 
paths:
  '/v1/things':
    get:
      operationId: list_things
      responses:
        '200':
          description: 'Success response!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingCollection'

Rule: array-boundary

Rule id: array-boundary
Description: Array schemas should define the minItems and maxItems fields [1].
Severity: warn
OAS Versions: oas3
Non-compliant example: 
components:
  schemas:
    Array:
      description: An Array instance.
      type: array
      items:
        type: string
        pattern: '^[a-zA-Z0-9]*$'
        minLength: 0
        maxLength: 50
Compliant example: 
components:
  schemas:
    Array:
      description: An Array instance.
      type: array
      minItems: 0
      maxItems: 16
      items:
        type: string
        pattern: '^[a-zA-Z0-9]*$'
        minLength: 0
        maxLength: 50

Rule: array-items

Rule id: array-items
Description: This rule checks to make sure that array schemas properly specify the items property to define the type of elements contained in the array.
Severity: error
OAS Versions: oas3
Non-compliant example: 
requestBody:
  content:
    application/json:
      schema:
        type: object
        properties:
          field1:
            type: array
          field2:
            type: array
            items: 'not a schema'
Compliant example: 
requestBody:
  content:
    application/json:
      schema:
        type: object
        properties:
          field1:
            type: array
            items:
              type: string
          field2:
            type: array
            items: 
              $ref: '#/components/schemas/SomeSchema'

Rule: array-of-arrays

Rule id: array-of-arrays
Description: Array schemas with items of type array should be avoided
Severity: warn
OAS Versions: oas3
Non-compliant example: 
requestBody:
  content:
    application/json:
      schema:
        type: array
        items:
          type: array
          items:
            type: string
Compliant example: 
requestBody:
  content:
    application/json:
      schema:
        type: array
        items:
          type: string

Rule: array-responses

Rule id: array-responses
Description: This rule checks to make sure that operations do not define an array as the top-level structure within a response. The recommendation is to instead use an object with a property that contains the array. This will allow you to expand the definition of the response body (e.g. add new properties) in a compatible way in the future if needed.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
paths:
  '/v1/things':
    get:
      operationId: list_things
      responses:
        '200':
          content:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Thing'

sample response body:
[ {"name": "thing-1"}, {"name": "thing-2"} ]

Compliant example: 
paths:
  '/v1/things':
    get:
      operationId: list_things
      responses:
        '200':
          content:
            schema:
              type: object
              properties:
                things:
                  type: array
                  items:
                    $ref: '#/components/schemas/Thing'

sample response body:
{"things": [ {"name": "thing-1"}, {"name": "thing-2"} ]}

Rule: authorization-parameter

Rule id: authorization-parameter
Description: Operations should not explicitly define the Authorization header parameter. Instead, the security object should be used to indicate the supported authentication mechanisms. The security object can be defined at an operation level (which would apply only to that operation) or at a global level within the API definition (which would apply to all operations).

Within generated SDKs, the Authorization header will be managed automatically by the built-in authenticator support.

Non-SDK users (those using curl, for example) can infer the use of the Authorization header from the security object in the API definition together with other documentation provided for the service.

Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/things':
    get:
      operationId: list_things
      parameters:
        - name: Authorization
          in: header
          description: The IAM access token in the form of a Bearer token.
          schema:
            type: string
            pattern: '^Bearer .*$'
      responses:
        '200':
          description: 'Success response!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingCollection'
Compliant example: 
security:
  - IAM: []
components:
  securitySchemes:
    IAM:
      description: Service supports normal IAM-based authentication/authorization.
      in: header
      name: Authorization
      type: apiKey
paths:
  '/v1/things':
    get:
      operationId: list_things
      responses:
        '200':
          description: 'Success response!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingCollection'

Rule: binary-schemas

Rule id: binary-schemas
Description: This rule checks to make sure that binary schemas are used only in proper locations within the API definition. Specifically, the rule will check to make sure a binary schema is NOT used in the following locations:
  • A schema associated with an operation parameter.
  • A schema associated with a requestBody with JSON content.
  • A schema associated with a response with JSON content.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
paths:
  '/v1/logfile':
    get:
      operationId: download_logfile
      responses:
        '200':
          description: 'Download confirmed!'
          content:
            application/json:
              schema:
                type: string
                format: binary
Compliant example: 
paths:
  '/v1/logfile':
    get:
      operationId: download_logfile
      responses:
        '200':
          description: 'Download confirmed!'
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

Rule: circular-refs

Rule id: circular-refs
Description: This rule checks to make sure that the API definition doesn't contain circular references. A circular reference (or cycle) would be a $ref to some sort of object (e.g. a schema) where traversing the referenced object's various sub-objects (e.g. schema properties, allOf/anyOf/oneOf lists, "additionalProperties", "items", etc.) leads us to a $ref that is a reference to the original referenced object. One example of a circular reference would be a schema "Foo" that contains a property "foo" that is an instance of "Foo" itself. Another example would be a "Foo" schema that contains property "bar" that is an instance of the "Bar" schema, and "Bar" contains a property "foo" that is an instance of the "Foo" schema. Any reference to either "Foo" or "Bar" will be a circular reference.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
components:
  schemas:
    Foo:
      type: object
      properties:
        bar:
          $ref: '#/components/schemas/Bar'
    Bar:
      type: object
      properties:
        foo:
          $ref: '#/components/schemas/Foo'
Compliant example: 
components:
  schemas:
    Foo:
      type: object
      properties:
        bar:
          $ref: '#/components/schemas/Bar'
    Bar:
      type: object
      properties:
        foo_id:               # include only the Foo instance's id,
          type: string        # not the entire Foo instance

Rule: collection-array-property

Rule id: collection-array-property
Description: The [API Handbook](https://cloud.ibm.com/docs/api-handbook?topic=api-handbook-collections-overview#response-format) states that the response to a "list" operation returning a collection must be an object that contains an array property whose name matches the plural form of the resource type. For example, the "GET /v1/things" operation should return an object with an array property named "things" (which is presumably defined as an array of Thing instances).

This rule enforces this requirement by checking each operation that appears to be a "list"-type operation (with or without support for pagination) to make sure that the operation's response schema defines an array property whose name matches the last path segment within the operation's path string, which should also match the plural form of the resource type.

For the purposes of this rule, an operation is considered to be a "list"-type operation if it is a "get" request and one of the following are also true:

  1. the operation's operationId starts with "list" (e.g. "list_things")
  2. the operation's path string does not end with a path parameter reference, but there is a companion path string that does end with a path parameter reference (e.g. "/v1/things" vs "/v1/things/{thing_id}").
Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/things':
  get:
    operationId: list_things
    responses:
      '200':
        content:
          'application/json':
            schema:
              type: object
              properties:
                abuncha_things:
                  type: array
                  items:
                    $ref: '#/components/schemas/Thing'
Compliant example: 
paths:
  '/v1/things':
  get:
    operationId: list_things
    responses:
      '200':
        content:
          'application/json':
            schema:
              type: object
              properties:
                things:
                  type: array
                  items:
                    $ref: '#/components/schemas/Thing'

Rule: composed-schema-restrictions

Rule id: composed-schema-restrictions
Description: This rule examines each schema that includes a oneOf/anyOf composition and verifies that it complies with SDK generation best practices.

These best practices include the following restrictions:

  • Any object schema containing a oneOf/anyOf composition must include only object schemas within the oneOf/anyOf list.
  • The union of the properties defined by the main schema and its oneOf/anyOf sub-schemas is examined to detect any like-named (common) properties defined by two or more of the schemas. These common properties must be defined with the same datatype.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
components:
  schemas:
    Foo:
      description: A schema that violates the restrictions
      type: object
      oneOf:
        - $ref: '#/components/schemas/SubSchema1
        - $ref: '#/components/schemas/SubSchema2
    SubSchema1:
      properties:
        common_property:
          type: string
        another_property:
          type: integer
    SubSchema2:
      properties:
        common_property:
          type: integer       <<< incompatible type
        some_other_property:
          type: integer
Compliant example: 
components:
  schemas:
    Foo:
      description: A schema that complies with the restrictions
      type: object
      oneOf:
        - $ref: '#/components/schemas/SubSchema1
        - $ref: '#/components/schemas/SubSchema2
    SubSchema1:
      properties:
        common_property:
          type: string
        another_property:
          type: string
    SubSchema2:
      properties:
        common_property:
          type: string
        some_other_property:
          type: integer

Rule: consecutive-path-param-segments

Rule id: consecutive-path-param-segments
Description: This rule checks each path string in the API to detect the presence of two or more path segments that contain a parameter reference, which is not allowed. For example, the path /v1/foos/{foo_id}/{bar_id} is invalid and should probably be /v1/foos/{foo_id}/bars/{bar_id}.
Severity: error
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/foos/{foo_id}/{bar_id}':
    parameters:
      - $ref: '#/components/parameters/FooIdParam'
      - $ref: '#/components/parameters/BarIdParam'
  get:
    operationId: get_foobar
    ...
Compliant example: 
paths:
  '/v1/foos/{foo_id}/bars/{bar_id}':
    parameters:
      - $ref: '#/components/parameters/FooIdParam'
      - $ref: '#/components/parameters/BarIdParam'
  get:
    operationId: get_foobar
    ...

Rule: content-entry-contains-schema

Rule id: content-entry-contains-schema
Description: Each request body and response content field should contain a schema.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
responses:
  200:
    description: 'Success response!'
    content:
      application/json:
        # schema not provided
Compliant example: 
responses:
  200:
    description: 'Success response!'
    content:
      application/json:
        schema:
          type: string

Rule: content-entry-provided

Rule id: content-entry-provided
Description: Each request body and non-204 response should have a content field.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
responses:
  200:
    description: 'Success response!'
Compliant example: 
responses:
  200:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Thing'

Rule: content-type-parameter

Rule id: content-type-parameter
Description: Operations should not explicitly define the Content-Type header parameter. Instead, the value of the Content-Type parameter is inferred from the requestBody field. Note that the Content-Type header parameter is managed automatically by generated SDKs.
Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/things':
    post:
      operationId: create_thing
      parameters:
        - name: Content-Type
          in: header
          description: The content type of the request body.
          schema:
            type: string
      requestBody:
          description: 'The new Thing instance'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
Compliant example: 
paths:
  '/v1/things':
    post:
      operationId: create_thing
      requestBody:
          description: 'The new Thing instance'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'

Rule: delete-body

Rule id: delete-body
Description: This rule checks each "delete" operation and will return a warning if the operation contains a requestBody.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#/components/parameters/ThingIdParam'
    delete:
      operationId: delete_thing
      requestBody:
          description: 'The Thing instance to be deleted.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
      responses:
        '204':
          description: 'The thing was deleted'
Compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#/components/parameters/ThingIdParam'
    delete:
      operationId: delete_thing
      responses:
        '204':
          description: 'The thing was deleted'

Rule: description-mentions-json

Rule id: description-mentions-json
Description: Schema and schema property descriptions should avoid mentioning JSON.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
components:
  schemas:
    Thing:
      description: A JSON object representing a Thing instance.
      type: object
      properties:
        thing_type:
          type: string
        thing_version:
          type: string
Compliant example: 
components:
  schemas:
    Thing:
      description: An object representing a Thing resource.
      type: object
      properties:
        thing_type:
          type: string
        thing_version:
          type: string

Rule: discriminator

Rule id: discriminator
Description: This rule is used in conjunction with Spectral's oas3-schema rule to verify that a discriminator object (if present) is defined properly within a schema. This includes the following validations:
  1. The discriminator field must be an object.
  2. The discriminator object must have a field named propertyName that defines the name of the discriminator property.
  3. The propertyName field must be of type string.
  4. The schema property whose name is specified with the propertyName field must exist within the schema.
Severity: error
OAS Versions: oas3
Non-compliant example: 
components:
  schema:
    Thing:
      description: A Thing instance.
      type: object
      properties:
        thing_id:
          type: string
        thing_version:
          type: string
      discriminator:
        propertyName: thing_type
Compliant example: 
components:
  schema:
    Thing:
      description: A Thing instance.
      type: object
      properties:
        thing_type:
          type: string
        thing_id:
          type: string
        thing_version:
          type: string
      discriminator:
        propertyName: thing_type

Rule: duplicate-path-parameter

Rule id: duplicate-path-parameter
Description: When defining a path parameter, it's a good practice to define it once in the path object's `parameters` field rather than defining it separately within each of the operations that exist for that path.

This rule checks for situations in which a path parameter is defined identically within multiple operations under a given path, and returns a warning to alert the user that the path parameter should be defined on the path object instead.

Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/things/{thing_id}':
    get:
      operationId: get_thing
      parameters:
        - name: thing_id
          in: path
          description: The id of the thing instance.
          schema:
            type: string
    delete:
      operationId: delete_thing
      parameters:
        - name: thing_id
          in: path
          description: The id of the thing instance.
          schema:
            type: string
Compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - name: thing_id
        in: path
        description: The id of the thing instance.
        schema:
          type: string
    get:
      operationId: get_thing
    delete:
      operationId: delete_thing

Rule: enum-case-convention

Rule id: enum-case-convention
Description: This rule verifies that enum fields specified for string-type schema properties contain values that follow a specific case convention, with the default being snake case.
Severity: error
OAS Versions: oas2, oas3
Configuration: This rule can be configured to enforce a specific case convention for enum values. To configure the rule, set the functionOptions field within the rule definition to be an object that is the appropriate configuration to be used by Spectral's casing() function [1] to enforce the desired case convention for enum values.

The default configuration object provided in the rule definition is: 

{
  type: 'snake'
}

To enforce a different case convention for enum values, you'll need to replace this rule with a new rule within your custom ruleset and modify the configuration such that the value of the type field specifies the desired case convention. For example, to enforce camel case for enum values, the configuration object would look like this: 

{
  type: 'camel'
}
Non-compliant example: 
components:
  schemas:
    ThingType:
      type: string
      enum:
        - thingType1
        - thingType2
Compliant example: 
components:
  schemas:
    ThingType:
      type: string
      enum:
        - thing_type_1
        - thing_type_2

Rule: examples-name-contains-space

Rule id: examples-name-contains-space
Description: The name of an entry in an examples field should not contain a space.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
paths:
  /v1/things:
    post:
      operationId: create_thing
      description: Create a new Thing instance.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Thing'
            examples:
              'Create Thing Example':
                value:
                  thing_id: 1ac38d2z89
                  thing_type: type1
      responses:
        ...
Compliant example: 
paths:
  /v1/things:
    post:
      operationId: create_thing
      description: Create a new Thing instance.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Thing'
            examples:
              CreateThingExample:
                value:
                  thing_id: 1ac38d2z89
                  thing_type: type1
      responses:
        ...

Rule: ibm-content-type-is-specific

Rule id: ibm-content-type-is-specific
Description: The use of */* as a mimetype within a content field should be avoided unless the API actually supports all content types.

If the API in fact supports all content types, this warning should be ignored.

Severity: warn
OAS Versions: oas3
Non-compliant example: 
requestBody:
  content:
    '*/*':
      ...
Compliant example: 
requestBody:
  content:
    'application/json':
      ...
    'text/plain':
      ...

Rule: ibm-error-content-type-is-json

Rule id: ibm-error-content-type-is-json
Description: An error response likely returns application/json content and this rule warns when application/json is not the content mimetype. This rule should be ignored when the API actually returns an error response that is not application/json.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
responses:
  400:
    content:
      'application/octet-stream':
        ...
Compliant example: 
responses:
  400:
    content:
      'application/json':
        ...

Rule: ibm-sdk-operations

Rule id: ibm-sdk-operations
Description: This rule validates the structure of values specified for the x-sdk-operations extension, using this JSON Schema document.
Severity: warn
OAS Versions: oas3
Non-compliant example: n/a
Compliant example: n/a

Rule: if-modified-since-parameter

Rule id: if-modified-since-parameter
Description: The API Handbook recommends against the use of the If-Modified-Since and If-Unmodified-Since header parameters. Operations should support If-Match and If-None-Match headers instead.

This rule warns about operations that support the If-Modified-Since header parameter.

Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#components/parameters/ThingIdParam'
    get:
      operationId: get_thing
      parameters:
        - name: If-Modified-Since
          in: header
          description: |-
            The operation will succeed only if the resource has been last modified 
            after the date specified for this header parameter.
          schema:
            type: string
      responses:
        '200':
          description: 'Resource was retrieved successfully!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
        '412':
          description: 'Resource has not been modified after If-Modified-Since date.'
Compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#components/parameters/ThingIdParam'
    get:
      operationId: get_thing
      parameters:
        - name: If-None-Match
          in: header
          description: |-
            The operation will succeed only if the resource's current ETag value 
            does not match the value specified for this header parameter.
          schema:
            type: string
      responses:
        '200':
          description: 'Resource was retrieved successfully!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
        '412':
          description: 'Resource current ETag matches If-None-Match value.'

Rule: if-unmodified-since-parameter

Rule id: if-unmodified-since-parameter
Description: The API Handbook recommends against the use of the If-Modified-Since and If-Unmodified-Since header parameters. Operations should support If-Match and If-None-Match headers instead.

This rule warns about operations that support the If-Unmodified-Since header parameter.

Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#components/parameters/ThingIdParam'
    delete:
      operationId: delete_thing
      parameters:
        - name: If-Unmodified-Since
          in: header
          description: |-
            The operation will succeed only if the resource has not been modified 
            after the date specified for this header parameter.
          schema:
            type: string
      responses:
        '204':
          description: 'Resource was deleted successfully!'
        '412':
          description: 'Resource was last modified after the If-Unmodified-Since date.'
Compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#components/parameters/ThingIdParam'
    delete:
      operationId: delete_thing
      parameters:
        - name: If-Match
          in: header
           description: |-
            The operation will succeed only if the resource's current ETag value
            matches the value specified for this header parameter.
          schema:
            type: string
      responses:
        '204':
          description: 'Resource was deleted successfully!'
        '412':
          description: 'Resource current ETag value does not match the If-Match value.'

Rule: inline-property-schema

Rule id: inline-property-schema
Description: If a nested schema (perhaps a schema property, an array items schema, an additionalProperties schema, etc.) is an object with user-defined properties, it is a best practice to define the schema as a named schema within the components.schemas section of the API definition, and then reference it with a schema $ref instead of defining it as an inline object schema. This is documented in the [API Handbook](https://cloud.ibm.com/docs/api-handbook?topic=api-handbook-schemas#nested-object-schemas).

The use of a schema $ref is preferred instead of a nested object schema, because IBM's SDK generator will use the schema $ref when determining the datatype associated with the nested object within the generated SDK code. If IBM's SDK generator encounters a nested object schema, it must refactor it by moving it to the components.schemas section of the API definition and then replacing it with a schema $ref. However, the names computed by the generator are not optimal (e.g. MyModelProp1), so the recommendation is to define any nested object schema as a $ref so that the generator's refactoring (and it's sub-optimal name computation) can be avoided.

Severity: warn
OAS Versions: oas3
Non-compliant example: 
components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        version:
          type: object
          properties:
            major:
              type: string
            minor:
              type: string
Compliant example: 
components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        version:
          $ref: '#/components/schemas/ThingVersion'
    ThingVersion:
      type: object
      properties:
        major:
          type: string
        minor:
          type: string

Rule: inline-request-schema

Rule id: inline-request-schema
Description: If a requestBody schema contains properties (i.e. a user-defined model), it is a best practice to define the schema as a named schema within the components.schemas section of the API definition, and then reference it with a schema $ref within the requestBody object. Following this best practice allows user-defined models to be re-used within the API definition.

In addition to re-usability, there is an added benefit during SDK code generation. In certain scenarios, the SDK generator will refactor an inline requestBody schema by moving it to components.schemas and replacing it with a schema $ref. When doing this refactoring, the SDK generator is likely to compute a name for the new schema that is not optimal (e.g. CreateThingRequest), so the recommendation is to specify user-defined models as a named schema in components.schemas, and then reference where needed with a schema $ref instead of an inline schema.

Severity: warn
OAS Versions: oas3
Non-compliant example: 
paths:
  /v1/things:
    post:
      operationId: create_thing
      description: Create a new Thing instance.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: A Thing instance.
              properties:
                thing_id:
                  type: string
                thing_style:
                  type: string
              additionalProperties: true
      ...
Compliant example: 
components:
  schemas:
    Thing:
      type: object
      description: A Thing instance.
      properties:
        thing_id:
          type: string
        thing_style:
          type: string
      additionalProperties: true
paths:
  /v1/things:
    post:
      operationId: create_thing
      description: Create a Thing instance.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Thing'
      ...

Rule: inline-response-schema

Rule id: inline-response-schema
Description: A response schema should be defined as a reference to a named schema instead of defined as an inline schema. This is a best practice because IBM's SDK generator will use the schema reference when determining the operation's return type within the generated SDK code.

IBM's SDK generator will refactor any inline response schemas that it finds by moving them to the components.schemas section of the API definition and then replacing them with a reference. However, the names computed by the generator are not optimal (e.g. GetThingResponse), so the recommendation is for API authors to define the response schema as a $ref.

Severity: warn
OAS Versions: oas3
Non-compliant example: 
paths:
  '/v1/things/{thing_id}':
    get:
      operationId: get_thing
      description: Retrieve a Thing instance by id.
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                description: A Thing instance.
                properties:
                  thing_id:
                    type: string
                  thing_style:
                    type: string
Compliant example: 
components:
  schemas:
    Thing:
      type: object
      description: A Thing instance.
      properties:
        thing_id:
          type: string
        thing_style:
          type: string
paths:
  '/v1/things/{thing_id}':
    get:
      operationId: get_thing
      description: Retrieve a Thing instance by id.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'

Rule: major-version-in-path

Rule id: major-version-in-path
Description: Each path defined within the API definition should include a path segment for the API major version, of the form v<n>, and all paths should have the same API major version segment. The API major version can appear in either the server URL (oas3), the basePath (oas2), or in each path entry.
Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
openapi: 3.0.1
info:
  version: 1.0.0
  ...
paths:
  /things:
    ...
Compliant example: 
openapi: 3.0.1
info:
  version: 1.0.0
  ...
paths:
  /v1/things:
    ...

Rule: merge-patch-optional-properties

Rule id: merge-patch-optional-properties
Description: In order to adhere to the "merge-patch" semantics, the requestBody schema for a patch operation with application/merge-patch+json requestBody content should not define any required properties or specify a non-zero value for the minProperties field.

This rule verifies that "merge-patch" operations adhere to this requirement.

Severity: warn
OAS Versions: oas3
Non-compliant example: 
paths:
  /v1/things/{thing_id}:
    patch:
      operationId: update_thing
      requestBody:
        content:
          'application/merge-patch+json':
            schema:
              $ref: '#/components/schemas/ThingPatch'
components:
  schemas:
    ThingPatch:
      type: object
      required:
        - name
        - long_description
      properties:
        name:
          description: The name of the Thing
          type: string
        long_description:
          description: The long description of the Thing
Compliant example: 
paths:
  /v1/things/{thing_id}:
    patch:
      operationId: update_thing
      requestBody:
        content:
          'application/merge-patch+json':
            schema:
              $ref: '#/components/schemas/ThingPatch'
components:
  schemas:
    ThingPatch:          <<< no longer defines any required properties
      type: object
      properties:
        name:
          description: The name of the Thing
          type: string
        long_description:
          description: The long description of the Thing

Rule: missing-required-property

Rule id: missing-required-property
Description: This rule verifies that for each property name included in a schema's required list, that property must be defined within the schema. The property could be defined in any of the following ways:
  1. within the schema's properties field
  2. within one or more of the schemas listed in the allOf field
  3. within each of the schemas listed in the anyOf or oneOf field
Severity: error
OAS Versions: oas2, oas3
Non-compliant example: 
components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          type: string
      required:
        - thing_id
        - thing_version
Compliant example: 
components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          type: string
        thing_version:
          type: string
      required:
        - thing_id
        - thing_version

Rule: no-etag-header

Rule id: no-etag-header
Description: This rule checks each path item (the object containing operations with keys 'get', 'post', 'delete', etc.) to make sure that the path item's GET operation defines the ETag response header if it is, in fact, needed. An ETag response header is needed if there are operations within the same path item that support the If-Match or If-Not-Match header parameters.

The reasoning behind this rule is that if a given path has one or more operations in which the user needs to provide a value for the If-Match or If-None-Match header parameters (sometimes referred to as an "etag value"), then the API must provide a way for the user to obtain the etag value. And, the standard way for a service to provide an etag value to the user is by returning it as the ETag response header within the GET operation's response.

Severity: error
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - name: thing_id
        description: The id of the Thing.
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: get_thing
      responses:
        '200':
          description: 'Success response!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingCollection'
    delete:
      operationId: delete_thing
      parameters:
        - name: 'If-Match'
          description: The etag value associated with the Thing instance to be deleted.
          in: header
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 'Success response!'
Compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - name: thing_id
        description: The id of the Thing.
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: get_thing
      responses:
        '200':
          description: 'Success response!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingCollection'
          headers:
            ETag:
              description: The unique etag value associated with the instance that was retrieved.
              schema:
                type: string
    delete:
      operationId: delete_thing
      parameters:
        - name: 'If-Match'
          description: The etag value associated with the Thing instance to be deleted.
          in: header
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 'Success response!'

Rule: operation-id-case-convention

Rule id: operation-id-case-convention
Description: Operation ids should follow a specific case convention, with the default being snake case.
Severity: warn
OAS Versions: oas2, oas3
Configuration: This rule can be configured to enforce a specific case convention for operationId values. To configure the rule, set the functionOptions field within the rule definition to be an object that is the appropriate configuration to be used by Spectral's casing() function [1] to enforce the desired case convention for operationId values.

The default configuration object provided in the rule definition is: 

{
  type: 'snake'
}

To enforce a different case convention for operationId values, you'll need to replace this rule with a new rule within your custom ruleset and modify the configuration such that the value of the type field specifies the desired case convention. For example, to enforce camel case for operation ids, the configuration object would look like this: 

{
  type: 'camel'
}
Non-compliant example: 
paths:
  '/v1/things':
    post:
      operationId: createThing
Compliant example: 
paths:
  '/v1/things':
    post:
      operationId: create_thing

Rule: operation-id-naming-convention

Rule id:
Description: Operation ids should follow a naming convention using standard, predictable verbs. For example, create_thing would be preferred over manufacture_thing when deciding on an operationId for the POST /v1/things operation. Likewise, for the GET /v1/things/{thing_id} operation, we might prefer get_thing over retrieve_thing for the operationId.

This rule will analyze the operations, looking for operationId values that are not using the recommended verbs.

Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/things':
    post:
      operationId: manufacture_thing
      description: Create a new Thing instance.
      summary: Create a Thing
  '/v1/things/{thing_id}':
    get:
      operationId: retrieve_thing
      description: Get a Thing instance.
      summary: Get a Thing
Compliant example: 
paths:
  '/v1/things':
    post:
      operationId: create_thing
      description: Create a new Thing instance.
      summary: Create a Thing
  '/v1/things/{thing_id}':
    get:
      operationId: get_thing
      description: Get a Thing instance.
      summary: Get a Thing

Rule: operation-summary

Rule id: operation-summary
Description: This rule verifies that each operation has a non-empty summary.
Severity: warn
OAS Versions: oas3
Non-compliant example: 
paths:
  '/v1/things':
    post:
      operationId: create_thing
      description: Create a new Thing instance.
Compliant example: 
paths:
  '/v1/things':
    get:
      operationId: create_thing
      description: Create a new Thing instance.
      summary: Create a Thing

Rule: optional-request-body

Rule id: optional-request-body
Description: This rule scrutinizes optional request bodies because in most cases, they should be required. Specifically, this rule examines the schemas associated with optional request bodies and if there are required properties, then it is likely that the API author intended for the request body to be required.
Severity: info
OAS Versions: oas3
Non-compliant example: 
paths:
  '/v1/things':
    post:
      operationId: create_thing
      requestBody:
        required: false
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Thing'    # Assume "Thing" schema has required properties
Compliant example: 
paths:
  '/v1/things':
    post:
      operationId: create_thing
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Thing'    # Assume "Thing" schema has required properties

Rule: pagination-style

Rule id: pagination-style
Description: This rule verifies that list-type operations implement pagination correctly per the guidelines in the API Handbook.

An operation is recognized as a paginated list-type operation if all of the following are true:

  • The path doesn't end in a path segment that is a path parameter reference (e.g. /v1/things vs /v1/things/{thing_id}).
  • The operation is a get.
  • The operation's response schema is an object containing an array property.
  • The operation defines either the offset query parameter or a page-token type query parameter whose name is one of the following: start(preferred), token, cursor, page, or page_token.

If an operation is recognized as a paginated list-type operation, then the following checks are performed:

  • If the operation has a limit query parameter, then it must be of type integer, optional, and have default and maximum values defined for it [1, 2].
  • If the operation has an offset query parameter, then it must be of type integer and optional [3].
  • If the operation has an offset query parameter, then it must also have a limit query parameter [4]. This is because the presence of the offset parameter indicates that the offset/limit style pagination is being used.
  • If the operation has a page-token type query parameter, then it must be of type string and optional, and its name should be start [5].
  • If the operation has a limit query parameter, then the response body schema must contain a limit schema property that is of type integer and required [6, 7].
  • If the operation has an offset query parameter, then the response body schema must contain an offset schema property that is of type integer and required [8].
  • If the operation's response body schema contains a total_count property, then it must be of type integer and required [9, 10].
  • The operation's response body schema should contain properties named first, last, previous and next that provide links to the first, last, previous and next page of results, respectively. Each of these properties should be defined as an object with a property named href of type string which contains the appropriate request URL string to be used to obtain that page of results [11].
Severity: warn
OAS Versions: oas3
Non-compliant example: n/a
Compliant example: n/a

Rule: parameter-case-convention

Rule id: parameter-case-convention
Description: Parameter names should be snake case
Severity: error
OAS Versions: oas2, oas3
Configuration: This rule can be configured to enforce specific case conventions for each parameter type. To configure the rule, set the functionOptions field within the rule definition to be an object with keys that represent the different parameter types to be checked for proper case conventions ('query', 'path', and 'header'). The value associated with each entry should be an object that is the appropriate configuration to be used by Spectral's casing() function [1] to enforce the desired case convention for that parameter type.

The default configuration object provided in the rule definition is: 

{
  query: {
    type: 'snake',
    separator: {
      char: '.'
    }
  },
  path: {
    type: 'snake'
  },
  header: {
    type: 'pascal',
    separator: {
      char: '-'
    }
  }
}
This enforces:
  • Query parameter names to be snake case, while also allowing "." within the name
  • Path parameter names to be snake case
  • Header parameter names to be in http header canonical form, which amounts to pascal casing with a hyphen ("-") separating the words (e.g. X-My-Header).

To disable the case convention checks for a particular parameter type, simply remove the entry for that parameter type from the configuration object.

If you want to use a different configuration for this rule other than the default configuration mentioned above, you'll need to replace this rule with a new rule within your custom ruleset and modify the configuration appropriately for your needs. For example, to disable the case convention checks on header parameter names, while enforcing camel case conventions on query and path parameter names, the configuration object would look like this: 

{
  query: {
    type: 'camel'
  },
  path: {
    type: 'camel'
  }
}
Non-compliant example: 
components:
  parameters:
    SortOrderParam:
      name: sortOrder           << camel case
      description: The sort order.
      in: query
      required: false
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc
Compliant example: 
components:
  parameters:
    SortOrderParam:
      name: sort_order        << snake case
      description: The sort order.
      in: query
      required: false
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc

Rule: parameter-default

Rule id: parameter-default
Description: Required parameters should not define a default value.
Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
components:
  parameters:
    SortOrderParam:
      name: sort_order
      description: The sort order.
      in: query
      required: true
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc
Compliant example: 
components:
  parameters:
    SortOrderParam:
      name: sort_order
      description: The sort order.
      in: query
      required: true
      schema:
        type: string
        enum:
          - asc
          - desc

Rule: parameter-description

Rule id: parameter-description
Description: Parameters should have a non-empty description.
Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
components:
  parameters:
    SortOrderParam:
      name: sort_order
      in: query
      required: false
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc
Compliant example: 
components:
  parameters:
    SortOrderParam:
      name: sort_order
      description: An optional ordering to be performed on the results that are returned.
      in: query
      required: false
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc

Rule: parameter-order

Rule id: parameter-order
Description: It is a good practice to list the parameters within an operation such that all required parameters are listed first, then any optional parameters.
Severity: warn
OAS Versions: oas2, oas3
Non-compliant example: 
paths:
  '/v1/things':
    get:
      operationId: list_things
      description: List the set of Things.
      summary: List Things
      parameters:
        - name: offset
          required: false
          in: query
          schema:
            type: integer
        - name: limit
          required: false
          in: query
          schema:
            type: integer
        - name: filter
          required: true
          in: query
          schema:
            type: string
Compliant example: 
paths:
  '/v1/things':
    get:
      operationId: list_things
      description: List the set of Things.
      summary: List Things
      parameters:
        - name: filter
          required: true
          in: query
          schema:
            type: string
        - name: offset
          required: false
          in: query
          schema:
            type: integer
        - name: limit
          required: false
          in: query
          schema:
            type: integer

Rule: parameter-schema-or-content

Rule id: parameter-schema-or-content
Description: Each parameter must provide either a schema or content object.
Severity: error
OAS Versions: oas3
Non-compliant example: 
parameters:
- name: param1
  in: query
  description: query param
Compliant example: 
parameters:
- name: param1
  in: query
  description: query param
  schema:
    type: string

Rule: patch-request-content-type

Rule id: patch-request-content-type
Description: The API Handbook recommends that PATCH operations contain request bodies that support only content types application/json-patch+json and application/merge-patch+json.

This rule verifies that each PATCH operation complies with this recommendation.

Severity: warn
OAS Versions: oas3
Non-compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#/components/parameters/ThingIdParam'
    patch:
      operationId: update_thing
      description: Update a Thing instance.
      requestBody:
        content:
          application/json:
            schema:
              - $ref: '#/components/schemas/Thing'
      responses:
        '200':
          description: 'Thing updated successfully!'
Compliant example: 
paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#/components/parameters/ThingIdParam'
    patch:
      operationId: update_thing
      description: Update a Thing instance.
      requestBody:
        content:
          application/merge-patch+json:
            schema:
              - $ref: '#/components/schemas/Thing'
      responses:
        '200':
          description: 'Thing updated successfully!'

Rule: path-param-not-crn

Rule id: path-param-not-crn
Description: This rule checks to make sure that there are no path parameters that are defined as a CRN (Cloud Resource Name) value.

In order to determine whether or not a path parameter is considered to be defined as a CRN value, this validation rule will perform the following checks:

  • The parameter's name field contains "crn" (e.g. "resource_crn")
  • The parameter's schema is defined with type=string, format=crn
  • The parameter's schema is defined with a pattern field that starts with either "crn" or "^crn" (e.g. 'crn:[-0-9A-Fa-f]+')
  • The parameter's example field contains a CRN-like value (e.g. "crn:0afd-0138-2636")
  • The parameter's examples field contains an entry containing a CRN-like value, as in this example: 
    
components:
  parameters:
    ThingIdParam:
      name: thing_id
      description: The id of the Thing instance
      in: path
      required: true
      schema:
        type: string
      examples:
        crn_example:
          value: 'crn:0afd-0138-2636'

    • 

  • The parameter schema's example field contains a CRN-like value (e.g. "crn:0afd-0138-2636")
    • 

  • The parameter's description field contains either "CRN" or "Cloud Resource Name"
    • 

  • The parameter schema's description field contains either "CRN" or "Cloud Resource Name"
    • 


These checks are logically OR'd together, so that if any one or more of these checks
are true for a particular parameter, then a warning is raised for that parameter. 




Severity:
warn




OAS Versions:
oas2, oas3




Non-compliant example:


components:
  parameters:
    ThingCrnParam:
      name: thing_crn
      description: The CRN associated with the Thing instance
      in: path
      required: true
      schema:
        type: string
        format: crn
        pattern: '^crn:[-0-9A-Fa-f]+$'
        minLength: 5
        maxLength: 32







Compliant example:


components:
  parameters:
    ThingIdParam:
      name: thing_id
      description: The id associated with the Thing instance
      in: path
      required: true
      schema:
        type: string
        format: identifier
        pattern: '^id:[-0-9A-Fa-f]+$'
        minLength: 5
        maxLength: 32








Rule: path-segment-case-convention





Rule id:
path-segment-case-convention




Description:
Path segments must follow a specific case convention, with the default being snake case.




Severity:
error




OAS Versions:
oas2, oas3




Configuration:
This rule's default configuration will enforce snake case for path segments, but the rule can be configured
to enforce a different case convention if desired.

To enforce a different case convention for path segments, you'll need to
replace this rule with a new rule within your
custom ruleset and modify the configuration such that the value of the type field 
specifies the desired case convention.
For example, to enforce camel case for path segments, the configuration object would look like this:

{
  type: 'camel'
}







Non-compliant example:


paths:
  '/v1/someThings/{thing_id}':







Compliant example:


paths:
  '/v1/some_things/{thing_id}':








Rule: precondition-header

. For more details, please see the API Handbook on [Conditional Headers](https://cloud.ibm.com/docs/api-handbook?topic=api-handbook-headers#conditional-headers).




Rule id:
precondition-header




Description:
Operations that return a 412 status code must support at least one of the following header parameters: If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since



Severity:
error




OAS Versions:
oas3




Non-compliant example:


paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#components/parameters/ThingIdParam'
    get:
      operationId: get_thing
      responses:
        '200':
          description: 'Resource was retrieved successfully!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
        '412':
          description: 'Resource current ETag matches If-None-Match value.'







Compliant example:


paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#components/parameters/ThingIdParam'
    get:
      operationId: get_thing
      parameters:
        - name: If-None-Match
          in: header
          description: |-
            The operation will succeed only if the resource's current ETag value 
            does not match the value specified for this header parameter.
          schema:
            type: string
      responses:
        '200':
          description: 'Resource was retrieved successfully!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
        '412':
          description: 'Resource current ETag matches If-None-Match value.'








Rule: prohibit-summary-sentence-style





Rule id:
prohibit-summary-sentence-style




Description:
An operation's summary field should not have a trailing period.




Severity:
warn




OAS Versions:
oas3




Non-compliant example:


paths:
  /v1/things
    get:
      operationId: list_things
      summary: List Things.
      description: Retrieve a paginated collection of Thing instances.







Compliant example:


paths:
  /v1/things
    get:
      operationId: list_things
      summary: List Things
      description: Retrieve a paginated collection of Thing instances.








Rule: property-attributes





Rule id:
property-attributes




Description:
This rule performs the following checks on schemas and schema properties:



Numeric schemas (type=integer, type=number):




    

  • minimum must not be greater than maximum.
    • 

  • minimum must not be defined for a schema type other than integer or number.
    • 

  • maximum must not be defined for a schema type other than integer or number.
    • 





Array schemas (type=array):




    

  • minItems must not be greater than maxItems.
    • 

  • minItems must not be defined for a schema type other than array.
    • 

  • maxItems must not be defined for a schema type other than array.
    • 





Object schemas (type=object):




    

  • minProperties must not be greater than maxProperties.
    • 

  • minProperties must not be defined for a schema type other than object.
    • 

  • maxProperties must not be defined for a schema type other than object.
    • 











Severity:
error




OAS Versions:
oas3




Non-compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        thing_names:
          type: array
          items:
            type: string
          minItems: 10
          maxItems: 5
        thing_size:
          type: integer,
          minimum: 5
          maximum: 4







Compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        thing_names:
          type: array
          items:
            type: string
          minItems: 5
          maxItems: 10
        thing_size:
          type: integer,
          minimum: 4
          maximum: 5








Rule: property-case-collision





Rule id:
property-case-collision




Description:
Property names within a schema must be unique, even if they differ by case convention
(e.g. properties thingType and thing_type defined within the same schema would violate this rule).




Severity:
error




OAS Versions:
oas2, oas3




Non-compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          type: string
        thing_type:
          type: string
        thingType:
          type: string







Compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          type: string
        thing_type:
          type: string








Rule: property-case-convention





Rule id:
property-case-convention




Description:
Schema property names should follow a specific case convention, with the default being snake case.




Severity:
error




OAS Versions:
oas2, oas3




Configuration:
This rule can be configured to enforce a specific case convention for schema property names.
To configure the rule, set the functionOptions field within the rule definition to be an object
that is the appropriate configuration to be used by Spectral's casing() function
[1]
to enforce the desired case convention for property names.

The default configuration object provided in the rule definition is:

{
  type: 'snake'
}



To enforce a different case convention for property names, you'll need to
replace this rule with a new rule within your
custom ruleset and modify the configuration such that the value of the type field 
specifies the desired case convention.
For example, to enforce camel case for property names, the configuration object would look like this:

{
  type: 'camel'
}







Non-compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        thingId:
          type: string
        thingType:
          type: string







Compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          type: string
        thing_type:
          type: string








Rule: property-description





Rule id:
property-description




Description:
Schema properties should have a non-empty description.




Severity:
warn




OAS Versions:
oas2, oas3




Non-compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          type: string
        thing_type:
          type: string







Compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          description: The ID associated with the Thing instance.
          type: string
        thing_type:
          description: The type associated with the Thing instance.
          type: string








Rule: property-inconsistent-name-and-type





Rule id:
property-inconsistent-name-and-type




Description:
Avoid using the same property name for properties of different types.



This rule is disabled by default. Enable it in your Spectral config file to utilize this validation.





Severity:
off




OAS Versions:
oas2, oas3




Non-compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        name:
          description: The name of the Thing.
          type: string
    OtherThing:
      type: object
      properties:
        name:
          description: The name of the OtherThing.
          type: integer # The property 'name' should use consistent types throughout the API







Compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        name:
          description: The name of the Thing.
          type: string
    OtherThing:
      type: object
      properties:
        name:
          description: The name of the OtherThing.
          type: string








Rule: ref-pattern





Rule id:
ref-pattern




Description:
This rule checks each $ref value to make sure it follows the correct pattern based on
the type of object it references.  For example, a reference to a schema should follow the pattern 
#/components/schemas/<schema-name>.

Here is the full set of valid patterns for $ref values:

    

  • #/components/callbacks/<name>
    • 

  • #/components/examples/<name>
    • 

  • #/components/headers/<name>
    • 

  • #/components/links/<name>
    • 

  • #/components/parameters/<name>
    • 

  • #/components/requestBodies/<name>
    • 

  • #/components/responses/<name>
    • 

  • #/components/schemas/<name>
    • 

  • #/components/securitySchemes/<name>
    • 


The validator uses the $ref property's location within the API definition
to determine the type of object being referenced.  For example, if the
$ref property is found where a parameter object is expected, then the validator assumes
that the $ref is referencing a parameter object, and that the reference should follow
the pattern #/components/parameters/<param-name>.
Incidentally, this rule also has the effect of ensuring that various types of objects are defined in their
proper locations within the API definition's componentsfield. 





Severity:
warn




OAS Versions:
oas3




Non-compliant example:


components:
  schemas:
    Foo:
      type: object
      properties:
        bar:
          $ref: '#/definitions/Bar'
definitions:
  Bar:
    type: object
    properties:
      bar:
        type: string







Compliant example:


components:
  schemas:
    Foo:
      type: object
      properties:
        bar:
          $ref: '#/components/schemas/Bar'
    Bar:
      type: object
      properties:
        bar:
          type: string








Rule: ref-sibling-duplicate-description





Rule id:
ref-sibling-duplicate-description




Description:
This rule checks for instances where the "ref sibling" allOf pattern is used to override
the description of a referenced schema, but yet the overridden description is the same as that defined inside
the referenced schema.

Prior to OpenAPI 3.0, when defining a schema one could use a $ref along with additional attributes in order to
reference a named schema and also override those attributes defined within the referenced schema.
A common use of this pattern was to override a referenced schema's description with a more
specific description. Here is an example (a swagger 2.0 fragment):


definitions:
  PageLink:
    description: 'A link to a page of results'        <<< general description
    type: object
    properties:
      href:
        description: 'The URL string pointing to a specific page of results'
        type: string
  ResourceCollection:
    description: 'A collection of resources returned by the list_resources operation'
    type: object
    properties:
      first:
        $ref: '#/definitions/PageLink'
        description: 'A link to the first page of results'     <<< more specific description
      next:
        $ref: '#/definitions/PageLink'
        description: 'A link to the next page of results'      <<< more specific description



In this example, the "first" and "next" properties are given specific descriptions that indicate they point to
the first and next page of results, respectively.


Starting with OpenAPI 3.0, one can no longer use this pattern.  If a schema definition contains the $ref attribute,
then no other attributes are allowed to be defined alongsize it.   So to work around this restriction, 
API authors typically use the "ref sibling" allOf pattern.   The above example might look like this:

components:
  schemas:
    PageLink:
      description: 'A link to a page of results'        <<< general description
      type: object
      properties:
        href:
          description: 'The URL string pointing to a specific page of results'
          type: string
    ResourceCollection:
      description: 'A collection of resources returned by the list_resources operation'
      type: object
      properties:
        first:
          allOf:
            - $ref: '#/components/schemas/PageLink'
            - description: 'A link to the first page of results'     <<< more specific description
        next:
          description: 'A link to the next page of results'      <<< more specific description
          allOf:
            - $ref: '#/components/schemas/PageLink'


In this example the "first" property uses an allOf with two list elements, where the second list element schema overrides
the description of the PageLink schema.   The "next" property is defined using a variation of the "ref sibling" allOf pattern
where the overridden description is defined directly as an attribute of the "next" schema itself rather than in the 
second allOf list element.  Both are considered to be examples of the "ref sibling" allOf pattern.

This rule specifically looks for instances of this pattern where the overridden description is the same as the
description defined within the reference schema, thus rending the use of the "ref sibling" pattern unnecessary.
Here is an example of this:

components:
  schemas:
    PageLink:
      description: 'A link to a page of results'        <<< general description
      type: object
      properties:
        href:
          description: 'The URL string pointing to a specific page of results'
          type: string
    ResourceCollection:
      description: 'A collection of resources returned by the list_resources operation'
      type: object
      properties:
        page_link:
          allOf:
            - $ref: '#/components/schemas/PageLink'
            - description: 'A link to a page of results'     <<< duplicate description







Severity:
warn




OAS Versions:
oas3




Non-compliant example:


components:
  schemas:
    PageLink:
      description: 'A link to a page of results'
      type: object
      properties:
        href:
          description: 'The URL string pointing to a specific page of results'
          type: string
    ResourceCollection:
      description: 'A collection of resources returned by the list_resources operation'
      type: object
      properties:
        page_link:
          allOf:
            - $ref: '#/components/schemas/PageLink'
            - description: 'A link to a page of results'







Compliant example:


components:
  schemas:
    PageLink:
      description: 'A link to a page of results'
      type: object
      properties:
        href:
          description: 'The URL string pointing to a specific page of results'
          type: string
    ResourceCollection:
      description: 'A collection of resources returned by the list_resources operation'
      type: object
      properties:
        page_link:
          $ref: '#/components/schemas/PageLink'








Rule: request-body-name





Rule id:
request-body-name




Description:
The x-codegen-request-body-name extension can be set on an operation to provide a language-agnostic
name for any body parameter that might appear within generated SDK code.
For operations that support multipart-form-based request body content, this isn't necessary since the
names of the form parameters are inferred from the property names within the request body schema.
However, for operations that support other non-form-based request body content (json-based and non-json-based content alike),
it is a good practice to provide the request body name via the extension, especially in situations where there is no other
way to infer a logical name for the operation's body parameter.

This rule analyzes each operation to determine if a request body name is needed, and if so, checks to make sure 
that the x-codegen-request-body-name extension is set on the operation.






Severity:
warn




OAS Versions:
oas3




Non-compliant example:


paths:
  '/v1/logs':
    post:
      operationId: upload_logfile
      requestBody:
        content:
          'application/octet-stream':
            schema:
              type: string
              format: binary







Compliant example:


paths:
  '/v1/logs':
    post:
      operationId: upload_logfile
      x-code-gen-request-body-name: log_file   <<<
      requestBody:
        content:
          'application/octet-stream':
            schema:
              type: string
              format: binary








Rule: request-body-object





Rule id:
request-body-object




Description:
Each request body should be defined as an object.




Severity:
warn




OAS Versions:
oas3




Non-compliant example:


requestBody:
  content:
    application/json:
      schema:
        type: string







Compliant example:


requestBody:
  content:
    application/json:
      schema:
        type: object
        properties:
          prop1:
            type: string








Rule: response-error-response-schema





Rule id:
response-error-response-schema




Description:
This rule implements the guidance related to error response schemas found in the API Handbook.

Specifically, the following checks are performed against each schema associated with an error response:

    

  • The error response schema should form a valid
error container model as
described by the API Handbook.
    • 

  • The errors property must be an array whose items field is a schema that forms a valid
error model
as described in the API Handbook.
    • 

  • If present, the target property must contain a valid
error target model
as described in the API Handbook.
    • 







Severity:
warn




OAS Versions:
oas3




Non-compliant example:


paths:
  '/v1/things':
    post:
      operationId: create_thing
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Thing'
    responses:
      '201':
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Thing'
      '400':
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ErrorContainer'
components:
  schemas:
    ErrorContainer: {
      description: 'An error response for an operation.',
      type: 'object',
      properties: {
        error: {
          $ref: '#/components/schemas/Error'
        },
        trace: {
          description: 'The error trace information.',
          type: 'string',
          format: 'uuid'
        }
      }
    },
    Error: {
      description: 'An error response entry.',
      type: 'object',
      properties: {
        code: {
          description: 'The error code.',
          type: 'integer'
        },
        message: {
          description: 'The error message.',
          type: 'string'
        },
        more_info: {
          description: 'Additional info about the error.',
          type: 'string'
        },
      }
    }







Compliant example:


paths:
  '/v1/things':
    post:
      operationId: create_thing
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Thing'
    responses:
      '201':
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Thing'
      '400':
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ErrorContainer'
components:
  schemas:
    ErrorContainer: {
      description: 'An error response for an operation.',
      type: 'object',
      properties: {
        errors: {
          type: 'array',
          minItems: 0,
          maxItems: 100,
          description: 'The array of error entries associated with the error response',
          items: {
            $ref: '#/components/schemas/Error'
          }
        },
        trace: {
          description: 'The error trace information.',
          type: 'string',
          format: 'uuid'
        }
      }
    },
    Error: {
      description: 'An error response entry.',
      type: 'object',
      properties: {
        code: {
          description: 'The error code.',
          type: 'string',
          enum: ['bad_request', 'not_authorized', 'no_need_to_know']
        },
        message: {
          description: 'The error message.',
          type: 'string'
        },
        more_info: {
          description: 'Additional info about the error.',
          type: 'string'
        },
      }
    }








Rule: response-example-provided





Rule id:
response-example-provided




Description:
Response examples should be provided in the schema object - or as a sibling to the schema object -
within each response content field entry, in order to aid in the generation of API reference documentation.





Severity:
warn




OAS Versions:
oas3




Non-compliant example:


responses:
  200:
    content:
      application/json:
        schema:
          type: string







Compliant example:

The example may be provided in the schema object.

responses:
  200:
    content:
      application/json:
        schema:
          type: string
          example: 'example string'



Alternatively, the example may be provided as a sibling to the schema object.

responses:
  200:
    content:
      application/json:
        schema:
          type: string
        example: 'example string'







Rule: response-status-codes





Rule id:
response-status-codes




Description:
This rule performs a few different checks on the status codes used in operation responses:

    

  • The use of the 422 - Unprocessable Entity status code is discouraged. Use 400 - Bad Request instead.
    • 

  • The use of the 302 - Found status code is discouraged. Use 303 - See Other or 
307 - Temporary Redirect instead.
    • 

  • The 101 - Switching Protocols status code should not be used if any success status codes (2xx) are also present.
    • 

  • Each operation should include at least one success status code (2xx).  An exception to this is when the 
101 - Switching Protocols status code is used, which should be extremely rare (it's normally used with websockets).
    • 

  • A 204 - No Content response should not include content.
    • 

  • A non-204 success status code (e.g. 200 - OK, 201 - Created, etc.) should include content.
    • 

  • A "create"-type operation must return either a 201 - Created
or a 202 - Accepted status code.

    Note that for the purposes of this rule, an operation is considered to be a "create"-type operation if the
operationId starts with "create" or the operation is a POST request and there is another path
present in the API that is similar to the path of the "create" operation, but with a trailing path parameter reference.
For example, "process_things" would be considered a "create"-type operation:

      paths:
    '/v1/things':
      post:
        operationId: process_things
        ...
    '/v1/things/{thing_id}':
      get:
        operationId: get_thing

    
but "handle_things" would not:

      paths:
    '/v1/things':
      post:
        operationId: handle_things
        ...

    
The difference being that with the "handle_things" operation, there is no corresponding path
with a trailing path parameter reference that would give us a hint that "handle_things" is a create-type operation.

    • 

  • An operation that returns a 202 - Accepted status code should not return any other
success (2xx) status codes. This is because an operation should be unambiguous in terms of whether or not
it is a synchronous or asynchronous operation.



References: 







Severity:
warn




OAS Versions:
oas3




Non-compliant example:


paths:
  '/v1/things':
    post:
      operationId: create_thing
      description: 'Create a Thing instance.'
      responses:
        '204':
          description: 'should not have content'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
        '101':
          description: 'invalid use of status code 101'
        '422':
          description: 'should use status code 400 instead'







Compliant example:


paths:
  '/v1/things':
    post:
      operationId: create_thing
      description: 'Create a Thing instance.'
      responses:
        '201':
          description: 'Successfully created a new Thing instance.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
        '400':
          description: 'Thing instance was invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'








Rule: schema-description





Rule id:
schema-description




Description:
Schemas should have a non-empty description.




Severity:
warn




OAS Versions:
oas2, oas3




Non-compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        ...







Compliant example:


components:
  schemas:
    Thing:
      description: >-
        A Thing instance is used as a way to demonstrate how various
        validation rules may be applied to an API definition.
      type: object
      properties:
        ...








Rule: schema-type





Rule id:
schema-type




Description:

Schemas should have a non-empty type field.



This rule is disabled by default. Enable it in your Spectral config file to utilize this validation.





Severity:
off




OAS Versions:
oas2, oas3




Non-compliant example:


components:
  schemas:
    Thing:
      description: An underspecified schema
        ...







Compliant example:


components:
  schemas:
    Thing:
      type: string
      description: An string schema
        ...








Rule: security-scheme-attributes





Rule id:
security-scheme-attributes




Description:
Performs a series of validations on the content within security schemes to ensure they comply
with the constraints outlined in the OpenAPI Specification.

Specifically, the rule will perform these checks:

    

  1. Each security scheme must specify the type property. Valid values for the type property are:

      

    • apiKey
      • 

    • http
      • 

    • oauth2
      • 

    • openIdConnect
      • 

    

    2. 

  2. A security scheme with type apiKey must specify the name and in properties.
Valid values for the in property are:

      

    • cookie
      • 

    • header
      • 

    • query
      • 

    

    3. 

  3. A security scheme with type http must specify the scheme property.

    4. 

  4. A security scheme with type oauth2 must specify the flows property.

    Furthermore, the flows property must be an object that defines at least one of the following keys:

      

    • implicit
      • 

    • authorizationcode
      • 

    • clientCredentials
      • 

    • password
      • 

    

    

    An implicit oauth2 flow must specify the scopes and authorizationUrl properties.
    

    A password or clientCredentials oauth2 flow must specify the scopes and tokenUrl properties.
    

    An authorizationCode oauth2 flow must specify the scopes, authorizationUrl, and tokenUrl properties.
    

    5. 

  5. A security scheme with type openIdConnect must specify the openIdConnectUrl property.

    6. 







Severity:
error




OAS Versions:
oas3




Non-compliant example:


components:
  securitySchemes:
    BasicAuthScheme:
      type: http
    IAMAuthScheme:
      type: apiKey
    OAuth2Scheme:
      type: oauth2







Compliant example:


components:
  securitySchemes:
    BasicAuthScheme:
      type: http
      description: Basic authentication via the Authorization header
      scheme: Basic
      bearerFormat: bearer
    IAMAuthScheme:
      type: apiKey,
      description: An IAM access token provided via the Authorization header
      in: header
      name: Authorization
    OAuth2Scheme:
      type: oauth2
      description: Supported oauth2 authorizaton flows
      flows:
        implicit:
          authorizationUrl: https://myoauthserver.com/auth
          scopes:
            writer: User can create resources
        authorizationCode:
          authorizationUrl: https://myoauthserver.com/auth
          tokenUrl: https://myoauthserver.com/token
          scopes:
            reader: User can retrieve resources








Rule: security-schemes





Rule id:
security-schemes




Description:
Verifies the security schemes and security requirement objects.

Specifically, the rule will perform these checks:

    

  1. The name used within a security requirement object must correspond to a
security scheme that is properly defined in "components.securitySchemes".

    2. 

  2. Each security scheme defined in "components.securitySchemes" should be referenced
by at least one security requirement object.

    3. 

  3. Each scope referenced within a security requirement object for an oauth2-type security scheme
must be defined within that security scheme.

    4. 

  4. Each scope that is defined within an oath2-type security scheme should be
referenced by at least one security requirement object.

    5. 

  5. If a security requirement object is associated with a security scheme that does not support
scopes, then its scopes array MUST be empty.

    6. 







Severity:
warn




OAS Versions:
oas3




Non-compliant example:


paths:
  '/v1/things':
    post:
      operationId: create_thing
      security:
        - IAM: []   # refers to undefined security scheme "IAM"
components:
  securitySchemes:
    Basic:
      type: http
      scheme: basic







Compliant example:


paths:
  '/v1/things':
    post:
      operationId: create_thing
      security:
        - IAM: []
components:
  securitySchemes:
    IAM:
      in: header
      name: Authorization
      type: apiKey








Rule: server-variable-default-value





Rule id:
server-variable-default-value




Description:
Server variables should have a default value.




Severity:
warn




OAS Versions:
oas3




Non-compliant example:


servers:
- url: https://{region}.myservice.cloud.ibm.com
  description: The region-based endpoints available for My Service.
  variables:
    region:
      description: >-
        The name of the region, which should be one of:
          "global", "us-south", "us-east", "us-west", "us-north"







Compliant example:


servers:
- url: https://{region}.myservice.cloud.ibm.com
  description: The region-based endpoints available for My Service.
  variables:
    region:
      default: global
      description: >-
        The name of the region, which should be one of:
          "global", "us-south", "us-east", "us-west", "us-north"








Rule: string-boundary





Rule id:
string-boundary




Description:
This rule checks to make sure that string schema properties define the pattern, minLength and maxLength
fields in order to clearly define the set of valid values for the property.
[1].

Note that these checks are bypassed for the following scenarios:

    

  • All checks are bypassed for string schemas that are used only within an operation response.

  • All checks are bypassed for string schemas that contain an enum field.
    • 

  • The check for the pattern field is bypassed if format is set to 
binary, byte, date, date-time, or url.
    • 

  • The check for the minLength field is bypassed if format is set to
date, identifier, or url.
    • 

  • The check for the maxLength field is bypassed if format is set to date.
    • 



This rule also checks non-string schema properties to make sure they do not define the
code>pattern, minLength and maxLength fields since these fields are applicable
only for string schemas.






Severity:
warn




OAS Versions:
oas3




Non-compliant example:


components:
  schemas:
    Thing:
      description: A Thing instance.
      type: object
      properties:
        thing_id:
          description: The unique identifier of the Thing instance.
          type: string







Compliant example:


components:
  schemas:
    Thing:
      description: A Thing instance.
      type: object
      properties:
        thing_id:
          description: The unique identifier of the Thing instance.
          type: string
          pattern: '^[a-zA-Z0-9]*$'
          minLength: 8
          maxLength: 64
          example: 'ab38dd26z'








Rule: unused-tag





Rule id:
unused-tag




Description:
This rule verifies that each tag (defined in the tags field) is referenced by one or more operations.




Severity:
warn




OAS Versions:
oas3




Non-compliant example:


tags:
  - name: Things
    description: Operations related to Things.
  - name: UnusedTag
    description: This tag is not used.

paths:
'/v1/things':
post:
operationId: create_thing
description: Create a new Thing instance.
summary: Create a Thing
tags:
- Things







Compliant example:


tags:
  - name: Things
    description: Operations related to Things.

paths:
'/v1/things':
post:
operationId: create_thing
description: Create a new Thing instance.
summary: Create a Thing
tags:
- Things








Rule: valid-path-segments





Rule id:
valid-path-segments




Description:
This rule validates the path segments within each path string found in the API.
Specifically, the rule makes sure that any path segment containing a path parameter reference contains
only that parameter reference and nothing more.
For example, the path /v1/foos/_{foo_id}_ is invalid and should probably be /v1/foos/{foo_id}.





Severity:
error




OAS Versions:
oas2, oas3




Non-compliant example:


paths:
  '/v1/foos/_{foo_id}_':
    parameters:
      - $ref: '#/components/parameters/FooIdParam'
  get:
    operationId: get_foo
    ...







Compliant example:


paths:
  '/v1/foos/{foo_id}':
    parameters:
      - $ref: '#/components/parameters/FooIdParam'
  get:
    operationId: get_foo
    ...








Rule: valid-type-format





Rule id:
valid-type-format




Description:
Schemas and schema properties must use a valid combination of the type and format fields
[1].
The following table defines the valid combinations:



TypeFormats



string


    

  • binary
    • 

  • byte
    • 

  • crn
    • 

  • date
    • 

  • date-time
    • 

  • email
    • 

  • identifier
    • 

  • password
    • 

  • url
    • 

  • uuid
    • 






boolean


integer
  • int32
  • int64


number
  • float
  • double


object


array








Severity:
error




OAS Versions:
oas3




Non-compliant example:


components:
  schemas:
    Thing:
      type: bad_object
      properties:
        thing_url:
          type: url
        thing_crn:
          type: crn
        thing_cost:
          type: float
        thing_contents:
          type: byte-array







Compliant example:


components:
  schemas:
    Thing:
      type: object
      properties:
        thing_url:
          type: string
          format: url
        thing_crn:
          type: string
          format: crn
        thing_cost:
          type: number
          format: float
        thing_contents:
          type: string
          format: byte