Skip to content

OpenAPI 3.0 Coverage

This page describes which parts of the OpenAPI 3.0 specification Contracteer supports, where it deviates, and which features are not applicable to contract testing.

Contracteer supports OpenAPI 3.0.x.

Limitations

Contracteer does not reject a specification because it contains unsupported features. Unsupported content types cause the operation to be skipped with a warning. Unsupported schema keywords are ignored. Your specification still loads.

Feature Impact
application/xml Operations with XML-only content types are skipped with a warning.
not (schema negation) The keyword is ignored. Values are validated and generated without it.
allowEmptyValue (parameters) The keyword is ignored. Deprecated by the OAS 3.0 specification itself.
externalValue (Example Objects) Only inline value is read. External references are not fetched.
Pattern generation (regex) Some regex features (lookaheads, lookbehinds) do not generate correctly.
Unknown integer/number formats Rejected. Only int32, int64, float, double are supported.

If Contracteer skips an operation or ignores a keyword, it logs a warning when loading the specification.

Deviations from the Specification

The OpenAPI 3.0 specification is sometimes ambiguous or impractical for contract testing. In these cases, Contracteer makes explicit choices.

String constraint precedence

OpenAPI treats format, pattern, minLength, and maxLength as independent constraints applied simultaneously. Contracteer applies them in a strict precedence order:

  1. format (email, uuid, date, date-time, byte, binary) -- the format defines the type entirely. pattern is always ignored with a warning. minLength/maxLength are supported by email, base64, and binary formats, but ignored by uuid, date, and date-time.
  2. pattern -- the regex pattern defines the constraint. minLength and maxLength are ignored with a warning.
  3. minLength / maxLength -- used only when neither format nor pattern is set.

Generating a random value that satisfies both a regex pattern and a length range is not reliably possible. Contracteer uses the same constraint for both validation and generation to ensure consistency. What Contracteer validates is what it can generate.

enum is always validated against the active constraint when loading the specification. If all enum values satisfy the active constraint, the specification is accepted. If any enum value violates it, the specification is rejected.

Random value generation for patterns uses the RgxGen library. RgxGen supports most common regex features, but lookaheads and lookbehinds do not generate correctly. If Contracteer generates invalid values for your pattern, use enum values instead, or provide explicit examples in your specification.

Multipart default content types

The OAS 3.0 specification defaults arrays of primitives to text/plain in multipart parts. Contracteer uses application/json for all arrays. The specification does not define how to serialize an array as plain text in a multipart part.

Property type Contracteer default
Primitive text/plain
Array of primitives application/json
Array of format: binary or format: base64 items application/octet-stream
Object or composite application/json
format: binary or format: base64 application/octet-stream

Use the encoding object to override the default content type for specific properties.

Not Applicable to Contract Testing

These features are defined in the OAS 3.0 specification but do not affect the structural contract between client and server. Contracteer does not process them.

Feature Reason
servers / server variables Connection configuration. The verifier accepts the server URL as external configuration.
security / securitySchemes Authentication is runtime configuration, not contract structure.
tags, summary, description Documentation metadata.
operationId Client code generation hint.
externalDocs Documentation link.
deprecated Informational flag. A deprecated operation has the same structural contract.
callbacks Webhook definitions -- a separate concern from request/response contract testing.
links Hypermedia navigation hints between operations.
default (property values) The verifier always sends values. The mock server validates against the schema, not against assumed defaults.
example on Schema Object Contracteer uses the examples keyword on Parameter and Media Type Objects for scenario creation. Schema-level example is not read.
xml (Schema Object) XML serialization hints. Only relevant if XML content type were supported.

Detailed Coverage

Data types

Type Notes
string With minLength, maxLength, pattern, enum, nullable
integer With minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, enum, nullable
number With minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, enum, nullable
boolean With enum, nullable
array With minItems, maxItems, uniqueItems. Including array parameters with style/explode encoding
object With minProperties, maxProperties, additionalProperties, readOnly, writeOnly. Including object parameters with style/explode encoding

String formats

Format Status
date Supported (ISO 8601 YYYY-MM-DD)
date-time Supported (ISO 8601 with offset)
email Supported
uuid Supported
byte (base64) Supported
binary Supported
password Supported (treated as plain string)
Custom formats Ignored

Integer and number formats

Format Status
int32 Supported. Applies 32-bit signed range; rejects explicit min/max outside range
int64 Supported. Applies 64-bit signed range; rejects explicit min/max outside range
float Supported. Applies 32-bit float range; rejects explicit min/max outside range
double Supported. Applies 64-bit double range; rejects explicit min/max outside range

Schema keywords

Keyword Notes
nullable All data types
enum All data types
minimum / maximum Integer and number types
exclusiveMinimum / exclusiveMaximum Integer and number types (OAS 3.0 boolean semantics)
minLength / maxLength String, email, base64, binary types
pattern Plain strings only. See string constraint precedence
multipleOf Integer and number types
minItems / maxItems Array types
uniqueItems Array types
minProperties / maxProperties Object types
required (properties) Object types
additionalProperties Both boolean and typed schema forms
readOnly / writeOnly readOnly properties excluded from request schemas, writeOnly from response schemas
discriminator With propertyName and mapping on allOf, oneOf, anyOf

Schema composition

Feature Notes
allOf Requires all sub-schemas to be structured types (object or composite)
oneOf Validates that exactly one sub-schema matches
anyOf Validates that at least one sub-schema matches
discriminator Supported on allOf, oneOf, anyOf with propertyName and mapping

Parameters

Feature Notes
in: path Primitive, array, and object types. Styles: simple, label, matrix
in: query Primitive, array, and object types. Styles: form, spaceDelimited, pipeDelimited, deepObject
in: header Primitive, array, and object types. Style: simple
in: cookie Primitive, array, and object types. Style: form
style / explode All OAS 3.0 style/explode combinations with correct defaults per location
content (instead of schema) Parameter value serialized via content type (e.g., JSON-encoded query parameter)
allowReserved Query parameters and application/x-www-form-urlencoded encoding properties

Request and response bodies

Feature Notes
application/json Supported
Plain text content types Supported
multipart/* (form-data, mixed, etc.) Per-part content type via the encoding object
application/x-www-form-urlencoded Per-property encoding via the encoding object
Multiple content types Produces one verification per content type combination
required (request body) Supported
Content negotiation (Accept header) RFC 7231 support with quality factors and wildcard subtypes

Examples and scenarios

Feature Notes
examples map (parameter / media type level) Core mechanism for scenario creation
Single example (parameter / media type level) Supported
Status-code-prefixed example keys Supported (404_NOT_FOUND, 400_INVALID_INPUT)

See Creating Scenarios for how examples drive scenario creation.

References ($ref)

Feature Notes
$ref to #/components/schemas Supported
$ref to #/components/parameters Supported
$ref to #/components/requestBodies Supported
$ref to #/components/responses Supported
$ref to #/components/headers Supported
$ref to #/components/examples Supported
Recursive / chained $ref Supported (with depth limits)
External $ref (other files) Resolved by the OpenAPI parser before Contracteer processes the model

Responses

Feature Notes
Exact status codes (200, 404, etc.) Supported
Status code ranges (2XX, 4XX, 5XX) Used as fallback when exact status code is not defined
default response Used as fallback when neither an exact status code nor a status code range is defined
Response headers Supported
Response body Supported

Next Steps