Skip to main content

dollar-schema-only-for-root-schema-of-external-schema-resource

Overview​

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

If a schema definition is placed in an external/bare schema resource document (i.e. not an OpenAPI document), the $schema property must only be used in the root schema of that document as it applies to the lexical scope of the entire schema resource. It must not appear in non-resource root schema objects.

PropertyValue
EnabledYes
Maximum SeverityError
Message$schema is used in a non-root schema.
CodeOPENAPI3STANDARDS_V340
TypeValidation
Rule SystemSemantic
Broad CategorySchemas
Products ImpactedAPI Transformer, Code Generation, Developer Experience Portal
Tagsopenapi3 openapi standards semantic validation root schema json schema $schema schema

Suggested Fixes​

  • The top level schema object present directly in the external resource document is called the root schema.
  • Remove $schema from all of the inline schema definitions (i.e. schemas defined at any level within the root schema) and declare it once in the root schema only.
  • If a Schema Object is referenced from an external non-OAS resource document, the $schema rules of JSON schema Draft 2020-12 apply to it.

For More Information​