Skip to main content

Rules

R0001​

HTTP method mismatch​

The HTTP method does not match the method defined in the specification.

Why this is a problem

Method mismatches indicate the consumer or provider is calling the wrong operation, which can lead to unexpected behavior or missing functionality.

Example:

paths:
  /orders:
    get:
      responses:
        "200":
          description: OK

Request from consumer to mock:

POST /orders HTTP/1.1

The contract expects GET /orders, but the request uses POST, so a method mismatch is reported.

How this can be resolved

  • Update the client or provider to use the method defined in the specification.
  • If the method should be different, update the specification accordingly.

R0002​

HTTP status mismatch​

The HTTP status code does not match the expected status code defined in the specification.

Why this is a problem

Status codes communicate outcome semantics; a mismatch can mislead clients about success or failure.

Example:

paths:
  /orders:
    get:
      responses:
        "200":
          description: OK

Response from provider during a contract test:

HTTP/1.1 404 Not Found

The contract expects a 200 response, but the provider returns 404, so a status mismatch is reported.

How this can be resolved

  • Return the status code defined in the specification.
  • If the actual status is correct, update the specification to reflect it.

R0007​

No matching security scheme​

The request does not satisfy the requirements of any defined security scheme.

Why this is a problem

Security schemes define how clients authenticate; failing to meet them means the request is not authorized by the contract.

Example:

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
security:
  - apiKeyAuth: []

Request from consumer to mock:

GET /orders HTTP/1.1

The request does not include the required X-API-Key header, so no matching security scheme is reported.

How this can be resolved

  • Provide credentials that satisfy one of the defined security schemes.
  • If authentication is not required, remove or update the security requirement in the specification.

R1001​

Type mismatch​

The value type does not match the expected type defined in the specification.

Why this is a problem

Type mismatches cause validation failures and make clients/providers interpret data incorrectly.

Example:

type: object
required:
  - price
properties:
  price:
    type: number

Response from provider during a contract test:

{"price": "9.99"}

When validating the response from the provider, price is a string instead of a number, so the contract test reports a type mismatch.

How this can be resolved

  • Update the provider to return a numeric price, not a string.
  • If the string is correct, update the specification to accept a string type.

R1002​

Value mismatch​

The value does not match the expected value defined in the specification.

Why this is a problem

Exact-value expectations (like enums or consts) are used to guarantee fixed semantics; mismatches break downstream logic.

Example:

type: object
required:
  - status
properties:
  status:
    type: string
    enum: [created, confirmed]

Request from consumer to mock:

{"status": "pending"}

During validation of the request from consumer to mock, status is not one of the allowed enum values, so a value mismatch is reported.

How this can be resolved

  • Send a value that matches the specification enum.
  • If the new value is valid, update the specification enum to include it.

R1003​

Constraint violation​

The value does not satisfy the constraints defined in the specification.

Why this is a problem

Constraints like length, pattern, or range protect clients and providers from invalid or out-of-bounds data.

Example:

type: object
required:
  - username
properties:
  username:
    type: string
    minLength: 6

Request from consumer to mock:

{"username": "amy"}

The request from consumer to mock is validated and fails because username is shorter than the minimum length.

How this can be resolved

  • Provide values that satisfy the constraint (e.g., a longer username).
  • If the constraint is too strict, relax it in the specification.

R2001​

Missing required property​

A required property defined in the specification is missing.

Why this is a problem

Required properties are essential for processing; missing them can make behavior ambiguous or incorrect.

Example:

type: object
required:
  - email
properties:
  email:
    type: string
  name:
    type: string

Request from consumer to mock:

{"name": "Maya"}

Request validation fails because email is required but missing.

How this can be resolved

  • Include all required properties in the payload.
  • If the property should not be required, update the specification.

R2002​

Missing optional property​

An optional property defined in the specification is missing.

Why this is a problem

In strict validation modes where optional properties are treated as mandatory, missing optional data can hide partial responses.

Example:

type: object
required:
  - id
properties:
  id:
    type: integer
  description:
    type: string

Response from provider during a contract test (with optional fields treated as mandatory):

{"id": 101}

When optional fields are enforced, the missing description is reported as an optional property missing violation.

How this can be resolved

  • Provide the optional property when running with strict key checking.
  • If strict checking is not intended, run with the default optional behavior.
  • If the property should be required, mark it as required in the specification.

R2003​

Unknown property​

A property was found that is not defined in the specification.

Why this is a problem

Unexpected properties can signal drift between provider behavior and the specification, and may not be handled by clients.

Example:

type: object
additionalProperties: false
required:
  - id
properties:
  id:
    type: integer
  status:
    type: string

Payload being validated:

{"id": 5, "status": "active", "extra": "debug"}

During response validation, extra is not defined and additionalProperties: false disallows it, so an unknown property violation is reported.

How this can be resolved

  • Remove unexpected properties from the payload.
  • If the property is valid, add it to the specification or allow additional properties.

R3001​

Discriminator mismatch​

The value provided does not match the discriminator defined in the specification.

Why this is a problem

Discriminators determine which schema applies; an unknown discriminator value makes the payload ambiguous.

Example:

oneOf:
  - $ref: "#/components/schemas/Cat"
  - $ref: "#/components/schemas/Dog"
discriminator:
  propertyName: type
  mapping:
    Cat: "#/components/schemas/Cat"
    Dog: "#/components/schemas/Dog"
components:
  schemas:
    Cat:
      type: object
      required:
        - type
        - whiskers
      properties:
        type:
          type: string
        whiskers:
          type: integer
    Dog:
      type: object
      required:
        - type
        - bark
      properties:
        type:
          type: string
        bark:
          type: boolean

Request from consumer to mock:

{"type": "Parrot", "beakLength": 10}

The discriminator value does not match any mapping, so validation of the request from consumer to mock reports a discriminator mismatch.

How this can be resolved

  • Use a discriminator value that maps to a defined schema.
  • If a new subtype is needed, add it to the specification and discriminator mapping.

R3002​

Invalid discriminator setup​

The discriminator property defined in the specification is missing from the subschemas.

Why this is a problem

If subschemas do not define the discriminator property, validation cannot reliably select the correct schema.

Example:

oneOf:
  - $ref: "#/components/schemas/Cat"
  - $ref: "#/components/schemas/Dog"
discriminator:
  propertyName: type
  mapping:
    Cat: "#/components/schemas/Cat"
    Dog: "#/components/schemas/Dog"
components:
  schemas:
    Cat:
      type: object
      required:
        - whiskers
      properties:
        whiskers:
          type: integer
    Dog:
      type: object
      required:
        - bark
      properties:
        bark:
          type: boolean

Request from consumer to mock:

{"type": "Cat", "whiskers": 3}

The discriminator is declared, but neither subschema defines the type property, so the discriminator setup is invalid.

How this can be resolved

  • Add the discriminator property to each subschema and mark it required.
  • Ensure the discriminator mapping values align with the schema definitions.

R3003​

Missing discriminator​

The discriminator property defined in the specification is missing.

Why this is a problem

Without the discriminator property, a composed schema cannot determine which subschema should apply.

Example:

oneOf:
  - $ref: "#/components/schemas/Cat"
  - $ref: "#/components/schemas/Dog"
discriminator:
  propertyName: type
  mapping:
    Cat: "#/components/schemas/Cat"
    Dog: "#/components/schemas/Dog"
components:
  schemas:
    Cat:
      type: object
      required:
        - type
        - whiskers
      properties:
        type:
          type: string
        whiskers:
          type: integer
    Dog:
      type: object
      required:
        - type
        - bark
      properties:
        type:
          type: string
        bark:
          type: boolean

Request from consumer to mock:

{"whiskers": 3}

The payload lacks the discriminator property type, so validation reports a missing discriminator.

How this can be resolved

  • Include the discriminator property in the payload.
  • If the discriminator is not needed, remove it and adjust the composed schema.

R3004​

Property not in any schema options​

The property is not defined in any available schema options.

Why this is a problem

With anyOf, a property that does not exist in any option indicates the payload does not match the allowed shapes.

Example:

anyOf:
  - $ref: "#/components/schemas/OptionA"
  - $ref: "#/components/schemas/OptionB"
components:
  schemas:
    OptionA:
      type: object
      properties:
        a:
          type: string
    OptionB:
      type: object
      properties:
        b:
          type: number

Request payload being validated:

{"c": 10}

During validation of the request from consumer to mock, c is not present in any anyOf option, so the property not in any schema options violation is reported.

How this can be resolved

  • Send a payload that matches at least one anyOf option.
  • If c is valid, add it to one of the option schemas or add another option.

R3005​

Property matches no schema option​

The property does not satisfy any available schema options.

Why this is a problem

Even if a property exists in multiple options, it must still satisfy at least one option's constraints.

Example:

anyOf:
  - $ref: "#/components/schemas/StringOption"
  - $ref: "#/components/schemas/NumberOption"
components:
  schemas:
    StringOption:
      type: object
      properties:
        common:
          type: string
    NumberOption:
      type: object
      properties:
        common:
          type: number

Request from consumer to mock:

{"common": true}

The property exists in both options but does not match either type, so validation reports no matching schema option.

How this can be resolved

  • Provide a value that satisfies one of the schema options.
  • If boolean is valid, update the specification to allow it.

OAS0001​

Invalid min length​

Minimum length must be a positive integer.

Why this is a problem

Negative values are meaningless.

Example:

type: string
minLength: -1

How this can be resolved

  • Set minLength to a positive integer.

OAS0002​

Invalid max length​

Maximum length must be greater than or equal to minimum length.

Why this is a problem

Conflicting bounds cannot be satisfied by any value, so validation becomes impossible.

Example:

type: string
minLength: 10
maxLength: 5

How this can be resolved

  • Ensure maxLength is greater than or equal to minLength.

OAS0003​

Excessive length​

Length should not exceed recommended maximum of 4MB.

Why this is a problem

Very large bounds can lead to memory pressure and poor performance in tooling and tests.

Example:

type: string
maxLength: 2147483647

Just imagine if Specmatic were to generate a 2GB string in a contract test request and send it to your application, or generate a huge randomized value in a mock response!

How this can be resolved

  • Reduce maxLength to 4MB or lower. To ensure that a large string can be safely generated, Specmatic will proactively treat any length above 4MB as 4MB.

OAS0004​

Pattern length conflict​

Pattern must be able to generate values matching the minimum and maximum length.

Why this is a problem

If the pattern cannot produce any valid strings within the length bounds, the schema is unsatisfiable.

Example:

type: string
minLength: 1
maxLength: 1
pattern: "^[0-9]{2}$"

How this can be resolved

  • Update the pattern or length constraints so they are compatible.

OAS0005​

Invalid numeric bounds​

Maximum must be greater than or equal to minimum.

Why this is a problem

Conflicting numeric bounds cannot be satisfied by any value.

Example:

type: number
minimum: 10
maximum: 5

How this can be resolved

  • Ensure maximum is greater than or equal to minimum.

OAS0010​

Invalid parameter definition​

Parameters must define required properties such as name, schema, etc.

Why this is a problem

Incomplete parameter definitions prevent tools from understanding how to parse and validate requests.

Example:

parameters:
  - in: query
    required: true

How this can be resolved

  • Define required parameter properties (name, in, schema, and required where applicable).

OAS0011​

Missing path parameter​

All path template segments must be defined as parameters.

Why this is a problem

Unspecified path parameters make it unclear how to validate or bind the request.

Example:

paths:
  /orders/{id}:
    get:
      responses:
        "200":
          description: OK

How this can be resolved

  • Add parameter definitions for every path template segment.

OAS0012​

Required query object conflict​

A required form-exploded object query parameter must have at least one required schema property to make a concrete query parameter mandatory.

Why this is a problem

OpenAPI serializes style: form and explode: true object query parameters as individual query parameters. There is no wrapper query parameter for the object itself.

Example:

parameters:
  - in: query
    name: info
    required: true
    style: form
    explode: true
    schema:
      type: object
      properties:
        name:
          type: string
        description:
          type: string

The query object is marked as required, but neither name nor description is marked as required in the object schema. Since the object is represented by its properties, Specmatic has no concrete query parameter to require.

How this can be resolved

  • Add at least one property to the object's required list.
  • If none of the object properties must be present, set the query parameter required value to false or remove it.

OAS0013​

Query parameter type collision​

Multiple query parameter declarations serialize to the same query-string key, but they do not resolve to the same schema. This is reported as a warning.

Why this is a problem

When two query parameters produce the same wire key with different types or constraints, Specmatic cannot apply both definitions at runtime. Same-schema collisions are accepted, but different-schema collisions produce a warning. If parsing continues, Specmatic uses the last declared query parameter schema for that serialized key as authoritative for the rest of the run.

Example:

paths:
  /data:
    get:
      parameters:
        - in: query
          name: info
          style: form
          explode: true
          schema:
            type: object
            properties:
              age:
                type: integer
        - in: query
          name: age
          schema:
            type: string
      responses:
        "200":
          description: OK

In this example, the form-exploded info object contributes the wire key age through info.age, while the second parameter also declares age directly. Because info.age is an integer and age is a string, Specmatic warns that the query parameter wire key age has conflicting schemas and continues with the last declaration, age, as the authoritative schema for age.

How this can be resolved

  • Keep both declarations only if they resolve to the same schema for the same wire key.
  • Rename or restructure one of the parameters so they no longer serialize to the same query-string key.
  • If the wire key must stay the same, align the schemas so Specmatic does not have to choose between conflicting definitions.

OAS0014​

Invalid nested query parameter example​

Nested query parameter examples must use valid keys that match the parameter schema and the nested query syntax inferred by Specmatic.

Why this is a problem

Specmatic expands nested object query parameters from the example keys. Malformed keys, unknown properties, scalar fields followed by nested tokens, array indexes expressed as property names, or mixed nested property styles make the intended query shape ambiguous.

Example:

parameters:
  - in: query
    name: filter
    style: form
    explode: true
    schema:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
        method:
          type: object
          properties:
            status:
              type: string
        profile:
          type: object
          properties:
            name:
              type: string
    examples:
      invalid:
        value: "errors[0].code=E001&method[status]=failed&profile[[name=alice"

The example mixes errors[0].code with method[status], which uses conflicting nested property serialization styles in the same example. The profile[[name key is malformed and cannot be parsed as a valid nested query key.

How this can be resolved

  • Use one supported nested query key style consistently within the example.
  • Fix malformed keys and ensure every nested key maps to a property declared in the query parameter schema.
  • Rewrite invalid scalar or array paths so scalar properties are not followed by nested tokens, and arrays use numeric indexes where indexes are expected.

OAS0015​

Unsupported nested query parameter schema​

Nested query parameter schemas must be concrete enough for Specmatic to derive a safe nested query shape.

Why this is a problem

Specmatic cannot safely infer nested query keys from ambiguous or unsupported schema shapes. Composed schemas such as oneOf, anyOf, or allOf under nested query object properties are not supported for this feature. Array query schemas must also declare items.

Example:

parameters:
  - in: query
    name: filter
    style: form
    explode: true
    schema:
      type: object
      properties:
        criteria:
          oneOf:
            - type: object
              properties:
                status:
                  type: string
            - type: object
              properties:
                code:
                  type: string

Specmatic cannot determine a single nested query shape for criteria because it can match more than one composed schema branch.

How this can be resolved

  • Replace composed nested query schemas with a concrete object schema for query parameters.
  • Move ambiguous alternatives into separate query parameters when they represent different request shapes.
  • Add items to array query schemas so Specmatic can derive the nested array element shape.

For example:

parameters:
  - in: query
    name: filter
    style: form
    explode: true
    schema:
      type: object
      properties:
        criteria:
          type: object
          properties:
            status:
              type: string
            code:
              type: string

OAS0020​

Security property redefined​

Security scheme properties should not be redefined in parameters.

Why this is a problem

Redefining security details can introduce conflicting requirements and confuse users trying to understand validation errors.

Example:

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
paths:
  /orders:
    get:
      parameters:
        - name: X-API-Key
          in: header
          schema:
            type: string

How this can be resolved

  • Remove parameter redefinitions and rely on the security scheme.

OAS0021​

Security scheme missing​

Referenced security schemes must be defined and resolve-able.

Why this is a problem

If the security scheme in an API is not defined in the specification, the specification is incomplete. Specmatic will not be able to validate or enforce authentication requirements.

How this can be resolved

  • Define the referenced security scheme or update the reference.

OAS0030​

Media type overridden​

Media types should not be overridden by Content-Type parameters.

Why this is a problem

Conflicting media type definitions create ambiguity about the actual request or response body format.

In fact, the OpenAPI Specification disallows defining a Content-Type parameter alongside a requestBody or responses content type.

Example:

paths:
  /orders:
    post:
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object

How this can be resolved

  • Remove the conflicting Content-Type parameter.

OAS0031​

Invalid response status​

Response status must be a valid integer or literal default.

Why this is a problem

Non-standard status keys cannot be interpreted by tooling and break response matching.

Example:

responses:
  "2xx":
    description: OK

How this can be resolved

  • Use valid numeric status codes or default for responses.

OAS0032​

Undeclared request variant response requires external example​

405 and 415 responses describe requests outside the declared operation shape. Specmatic does not generate tests or inline mock data for them from the response definition alone, so the response may never be exercised.

Example:

paths:
  /orders:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "405":
          description: Method not allowed
        "415":
          description: Unsupported media type

How this can be resolved

  • Provide external examples for the 405 or 415 responses that you want Specmatic to test or mock.
  • Remove the undeclared request variant response if it is not intended to be exercised.

OAS0033​

Method Not Allowed response has no disallowed method​

405 response may never occur as all HTTP methods have been declared in the spec.

Why this is a problem

A 405 response represents a method that is not allowed for a path. If every HTTP method is already declared, there is no remaining method for Specmatic to use when creating a Method Not Allowed variant.

Example:

paths:
  /orders:
    get:
      responses:
        "405":
          description: Method not allowed
    post:
      responses:
        "200":
          description: OK
    put:
      responses:
        "200":
          description: OK
    delete:
      responses:
        "200":
          description: OK
    patch:
      responses:
        "200":
          description: OK
    options:
      responses:
        "200":
          description: OK
    head:
      responses:
        "200":
          description: OK
    trace:
      responses:
        "200":
          description: OK

How this can be resolved

  • Remove the 405 response when all HTTP methods are valid for the path.
  • If a method should be disallowed, do not declare that method as an operation for the path, and provide an external example for the intended 405 variant.

OAS0041​

Unresolved reference​

References must resolve to a valid reusable component.

Why this is a problem

Broken references make the schema incomplete and unusable for validation.

Example:

schema:
  $ref: "#/components/schemas/MissingType"

How this can be resolved

  • Fix the $ref to point to an existing component, or add the missing component.

OAS0042​

Invalid $ref usage​

A $ref should not define sibling properties as per OAS 3.0 standards.

Why this is a problem

Sibling properties are ignored in OAS 3.0, leading to unexpected validation behavior.

Example:

schema:
  $ref: "#/components/schemas/Order"
  description: Order response

How this can be resolved

  • Move sibling properties into the referenced schema or remove them.

OAS0044​

Invalid additionalProperties usage​

additionalProperties should only be used within object schemas.

Why this is a problem

Using additionalProperties with non-object schemas is meaningless.

Example:

type: string
additionalProperties: true

How this can be resolved

  • Use additionalProperties only on object schemas, or move it into the appropriate object definition.

OAS0043​

Unclear schema​

The intent of this schema is unclear or may not be supported. Consider reaching out if this is an issue.

Why this is a problem

Ambiguous or unsupported schema constructs can cause inconsistent behavior across tools.

Example:

schema:
  allOf: []

How this can be resolved

Please reach out to the Specmatic team for help.

OAS9999​

Unsupported feature​

This feature is currently not yet supported, consider reaching out if you would like us to prioritise the support.

T00001​

Excluded by Filter​

What happened

This operation was skipped because it did not match the specified filter

Why you might see this

The filter expression specified in the Specmatic Config does not allow this operation to be executed.

What you can do

Please revise the filter to ensure it allows the operation by either broadening or narrowing the expression.

T00002​

Examples Required​

What happened

This operation was skipped because it requires examples, but none were provided.

Why you might see this

  • By default, only operations that return a 2xx status are generated automatically.
  • Operations returning a status other than 2xx require explicit examples to be provided.
  • Operations with a 400 status may be auto-generated if Schema Resiliency is activated.

What you can do

  • To execute this operation, please provide at least one example.
  • For 400 operations, consider activating Schema Resiliency if applicable

T00003​

Examples Required in Strict Mode​

What happened

This operation was skipped because strict mode is enabled and no valid example was found.

Why you might see this

When strict mode is enabled, only operations with valid examples will be executed, irrespective of schema resiliency.

What you can do

Provide at least one valid example for this operation, or disable strict mode.

T00004​

Generative Disabled​

What happened

This operation was skipped because it requires schema resiliency to be enabled.

Why you might see this

This issue occurs exclusively for bad request responses that lack examples.

What you can do

T00005​

Maximum Test Count Exceeded​

What happened

This operation was skipped because the execution reached the maximum permitted test count.

Why you might see this

Studio SaaS restricts the number of tests that can be executed in a single test run.

What you can do

Studio SaaS is designed as a playground for exploration. If you'd like to run unrestricted test suites or experience the full power of Specmatic, please reach out to the Specmatic team.

T00006​

Accept Mismatch​

What happened

The request Accept header does not match the response content type defined for this operation.

Why you might see this

  • The Accept header informs the server about the media types that the client can handle.
  • If the operation is specified to return a particular content type, but the request specifies an incompatible Accept header, the interaction becomes invalid.

What you can do

  • Modify the request Accept header to include the media type specified for the operation's response, such as application/json when the operation returns JSON.
  • If your API supports various response media types, ensure that the content section of the OpenAPI responses is accurately defined and that the example/request headers are properly aligned.

T10001​

Executed Using Example​

What happened

This operation was executed utilizing an available example (either inline or external).

Why you might see this

Specmatic identified a suitable example and executed the operation accordingly.

What you can do

  • Retain the example if this execution was intended.
  • Remove the example if this execution was not intended.

T10002​

Executed Using Generation​

What happened

This operation was executed using generated payloads due to the absence of a usable example.

Why you might see this

No valid example was found for this operation.

What you can do

  • Provide an example for the operation.
  • Enable strict mode to ensure that only operations with at least one valid example are executed.
  • If an example already exists, verify that it is valid and has been successfully loaded by Specmatic.

T10003​

Executed Using Positive Generation​

What happened

This operation was executed using positive payload generation.

Why you might see this

  • This can occur when positive generation is enabled in Schema Resiliency.
  • This can occur even when a valid example is present, as Specmatic will generate payloads with positive mutations based on the provided example.

What you can do

If you prefer to avoid this behavior, disable positive generation in the Specmatic Configuration.

T10004​

Executed Using Negative Generation​

What happened

This operation was executed using negative payload generation.

Why you might see this

  • This can occur when negative generation is enabled in Schema Resiliency.
  • This can occur even when a valid example is present, as Specmatic will generate payloads with negative mutations based on the provided example.

What you can do

If you prefer to avoid this behavior, disable negative generation in the Specmatic Configuration.