oasExampleSchema

oasExampleSchema will scan an OpenAPI specification looking for violations around examples.

The function is used by the oas3-valid-schema-example rule.

Function Options

This function is configured by the following functionOptions:

Format and content assertions

By default, oasExampleSchema does not assert format, contentEncoding, or contentMediaType constraints. Enable the corresponding options when examples must satisfy those annotations:

rules:
  oas3-valid-schema-example:
    description: Examples must be valid against their schemas
    severity: error
    given: "$"
    then:
      function: oasExampleSchema
      functionOptions:
        formatAssertions: true
        contentAssertions: true

The options are independent and remain disabled unless explicitly set to true.

Strict Mode

By default, this function only validates that examples conform to JSON Schema validation rules. This means extra properties in examples are allowed (unless additionalProperties: false is set on the schema).

When strictMode: true is enabled, the function will also detect undeclared properties in examples - properties that exist in the example but are not declared in the schema. This helps catch:

• Typos in property names (e.g., nmae instead of name)
• Outdated examples with properties that were removed from the schema
• Copy-paste errors where extra properties were accidentally included

Example ruleset with strict mode

rules:
  oas3-valid-schema-example:
    description: Examples must be valid against their schemas
    severity: error
    given: "$"
    then:
      function: oasExampleSchema
      functionOptions:
        strictMode: true

View Function Source