Diff rules

The diff command uses diff rules to find the changes that can break a client. Each rule finds one type of change, for example a removed operation. When a rule finds a change, the rule shows a message, and the change gets the impact that you set for the rule.

Experimental

Diff rules are an experimental feature. Their names, messages, and configuration can change in future releases.

`diff-recommended` ruleset

The diff-recommended ruleset turns on all diff rules with the major impact. The diff command uses this ruleset if you do not have a redocly.yaml file.

If you have a redocly.yaml file, only the rules from that file run. If the file turns on no diff rule, every change is minor or patch, and the command shows a warning. To use the ruleset, add it to extends:

extends:
  - recommended
  - diff-recommended

Configure diff rules

Set the impact of a rule in the diff section of redocly.yaml. The impact is major, minor, patch, or off:

extends:
  - diff-recommended
diff:
  enum-values-added: minor
  schema-constraint-changed: off

To turn off rules for one run, use the --skip-rule option:

redocly diff v1.yaml v2.yaml --skip-rule=enum-values-added

Requests and responses

Many rules check the direction of the data, because a change can break one direction only. For example, a new enum value is safe in a request, but it can break a client that reads a response.

OpenAPI: parameters and request bodies are requests, and responses are responses. In callbacks and webhooks, the API sends the request, so the directions are opposite.
AsyncAPI 3: the messages of an operation with action: receive are requests, and the messages of an operation with action: send are responses. A reply has the opposite direction.
A schema with readOnly: true is response data, and a schema with writeOnly: true is request data.
A component gets its directions from the places that reference it. If a request and a response reference the same schema, the rules check a change to that schema for both. For example, a new enum value in the schema is a major change, because it can break a client that reads the response.
If no request or response references a component, the component has no direction. The rules that check the direction do not report changes to it.

Rules

The rules apply to OpenAPI 3.x and AsyncAPI 3, except the rules that name one of them.

Paths, operations, and servers

Rule	Reports
`path-removed`	A removed or renamed path, or a removed webhook, callback, or callback URL. OpenAPI only.
`operation-removed`	A removed operation.
`operation-id-changed`	A changed or removed `operationId`. Generated clients use it as a method name. OpenAPI only.
`operation-action-changed`	A changed `action` of an operation. AsyncAPI only.
`server-removed`	A removed server, or a changed `url`, `host`, `pathname`, or `protocol` of a server.

Channels and messages

These rules apply to AsyncAPI only.

Rule	Reports
`channel-removed`	A removed channel.
`channel-address-changed`	A changed `address` of a channel.
`message-removed`	A removed message.
`message-content-type-changed`	A changed `contentType` of a message.

Parameters, request bodies, and responses

These rules apply to OpenAPI only.

Rule	Reports
`parameter-removed`	A removed or renamed parameter, or a changed `in` of a parameter.
`parameter-became-required`	A new required parameter, or a parameter that became required.
`parameter-serialization-changed`	A changed `style`, `explode`, `allowReserved`, or `allowEmptyValue` of a parameter.
`request-body-removed`	A removed request body.
`request-body-became-required`	A request body that became required.
`response-removed`	A removed response, or a changed status code of a response.
`response-header-removed`	A removed or renamed response header.
`media-type-removed`	A removed or renamed media type.

Schemas

Rule	Reports
`property-removed`	A removed or renamed property in a response, or in a request whose schema rejects unlisted properties (`additionalProperties: false` or `unevaluatedProperties: false`).
`required-properties-added`	Properties that became required in a request.
`required-properties-removed`	Properties that are no longer required in a response.
`enum-values-removed`	Removed `enum` values, or a new `enum`, in a request.
`enum-values-added`	New `enum` values, or a removed `enum`, in a response.
`schema-type-changed`	A changed `type` or `nullable` that accepts fewer types in a request, or more types in a response.
`schema-constraint-changed`	A changed constraint that accepts fewer values in a request, or more values in a response.
`schema-combinator-changed`	An added or removed subschema of `allOf`, `anyOf`, or `oneOf`, or an added or removed list of them, that accepts fewer values in a request, or more values in a response. OpenAPI only.

schema-constraint-changed checks these keywords:

Limits: minimum, maximum, exclusiveMinimum, exclusiveMaximum, minLength, maxLength, minItems, maxItems, minProperties, maxProperties.
Values: multipleOf, pattern, format, const, contentEncoding, contentMediaType. The rule cannot compare two values of these keywords, so it reports a changed value in both directions.
Flags: uniqueItems: true, and false for additionalProperties, items, unevaluatedItems, or unevaluatedProperties.
Subschemas: not, then, else, contains, propertyNames, items, prefixItems, additionalProperties, unevaluatedItems, unevaluatedProperties, dependentSchemas, dependentRequired.

Security