Skip to main content



This rule belongs to the openapi-v3-syntax-validation ruleset and states that:

$ref values must be RFC3986-compliant percent-encoded URIs.

Maximum SeverityError
MessageProvided $ref path is invalid.
Rule SystemSyntax
Broad CategoryReferences
Products ImpactedAPI Transformer, Code Generation, Developer Experience Portal
Tagsopenapi3 openapi syntax validation $ref uri reference

Suggested Fixes

  • Ensure that the value of $ref is a valid URI.
  • Ensure that any literal forward slashes are replaced by ~1 each.
  • Ensure that the URI value does not contain any forbidden characters.
  • Ensure that the $ref value is not empty or null.
  • Ensure that the reference path set in the $ref property is a valid path to the component you intend to reference.
  • If the reference path to the component is unknown remove the Reference Object and define the component directly.

For More Information