"Examples" incorrectly rendered for OpenAPI 3.x spec

[maolimu]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

3.27.0

Plugin version

4.13.0

Node.js version

16.13.0

Operating system

macOS

Operating system version (i.e. 20.04, 11.3, 10)

12.2 (21D49)

Description

When adding an examples array to JSON Schema, when translating it to OpenAPI 3.x spec, the property seems to be misplaced: it is added under schemas but it should be next to it.

This causes a validation error in Swagger Editor, indicating the examples is not a valid property under schemas and it makes Swagger-UI not render the examples array.

Steps to Reproduce

1. the schema is created with TypeBox

export const PrototypesSchema = Type.Object(
    {
        foo: Type.String(),
        bar: Nullable(Type.String()),
    },
    {
        examples: [
            {
                foo: 'example 1',
                bar: null,
            },
            {
                foo: 'example 2',
                bar: 'some bar value',
            },
        ],
    }
);

2. the generated JSON-Schema is correct:

{
   "examples": [
      {
         "foo": "example 1",
         "bar": null
      },
      {
         "foo": "example 2",
         "bar": "some bar value"
      }
   ],
   "type": "object",
   "properties": {
      "foo": {
         "type": "string"
      },
      "bar": {
         "type": "string",
         "nullable": true
      }
   },
   "required": [
      "foo",
      "bar"
   ]
}

3. The generated OpenAPI spec shows a validation error in Swagger Editor

Structural error at paths./experiments.put.requestBody.content.application/json.schema
should NOT have additional properties
additionalProperty: examples
Jump to line 29 

Indeed, the examples object is placed below schemas, but it should be next to it

paths:
  /experiments:
    put:
      summary: experiments endpoint
      tags:
        - Misc
      requestBody:
        content:
          application/json:
            schema:
              examples:
                example1:
                  value:
                    foo: example 1
                    bar: null
                example2:
                  value:
                    foo: example 2
                    bar: some bar value
              type: object
              properties:
                foo:
                  type: string
                bar:
                  type: string
                  nullable: true
              required:
                - foo
                - bar
                - ```

### Expected Behavior

Place **examples** one level up, next to **schemas**, where it is correct

[Eomm]

Would you like to send a Pull Request to address this issue? Remember to add unit tests.

[hamochigames]

Looking forward to have this fixed.

[mikicho]

Is examples an official keyword in json-schema?
If yes, how should we treat nested examples like:

{
  examples: [ 1 ],
  type: 'object',
  properties: {
    a: {
      examples: [ 'a', 'b' ],
      type: 'string'
    },
    b: {
      examples: [ 'c', 'd' ],
      type: 'object',
      properties: { c: { type: 'string' } },
      required: [ 'c' ]
    }
  },
  required: [ 'a', 'b' ]
}

I'm not sure about the correct behavior we need to implement here and need some guidance in order to implement it

[avdwio]

Hey @mikicho

examples is a keyword defined by JSON schema as of draft 6; you can read about it here.

examples is also a keyword in OpenAPI 3.x, which you can read about here. Note:

Note that schemas and properties support single example but not multiple examples.

So, perhaps frustratingly, nested examples is not permitted. It looks like in general, fastify-swagger doesn't care if the user inserts incorrect keys into their schema, so I think nested examples should just be ignored.

Onto the fix for the initial problem, is it enough to simply move the examples property from the schema object to the next level up? This would mean that this:

fastify.get('/description', {
  schema: {
    response: {
      200: {
        type: 'string',
        examples: ['one', 'two'],
      }
    }
  }
}, () => {})

gives something like

"get": {
  "responses": {
    "200": {
      "description": "Default Response",
      "content": {
        "application/json": {
          "schema": {
            "type": "string",
            "examples": {
              "one": {
                "value": "one"
              },
              "two": {
                "value": "two"
              }
            }
          }
        }
      }
    }
  }
},

It gets a bit weird when using $refs and something like TypeBox; I'd be doing something like:

export const PrototypesSchema = Type.Object(
    {
        foo: Type.String(),
        bar: Nullable(Type.String()),
    }
);

to generate the schema, then

fastify.addSchema(PrototypesSchema)
// ...
fastify.get('/description', {
  schema: {
    200: {
        ...Type.Ref(PrototypesSchema),
        examples: [
            {
                foo: 'example 1',
                bar: null,
            },
            {
                foo: 'example 2',
                bar: 'some bar value',
            },
        ],
      },
  }
}, () => {})

Would it be more correct if fastify-swagger used a x-examples keyword instead of examples, since it is manipulating the schema after user implementation (much like x-response-description)

---

As a side note, currently examples takes an array (enforced by JSON Schema) and is outputted as an object. The property names are created by fastify-swagger; is there any way to define these? Perhaps x-examples (if implemented) could take a literal object of the examples

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.