IBM Cloud Validation Ruleset

This rule is deprecated. Please use the ibm-no-required-properties-in-optional-body rule instead.

requestBody:
  content:
    'application/json':
      schema:
        type: object
        description: A dictionary-based request body, that should be a model
        additionalProperties:
          type: string

requestBody:
  content:
    'application/json':
      schema:
        # Note that this should be defined through a "reference" to a
        # named schema, using an inline schema for display purposes.
        type: object
        description: A model of a "Person" resource
        properties:
          name:
            type: string
            description: Name of the person
          age:
            type: integer
            description: Age of the person, in years

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
          pattern: 'id-[0-9a-fA-F]+'

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
          pattern: '^id-[0-9a-fA-F]+$'

This convention ensures that resource-oriented APIs are symmetrical between requests and responses in how resources are represented.

Note: the rule will report additional details about each violation of the graph fragment pattern through "info" level logs. Pass the option --log-level ibm-api-symmetry=info to see more info about any violations that occur.

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        age:
          type: integer
    ThingPrototype:
      name:
        type: string
      age:
        type: integer
      color:            # Does not exist on the resource!
        type: string
paths:
  /v1/things:
    post:
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ThingPrototype'
  /v1/things/{id}:
    get:
      responses:
        200:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Thing'

  components:
    schemas:
      Thing:
        type: object
        properties:
          id:
            type: string
          name:
            type: string
          age:
            type: integer
      ThingPrototype:      # A proper subset of properties
        name:
          type: string
        age:
          type: integer
  paths:
    /v1/things:
      post:
        requestBody:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ThingPrototype'
    /v1/things/{id}:
      get:
        responses:
          200:
            content:
              'application/json':
                schema:
                  $ref: '#/components/schemas/Thing'

components:
  schemas:
    Array:
      description: An Array instance.
      type: array

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

Specifically, this rule warns about the use of inline object schemas within request bodies, responses, and nested schemas (e.g. a schema property, an array items schema, an additionalProperties schema, etc.).

More information about this can be found in the API Handbook.

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        version:
          type: object
          properties:
            major:
              type: string
            minor:
              type: string
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:
                id:
                  type: string
                version:
                  type: object
                  properties:
                  major:
                    type: string
                  minor:
                    type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                description: A Thing instance.
                properties:
                  id:
                    type: string
                  version:
                    type: object
                    properties:
                    major:
                      type: string
                    minor:
                      type: string

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        version:
          $ref: '#/components/schemas/ThingVersion'
    ThingVersion:
      type: object
      properties:
        major:
          type: string
        minor:
          type: string
paths:
  /v1/things:
    post:
      operationId: create_thing
      description: Create a new Thing instance.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Thing'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'

This rule will return an error for schemas that are defined with multiple types (e.g. ['string', 'integer', 'boolean']). One exception to this is that the special type "null" is simply ignored by the rule when counting the number of elements in the schema's type field. So, the type value ['string', 'integer'] would cause an error, but the type value ['string', 'null'] would not.

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        metadata:
          description: additional info about the thing
          type:
            - string
            - boolean
            - integer
            - null

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        metadata:
          description: additional info about the thing
          type:
            - string
            - null

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

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

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.

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

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

• 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.

paths:
  '/v1/logfile':
    get:
      operationId: download_logfile
      responses:
        '200':
          description: 'Download confirmed!'
          content:
            application/json:
              schema:
                type: string
                format: binary

paths:
  '/v1/logfile':
    get:
      operationId: download_logfile
      responses:
        '200':
          description: 'Download confirmed!'
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

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}").

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'

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

responses:
  200:
    description: 'Success response!'
    content:
      application/json:
        # schema not provided

responses:
  200:
    description: 'Success response!'
    content:
      application/json:
        schema:
          type: string

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

requestBody:
  content:
    '*/*':
      ...

requestBody:
  content:
    'application/json':
      ...
    'text/plain':
      ...

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

components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          type: string
      required:
        - thing_id
        - thing_version

components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          type: string
        thing_version:
          type: string
      required:
        - thing_id
        - thing_version

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.

components:
  schema:
    Thing:
      description: A Thing instance.
      type: object
      properties:
        thing_id:
          type: string
        thing_version:
          type: string
      discriminator:
        propertyName: thing_type

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

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

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

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

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'
}

components:
  schemas:
    ThingType:
      type: string
      enum:
        - thingType1
        - thingType2

components:
  schemas:
    ThingType:
      type: string
      enum:
        - thing_type_1
        - thing_type_2

responses:
  400:
    content:
      'application/octet-stream':
        ...

responses:
  400:
    content:
      'application/json':
        ...

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.

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

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

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 should 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.

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!'

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!'

components:
  schemas:
    Thing:
      description: A Thing instance.
      type: object
      properties:
        thing_size:
          description: The size of the Thing instance, in ml.
          type: integer

components:
  schemas:
    Thing:
      description: A Thing instance.
      type: object
      properties:
        thing_size:
          description: The size of the Thing instance, in ml.
          type: integer
          minimum: 0
          maximum: 1000

openapi: 3.0.1
info:
  version: 1.0.0
  ...
paths:
  /things:
    ...

openapi: 3.0.1
info:
  version: 1.0.0
  ...
paths:
  /v1/things:
    ...

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'

paths:
  '/v1/things':
    get:
      operationId: list_things
      responses:
        '200':
          description: 'Success response!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingCollection'

• the two paths contain the same number of path segments (e.g. /v1/foo, /v1/{foo})
• when comparing each of the respective path segments in each path string:
  1. both path segments are non-parameterized and are equal (e.g. 'foo' vs 'foo')
  2. one or the other of the path segments is parameterized (e.g. 'foo' vs '{foo_id}')
  3. both of the path segments are parameterized (e.g. '{foo_id}' vs '{id}')

• /v1/things/{thing_id}, /v1/things/{id}
• /v1/things/{thing_id}, /v1/things/other_things
• /{version}/things, /v1/{things}

paths:
  '/v1/things/{thing_id}':
    ...
  '/v1/things/{foo_id}':
    ...
  '/v1/things/other_things':
    ...

paths:
  '/v1/things/{thing_id}':
    ...
  '/v1/foos/{foo_id}':
    ...
  '/v1/things/{thing_id}/other_things':
    ...

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

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

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"} ]

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"} ]}

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.

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'

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'

This rule has been deprecated and is now disabled in the IBM Cloud Validation Ruleset. Please use the ibm-no-operation-requestbody rule instead.

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'

paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#/components/parameters/ThingIdParam'
    delete:
      operationId: delete_thing
      responses:
        '204':
          description: 'The thing was deleted'

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

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

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

paths:
  '/v1/foos/{foo_id}/bars/{bar_id}':
    parameters:
      - $ref: '#/components/parameters/FooIdParam'
      - $ref: '#/components/parameters/BarIdParam'
  get:
    operationId: get_foobar
    ...

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'

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'

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"

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

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

components:
  parameters:
    SortOrderParam:
      name: sort_order
      description: The sort order.
      in: query
      required: true
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc

components:
  parameters:
    SortOrderParam:
      name: sort_order
      description: The sort order.
      in: query
      required: true
      schema:
        type: string
        enum:
          - asc
          - desc

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'

This rule specifically looks for instances of this pattern where the overridden description is the same as the description defined within the referenced schema, thus making 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

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'

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'

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

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.'

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.'

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

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.'

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.'

components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          type: string
        thing_name:
          type: string
        thing_size:
          type: integer
        thing_type:
          type: string
          nullable: true   <<< not valid in a response schema
    ThingPatch:
      type: object
      properties:
        thing_name:
          type: string
           nullable: true   <<< valid only in a merge-path requestBody schema
        thing_size:
          type: integer
          nullable: true   <<< valid only in a merge-path requestBody schema
        thing_type:
          type: string
          nullable: true   <<< valid only in a merge-path requestBody schema
paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#/components/parameters/ThingIdParameter'
    patch:
      operationId: update_thing
      requestBody:
        description: An object used to modify an existing Thing instance
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ThingPatch'
      responses:
        '200':
          description: Thing instance was updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'

components:
  schemas:
    Thing:
      type: object
      properties:
        thing_id:
          type: string
        thing_name:
          type: string
        thing_size:
          type: integer
        thing_type:    <<< property is no longer nullable
          type: string
    ThingPatch:
      type: object
      properties:
        thing_name:
          type: string
           nullable: true
        thing_size:
          type: integer
          nullable: true
        thing_type:
          type: string
          nullable: true
paths:
  '/v1/things/{thing_id}':
    parameters:
      - $ref: '#/components/parameters/ThingIdParameter'
    patch:
      operationId: update_thing
      requestBody:
        description: An object used to modify an existing Thing instance
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/ThingPatch'
      responses:
        '200':
          description: Thing instance was updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'

The default configuration object provided with the rule is:

{
  httpMethods: ['delete', 'get', 'head', 'options']
}

To configure the rule with a different set of HTTP methods, 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 httpMethods field specifies the desired set of HTTP methods to be checked. For example, to enforce the rule for DELETE, HEAD and OPTIONS operations, the configuration object would look like this:

{
  httpMethods: ['delete', 'head', 'options']
}

paths:
  '/v1/things/search':
    get:
      operationId: search_things
      requestBody:
        description: 'An object containing the search-related properties: filter, sort'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThingSearchRequest'
      responses:
        '200':
          description: 'Search completed successfully'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingSearchResponse'

paths:
  '/v1/things/search':
    get:
      parameters:
        - name: filter
          in: query
          description: The search filter to use.
          schema:
            type: string
        - name: sort
          in: query
          description: The sort order.
          schema:
            type: string
      operationId: search_things
      responses:
        '200':
          description: 'Search completed successfully'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingSearchResponse'

This rule is deprecated. Please use the ibm-no-required-properties-in-optional-body rule instead.

paths:
  '/v1/things':
    post:
      operationId: create_thing
      requestBody:
        required: false
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Thing'    # Assume "Thing" schema has required properties

paths:
  '/v1/things':
    post:
      operationId: create_thing
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Thing'    # Assume "Thing" schema has required properties

paths:
  /v1/things:
    post:
      operationId: create_thing
      description: Create a new Thing instance.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Thing'
            example:
              $ref: '#/components/examples/ThingExample'

paths:
  /v1/things:
    post:
      operationId: create_thing
      description: Create a new Thing instance.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Thing'
            example:
              name: 'Thing1'
              description: 'An example Thing object'

paths:
  '/v1/things':
    post:
      operationId: create_thing
      requestBody:
        required: false
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Thing'    # Assume "Thing" schema has required properties

paths:
  '/v1/things':
    post:
      operationId: create_thing
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Thing'    # Assume "Thing" schema has required properties

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:
        ...

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:
        ...

components:
  schemas:
    Thing:
      properties:
        foo_ref:
          allOf:
            - $ref: '#/components/schemas/Foo'
<

components:
  schemas:
    Thing:
      properties:
        foo_ref:
          $ref: '#/components/schemas/Foo'

openapi: 3.1.0
info:
  title: Thing Service
  description: A service that manages Things
  version: 1.0.0
jsonSchemaDialect: 'https://spec.openapis.org/oas/3.1/dialect/base'    <<< not supported
webhooks:                                                              <<< not supported
  newThingTypeAvailable:
    post:
      description: |-
        A callback-like operation to be implemented by the client so that it
        can be informed of a new type of Thing supported by the server.
      requestBody:
        description: 'A new type of Thing can now be created on the server.'
          content:
            application/json:
              schema:
                type: object,
                properties:
                  thing_type:
                    description: 'The new type value that can be used to create a Thing instance.'
                    type: string
      responses:
        '200':
          description: |-
            Return a 200 status code to the server to indicate that the new Thing type
            was received successfully by the client.

openapi: 3.1.0
info:
  title: Thing Service
  description: A service that manages Things
  version: 1.0.0

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

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

paths:
  '/v1/things':
    post:
      operationId: create_thing

paths:
  '/v1/things':
    post:
      operationId: create_thing
      responses:
        '201':
          description: 'The Thing instance was created successfully'
          content:
            application/json:
              schema:
                type: object
                properties:
                  thing_id:
                    type: string
                  thing_description:
                    type: string

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

paths:
  '/v1/things':
    get:
      operationId: create_thing
      description: Create a new Thing instance.
      summary: Create a Thing

paths:
  '/v1/things':
    post:
      operationId: create_thing
      description: Create a new Thing instance.
      summary: Create a shiny, brand new, hot-off-the-press instance of the standard Thing resource

paths:
  '/v1/things':
    get:
      operationId: create_thing
      description: Create a new Thing instance.
      summary: Create a Thing

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'
}

paths:
  '/v1/things':
    post:
      operationId: createThing

paths:
  '/v1/things':
    post:
      operationId: create_thing

This rule will analyze the operations, looking for operationId values that are not using the recommended verbs. Furthermore it can also validate the complete name of the operation id by comparing it to the path segments.

The default configuration object provided in the rule definition is:

{
  strict: true
}

To switch off the complete name validation and only validate the verbs the operation ids begin with, 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 strict field to false

{
  strict: false
}

paths:
  '/v1/things':
    post:
      operationId: manufacture_thing
      description: Create a new Thing instance.
      summary: Create a Thing
    get:
      operationId: list_thing
      description: List all Thing instances.
      summary: List Thing
  '/v1/things/{thing_id}':
    get:
      operationId: retrieve_thing
      description: Get a Thing instance.
      summary: Get a Thing

paths:
  '/v1/things':
    post:
      operationId: create_thing
      description: Create a new Thing instance.
      summary: Create a Thing
    get:
      operationId: list_things
      description: List all Thing instances.
      summery: List Things
  '/v1/things/{thing_id}':
    get:
      operationId: get_thing
      description: Get a Thing instance.
      summary: Get a Thing

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].

The default configuration object provided in the rule definition is:

{
  query: {
    type: 'snake',
    separator: {
      char: '.'
    }
  },
  path: {
    type: 'snake'
  },
  // Spectral casing convention types aren't robust enough to handle
  // the complexity of headers, so we define our own kebab/pascal case regex.
  header: {
    match: '/^[A-Z]+[a-z0-9]*-*([A-Z]+[a-z0-9]*-*)*$/',
  },
  headerMessage: 'Header parameter names must be kebab-separated pascal case',
}

• 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'
  }
}

components:
  parameters:
    SortOrderParam:
      name: sortOrder           << camel-case
      description: The sort order.
      in: query
      required: false
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc

components:
  parameters:
    SortOrderParam:
      name: sort_order        << snake-case
      description: The sort order.
      in: query
      required: false
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc

components:
  parameters:
    SortOrderParam:
      name: sort_order
      in: query
      required: false
      schema:
        type: string
        enum:
          - asc
          - desc
        default: asc

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

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

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

parameters:
- name: param1
  in: query
  description: query param

parameters:
- name: param1
  in: query
  description: query param
  schema:
    type: string

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

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!'

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!'

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'
}

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

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

• The patternProperties field must be an object with exactly one entry.
• The patternProperties and additionalProperties fields are mutually exclusive within a particular schema.
• The patternProperties field must contain a regular expression anchored by ^ and $.

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        metadata:
          description: additional info about the thing
          type: object
          patternProperties:
            '^foo.*$':
              type: string
            '^bar.*$':
              type: integer

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        metadata:
          description: additional info about the thing
          type: object
          patternProperties:
            '^(foo|bar).*$':
              type: string

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.'

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.'

paths:
  '/v1/things/':
    get:
      operationId: list_things
      parameters:
        - name: offset
          in: query
          description: 'The offset of the first item to return.'
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
        - name: limit
          in: query
          description: 'The number of items to return per page.'
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
            maximum: 100
            default: 10
      responses:
        '200':
          description: 'Resources retrieved successfully!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingCollection'
        '400':
          description: 'List operation failed.'

paths:
  '/v1/things/':
    get:
      operationId: list_things
      parameters:
        - name: start
          in: query
          description: 'The token representing the first item to return.'
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 64
            pattern: '[a-zA-Z0-9 ]+'
        - name: limit
          in: query
          description: 'The number of items to return per page.'
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
            maximum: 100
            default: 10
      responses:
        '200':
          description: 'Resources retrieved successfully!'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThingCollection'
        '400':
          description: 'List operation failed.'

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.
• multipleOf must not be defined for a schema type other than integer or number.
• exclusiveMaximum must not be defined for a schema type other than integer or number.
• exclusiveMinimum must not be defined for a schema type other than integer or number.

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.
• additionalProperties must not be defined for a schema type other than object.
• properties must not be defined for a schema type other than object.
• required must not be defined for a schema type other than object.

components:
  schemas:
    Thing:
      type: object
      properties:
        thing_size:
          type: integer,
          minimum: 5
          maximum: 4

components:
  schemas:
    Thing:
      type: object
      properties:
        thing_size:
          type: integer,
          minimum: 4
          maximum: 5

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'
}

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

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

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

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

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

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

• Regarding 30x responses a response body should only accompany any 301, 302, 305, 307.
• If a response body is provided for a 30x response, it must contain the following fields: code, target and message.
• For a 30x response the code field must contain one of the following values for redirect code and nothing else: forwarded, resolved, moved, remote_region, remote_account, version_mismatch.

References:

• IBM Cloud API Handbook: Fundamentals/Status Codes

paths:
  '/v1/things':
    post:
      operationId: create_thing
      description: 'Create a Thing instance.'
      responses:
        '301':
          description: 'Only partial data'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
              code: 'remote_region'
              message: 'The requested resource is in a different region'
              target:
                crn: 'crn:v1:bluemix:public:is:us-south-1:a/aa2432b1fa4d4ace891e9b80fc104e34::share:r134-a0c07083-f411-446c-9316-7b08d6448c86'
                href: 'https://us-south.iaas.cloud.ibm.com/v1/shares/r134-a0c07083-f411-446c-9316-7b08d6448c86'
                id: 'r134-a0c07083-f411-446c-9316-7b08d6448c86'
                name: 'my-share'
                remote:
                  region:
                    href: 'https://us-east.iaas.cloud.ibm.com/v1/regions/us-south'
                    name: 'us-south'
                    resource_type: 'region'
                resource_type: 'share'

paths:
  '/v1/things':
    post:
      operationId: create_thing
      description: 'Create a Thing instance.'
      responses:
        '301':
          description: 'Only partial data'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thing'
              code: 'remote'

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>

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

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

responses:
  200:
    description: 'Success response!'

responses:
  200:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Thing'

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

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

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.

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

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

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

paths:
  '/v1/thing':
    get:
      operationId: list_things
      responses:
        200:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ThingCollection'
components:
  schemas:
    ThingCollection:
      type: object
      properties:
        things:            << array property is optional
          type: array
          items:
            $ref: '#/components/schemas/Thing'

paths:
  '/v1/thing':
    get:
      operationId: list_things
      responses:
        200:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ThingCollection'
components:
  schemas:
    ThingCollection:
      type: object
      required:
        - things          << array property is now required
      properties:
        things:
          type: array
          items:
            $ref: '#/components/schemas/Thing'

paths:
  '/v1/thing':
    get:
      operationId: list_things
      responses:
        200:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ThingCollection'
components:
  schemas:
    ThingCollection:
      type: object
      required: 
        - things
      properties:
        things:
          type: array
          items:
            $ref: '#/components/schemas/Thing'
        collection_status:  << optional enumeration property
          type: string
          enum:
            - preliminary
            - final
            - under_review

paths:
  '/v1/thing':
    get:
      operationId: list_things
      responses:
        200:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ThingCollection'
components:
  schemas:
    ThingCollection:
      type: object
      required: 
        - things
        - collection_status   << enumeration property is now required
      properties:
        things:
          type: array
          items:
            $ref: '#/components/schemas/Thing'
        collection_status:
          type: string
          enum:
            - preliminary
            - final
            - under_review

paths:
  '/v1/thing':
    post:
      operationId: create_thing
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ThingPrototype'
      responses:
        201:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/OtherThing' # should be a ref to 'Thing'
  '/v1/thing/{id}':
    get:
      operationId: get_thing
      responses:
        200:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Thing'

paths:
  '/v1/thing':
    post:
      operationId: create_thing
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ThingPrototype'
      responses:
        201:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Thing'
  '/v1/thing/{id}':
    get:
      operationId: get_thing
      responses:
        200:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Thing'

• 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. The one exception is, it may return a 204 - No Content status code if the corresponding GET request for the same resource also returns a 204 - No Content status code (which indicates there is no body representation for the resource).
• A PUT operation must return either a 200 - OK, 201 - Created, or 202 - Accepted status code.
• A PATCH operation must return either a 200 - OK or a 202 - Accepted status code.
• Status codes 301, 302, 305, 307 should include a response body.

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:

• IBM Cloud API Handbook: Fundamentals/Status Codes
• IBM Cloud API Handbook: Fundamentals/Methods
• RFC7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

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'

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'

The default configuration object provided in the rule definition is:

{
  match: '/^[A-Z]+[a-z0-9]+([A-Z]+[a-z0-9]*)*$/'
}

To enforce a different case convention for schema name 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 match field specifies the desired case convention. For example, to disallow capitalized acronymns for schema names, the configuration object would look like this:

{
  match: '/^[A-Z][a-z0-9]+([A-Z][a-z0-9]+)*$/'
}

components:
  schemas:
    specific_thing:
      type: object
      properties:
        ...

components:
  schemas:
    SpecificThing:
      type: object
      properties:
        ...

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

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:
        ...

The default configuration object provided with the rule is:

{
  keywordAllowList: [
    '$ref',
    'additionalProperties',
    'allOf',
    'anyOf',
    'default',
    'description',
    'discriminator',
    'enum',
    'example',
    'examples',
    'exclusiveMaximum',
    'exclusiveMinimum',
    'format',
    'items',
    'maximum',
    'maxItems',
    'maxLength',
    'maxProperties',
    'minimum',
    'minItems',
    'minLength',
    'minProperties',
    'multipleOf',
    'not',
    'oneOf',
    'pattern',
    'patternProperties',
    'properties',
    'readOnly',
    'required',
    'title',
    'type',
    'uniqueItems',
    'unevaluatedProperties',
    'writeOnly',
  ]
}

To configure the rule with a different set of allowable keywords, 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 keywordAllowList field contains the desired set of keywords to be checked. For example, to configure the rule so that uniqueItems and unevaluatedProperties are disallowed, modify the configuration to remove these keywords from the keywordAllowList configuration field, like this:

{
  keywordAllowList: [
    '$ref',
    'additionalProperties',
    'allOf',
    'anyOf',
    'default',
    'description',
    'discriminator',
    'enum',
    'example',
    'examples',
    'exclusiveMaximum',
    'exclusiveMinimum',
    'format',
    'items',
    'maximum',
    'maxItems',
    'maxLength',
    'maxProperties',
    'minimum',
    'minItems',
    'minLength',
    'minProperties',
    'multipleOf',
    'not',
    'oneOf',
    'pattern',
    'patternProperties',
    'properties',
    'readOnly',
    'required',
    'title',
    'type',
    'writeOnly',
  ]
}

components:
  schemas:
    Things:
      type: object
      properties:
        thing_id:
          type: string
          $comment: A comment about this property definition
          nullable: true

components:
  schemas:
    Things:
      type: object
      properties:
        thing_id:
          description: A comment about this property definition
          type:
            - string
            - null

The rule checks the names of collection schemas, resource collection element schemas, creation/replacement schemas, and patch schemas against the name of the associated canonical schema to ensure the names follow the guidelines.

paths:
  /v1/things:
    post:
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ThingCreator' # Should be ThingPrototype
  /v1/things/{id}:
    get:
      responses:
        200:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Thing' # Canonical schema

paths:
  /v1/things:
    post:
      requestBody:
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/ThingPrototype'
  /v1/things/{id}:
    get:
      responses:
        200:
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Thing'

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

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

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

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

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. A security scheme with type apiKey must specify the name and in properties. Valid values for the in property are:
   • cookie
   • header
   • query
3. A security scheme with type http must specify the scheme property.
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. A security scheme with type openIdConnect must specify the openIdConnectUrl property.

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

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

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. Each security scheme defined in "components.securitySchemes" should be referenced by at least one security requirement object.
3. Each scope referenced within a security requirement object for an oauth2-type security scheme must be defined within that security scheme.
4. Each scope that is defined within an oath2-type security scheme should be referenced by at least one security requirement object.
5. If a security requirement object is associated with a security scheme that does not support scopes, then its scopes array MUST be empty.

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

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

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"

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"

Note that these checks are bypassed for the following scenarios:

• 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 pattern, minLength and maxLength fields since these fields are applicable only for string schemas.

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

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'

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

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'

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

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

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        metadata:
          description: additional info about the thing
          type: object
      unevaluatedProperties:
        type: string

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        metadata:
          description: additional info about the thing
          type: object
      unevaluatedProperties: false

And more specifically, IBM's OpenAPI SDK Generator will "explode" an operation's request body under certain circumstances in order to simplify the application code required to invoke the operation. This means that, instead of representing the operation's request body as a single operation parameter, the generator will expose each of the properties defined in the operation's request body schema such that they appear to be individual operation parameters. This optimization makes it easier for an SDK user to construct an instance of the request body schema (class, struct, etc.) when invoking the operation.

Because the request body schema properties are exposed as operation parameters, the generator must detect if there are any name collisions between these schema properties and the operation's other parameters. The generator will rename the request body schema properties if any collisions are detected, but the names computed by the generator are not optimal from a usability standpoint, so it's better for the API to be defined such that the name collisions are avoided altogether.

This validation rule checks each operation for name collisions between the operation's parameters and its request body schema properties. An error is logged for each collision. Each of these errors should be addressed by renaming either the parameter or request body schema property to avoid the collision.

paths:
  /v1/things:
    parameters:
      - in: query
        name: thing_type
        schema:
          type: string
    post:
      operationId: create_thing
      parameters:
        - in: query
          name: thing_size
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                thing_type:
                  type: string
                thing_size:
                  type: integer
                created_at:
                  type: string
                  format: date-time
                created_by:
                  type: string
                  format: email

paths:
  /v1/things:
    parameters:
      - in: query
        name: thing_type
        schema:
          type: string
    post:
      operationId: create_thing
      parameters:
        - in: query
          name: thing_size
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                size:
                  type: integer
                created_at:
                  type: string
                  format: date-time
                created_by:
                  type: string
                  format: email

Resource
  type: object
  properties:
    created_at: # Name indicates it should be a date or date-time
      type: integer
    stamp: # Example value indicates it should be a date-time
      type: string
      example: '1990-12-31T23:59:60Z'
    ...

Resource
  type: object
  properties:
    created_at:
      type: string
      format: date-time
    stamp:
      type: string
      format: date-time
      example: '1990-12-31T23:59:60Z'
    ...

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

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

components:
  schemas:
    Foo:
      type: string
      example: 42

components:
  schemas:
    Foo:
      type: string
      example: 'value'

components:
  schemas:
    AmbiguousDictionary:
      type: object
      additionalProperties: true # No type description of the values in the dictionary
    ProblematicHybird:
      type: object
      properties:
        name:
          type: string
      additionalProperties: # If the schema is a model, all property names/types should be explicit
        type: integer

  components:
    schemas:
      DefinedDictionary:
        type: object
        additionalProperties:
          type: string # Map of string to type string
          minLength: 1
          maxLength: 42
      DefinedModel:
        type: object
        properties:
          name:
            type: string