[OpenAPI] user-defined scalar type with nullable

[akishichinibu]

https://typespec.io/playground?c=c2NhbGFyIE15U3RyIGV4dGVuZHMgc3RyaW5nOwoKbW9kZWwgQSB7CiAgeDrHJnwgbnVsbAp9Cg%3D%3D&e=%40typespec%2Fopenapi3&options=%7B%7D

Consider the following TypeSpec definition:

scalar MyStr extends string;

model A {
  x: MyStr | null;
}

openapi: 3.0.0
info:
  title: (title)
  version: 0.0.0
tags: []
paths: {}
components:
  schemas:
    A:
      type: object
      required:
        - x
      properties:
        x:
          oneOf:
            - $ref: '#/components/schemas/MyStr'
          nullable: true
    MyStr:
      type: string

This generates the following OpenAPI specification, which violates the Redoc rule spec.

The `type` field must be defined when the `nullable` field is used.

In this case, the error occurs because the nullable field is used without defining the type explicitly within the oneOf clause, which Redoc requires for proper validation.

How can I fix this?

[timotheeguerin]

Does the tool also complain if it was of this form with allOf instead of oneOf

openapi: 3.0.0
info:
  title: (title)
  version: 0.0.0
tags: []
paths: {}
components:
  schemas:
    A:
      type: object
      required:
        - x
      properties:
        x:
          oneOf:
            - $ref: '#/components/schemas/MyStr'
          nullable: true
    MyStr:
      type: string

Just doing some reading on the spec, it does indeed say that nullable is only applicable when type is specified but this is a but problematic for openapi3 and most reference I found recommend to use the approach above

[akishichinibu]

Does the tool also complain if it was of this form with allOf instead of oneOf

Yes. I ran a test in our project code, and Redocly still reports the missing type field issue.

The `type` field must be defined when the `nullable` field is used.

13 |   x-order: 4
14 | ***:
15 |   nullable: true
16 |   allOf:
17 |     - $ref: '#/components/schemas/***'

I think the problem is about how to define a nullable custom scalar type in TypeSpec. TypeSpec uses object references to scalar types, but in fact the properties is a string type so type: "string" should be appended here. The schema like this can pass the linter.

 properties:
        x:
          type: string
          oneOf:
            - $ref: '#/components/schemas/MyStr'
          nullable: true

As a workaround, I'm trying to find a way to 'inline' the custom scalar type schema when it's used with nullable. After checking the documentation, I found a JavaScript API called shouldInline, which mentions:

Template instantiations are inlined unless they have a friendly name.

So, I added a new generic scalar type asY, which extends the original custom scalar type with an unused generic parameter. This forces TypeSpec to instantiate the template and inline the scalar type. However, I'm not sure if this is the correct approach. Could you provide some guidance?

scalar MyStr extends string;

scalar asY<T> extends MyStr;

model A {
  x: MyStr | null;
  y: asY<void> | null;
}

https://typespec.io/playground?c=c2NhbGFyIE15U3RyIGV4dGVuZHMgc3RyaW5nOwoKxx5hc1k8VD7JH8UtOwoKbW9kZWwgQSB7CiAgeDrHRHwgbnVsbDsKICB5OsU5dm9pZD7JF30K&e=%40typespec%2Fopenapi3&options=%7B%7D

[timotheeguerin]

yeah this is definitely a bit hacky. Can you file an issue about it?

I am just worried about those cases:

model Bar {
  a: MyEnum | Foo | null;
}

what would be the openapi3, the type of a can be object or string so you'd have add lots of wrapping

a:
  anyOf:
    - type: string
      nullable: true
      allOf:
         $ref: '#/components/schemas/MyEnum'
    - type: object    
       nullable: true
      allOf:
         $ref: '#/components/schemas/Foo'