OpenAPI 3.1.x parser types not aligned with spec

What happens?

Hi,

I've noticed that types in https://github.com/scalar/scalar/blob/main/packages/openapi-types/src/openapi-types.ts are not aligned with OpenAPI 3.1.x spec.

We can take a specific section as an example (other parts are affected as well): https://github.com/scalar/scalar/blob/2d7f99530a86f152ef8d21456c15369c8808c6b0/packages/openapi-types/src/openapi-types.ts#L190-L214

In OpenAPI 3.1.0, Schema Object by default represents a superset of JSON Schema 2020-12. It also comes with following paragraph from OpenAPI 3.1.x:

Unless stated otherwise, the keyword definitions follow those of JSON Schema and do not add any additional semantics; this includes keywords such as $schema, $id, $ref, and $dynamicRef being URIs rather than URLs.

This tells us that $ref field of Schema Object has the same semantics as in pure JSON Schema 2020-12. This has direct implication in OpenAPI 3.1.x - you don't see Schema Object | Reference Object type union no more.

Schema Object in OpenAPI 3.1.x is referencable by itself, using $ref, $dynamicRef or $anchor, $dynamicAnchor mechanisms. This is the most complex change in OpenAPI 3.1.x as those new reference keywords have resolutions rules completely different to the Reference Object that was used to reference Schema Objects in OpenAPI 3.0.x.

I've just issued a PR (https://github.com/OAI/OpenAPI-Specification/pull/4906) for OpenAPI 3.1.x, which removes the last remnant of this ambiguity from the spec. It has already been approved.

What did you expect to happen?

Schema Object shouldn't be used as union type of Schema Object | Reference Object

OpenAPI Document

No response

hey @char0n our latest types can be found here:

https://github.com/scalar/scalar/blob/main/packages/workspace-store/src/schemas/v3.1/strict/schema.ts

I believe they should be compliant right?

Hi,

It looks like the same issue, but differently written - Schema Objects are referenced via a reference() which uses ReferenceObjectSchema - if I understand this correctly it's using Reference Object to represent reference for Schema Object:

https://github.com/scalar/scalar/blob/66b18fc4477682b07c3ce5a09888ab3db5359412/packages/workspace-store/src/schemas/v3.1/strict/reference.ts#L17-L32.

So we're in the same situation as before.

This is a great summary:

Schema Object | Reference Object would create ambiguity as both objects can only have $ref field. When Schema Object is a type for a field, it shouldn't use union with Reference Object as the Schema Object is already reference-able by itself.

Source: https://github.com/OAI/OpenAPI-Specification/pull/4906 (as mentioned above)

So, is that bug responsible for my Schema examples not being picked up and having their examples replaced when the open api version is set to 3.1.X instead of 3.0.X?

Given this registered Schema:

components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string
        traceId:
          type: string
      examples:
        - type: https://tools.ietf.org/html/rfc7231#section-6.5.1
          title: An error occurred while processing your request.
          status: 500
          instance: /api/endpoint
          traceId: 00-0123456789abcdef0123456789abcdef-0123456789abcdef-00

And an endpoint with the following responses:

responses:
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
              examples:
                default:
                  value:
                    type: https://tools.ietf.org/html/rfc9110#section-15.5.5
                    title: Not Found
                    status: 404
                    instance: GET players/{playerId}
                    traceId: 00-0123456789abcdef0123456789abcdef-0123456789abcdef-00

The Schema shown is not the same depending on the OpenAPI version (3.0.X being the good behavior).

3.0.X:

3.1.X:

@Kuurama this seems unrelated it might be fixed already, this looks good to me: https://sandbox.scalar.com/e/w6KyU

@Kuurama this seems unrelated it might be fixed already, this looks good to me: https://sandbox.scalar.com/e/w6KyU

Came back here because apparently, another way of referencing example doesn't work on 3.1.X:

https://sandbox.scalar.com/e/tYGCn

While it works on 3.0.X:

https://sandbox.scalar.com/e/0oZqj