oas3-valid-schema-example

Examples are really important. When defining an OpenAPI specification, it’s critical that every operation request and response have examples defined for them. The same applies to definitions defined as references.

Examples help consumers of your API understand what real data should actually look like when sending requests, or listening for responses.

Good examples are particularly valuable when data is complex, deep, nested or contains special formatting.

Why did this violation appear?

The specification has examples that do not match the schema defined.

What is this rule checking for?

The rule looks through the spec at the following elements, and checks that examples have been clearly defined for each.

• All Schemas
• All Parameters
• All Headers
• All Media Types

Validating the schema.

If the operation or component implementing an example is an object (not a primitive), then vacuum will validate the example matches the schema defined.

Function Options

This rule supports the following functionOptions:

Strict Mode

By default, this rule 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 rule 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

Strict mode error example

Given this schema and example:

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
      example:
        name: "Buddy"
        extra: "undeclared"  # This property is not in the schema!

With strictMode: true, vacuum will report:

example contains undeclared property 'extra' at $.components.schemas['Pet'] (declared properties: [name])

Without strict mode, this example would pass validation because JSON Schema allows additional properties by default.

What does a good example look like?

In OpenAPI 3.0, we should include examples for each RequestBody. We should also include examples for Responses, Components or Parameters

A good example, of a RequestBody and Response example looks like this:

paths:
  /burgers:
    post:
      operationId: createBurger
      tags:
        - "Burgers"
      summary:  Create a new burger
      description: A new burger for our menu, yummy yum yum.
      requestBody:
        description: Give us the new burger!
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Burger'
            examples:
              pbjBurger:
                summary: A horrible, nutty, sticky mess.
                value:
                  name: Peanut And Jelly
                  numPatties: 3
              cakeBurger:
                summary: A sickly, sweet, atrocity
                value:
                  name: Chocolate Cake Burger
                  numPatties: 5
      responses:
        "200":
          description: A tasty burger for you to eat.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Burger'
              examples:
                quarterPounder:
                  summary: A yummy tasty two patty burger.
                  value:
                    name: Quarter Pounder with Cheese
                    numPatties: 1
                filetOFish:
                  summary: A Cripsy Fish Sammich filled with ocean goodness.
                  value:
                    name: Filet-O-Fish
                    numPatties: 1

How do I fix this violation?

Examples are critical for consumers to be able to understand schemas and models defined by the spec.

Without examples, developers can’t understand the type of data the API will return in real life. Examples are turned into mocks and can provide a rich testing capability for APIs. Add detailed examples everywhere!

Add examples, Make sure they are valid!