References to arbitrary data

[techbech]

So because of the missing ability in the OpenAPI standard to mark a property to be required independently of it being read-only or write-only, I'm making references to properties directly in cases we need a property that has been marked as required to be optional.

A quick example could be that you have a product with a name. The name is always required in responses. You might want it to be optional in a patch operation because only the given properties should be patched.

So my work-around was to add every writable property as the request body and then don't make them required. Just like so

requestBody:
  content:
    application/json:
      schema:
        type: object
        properties:
          name:
            $ref: '#/components/schemas/Product/properties/name'

This is working with all the other tools we're using, but after the additionalProperties default has been set to false, then the generated schema fails, as it should because of the missing properties object around the properties. This in general might be a problem with the structure of the generated schema types at the moment, because it may not be 1:1 with the provided API specification. I'm not quite sure if this problem might occur in other places as well.

I've made a small hack to the utility function transformRef but might become a unmaintainable solution moving forward. See it here https://github.com/venue-pos/openapi-typescript/commit/ad6be15bbaeddf93171dbda34683e3d47ad308cc

What is a better general solution that could actually be implemented?

[drwpow]

I think you’re asking something different of #604, but I also see some overlap there. In your example about required-ness being conditional of response vs PATCH (request), that would be readOnly / writeOnly, no? Or are you saying you need even more control than that?

[techbech]

In your example about required-ness being conditional of response vs PATCH (request), that would be readOnly / writeOnly, no?

Aah, my explanation is pretty bad. Forget about the read-only and write-only, that was the wrong way to explain what I actually want. I want to be able to set properties to required based on if one is reading the property or writing the property.

Or are you saying you need even more control than that?

Yes. In a response I want the type product.name to be required, as in it can not be undefined. But when sending a request using the same component as the body I don't want it to be required.

read-only and write-only is good for let's say product.id, as the ID may never change and may be generated by the API, so one would set it as required and read-only. But in this case, I want to be able to change the name of the product by using a patch operation, but I don't want it to be required in the request body, as I only want the operation to change the defined properties in the request body.

And I don't really want to use anyOf and make all the properties nullable, because this will not fulfill my need in the patch operation request body, as one would need to define all other untouched properties as null and it would also conflict with properties that actually is nullable.

[Rycochet]

This seems like an issue with the standard itself - I've just put together a basic working readOnly / writeOnly support PR which will fix the other issue, but being able to change the required status on type is more of an issue - and I think it's more of an openApi issue - personally I think that making sure the default is not required, then adding an allOf for just that property and making it required in that one. It's not elegant but it is maintainable.

From my look at the code, techn ically you could fork and add a custom non-standard schema pattern to https://github.com/drwpow/openapi-typescript/blob/main/src/transform/schema.ts#L36 with readRequired or writeRequired. Tbh I'm not a fan of the array of required keys - I'd much rather have a property on the individual key, but it is a standard... :-)

[techbech]

This seems like an issue with the standard itself

Indeed

From my look at the code, techn ically you could fork and add a custom non-standard schema pattern to https://github.com/drwpow/openapi-typescript/blob/main/src/transform/schema.ts#L36 with readRequired or writeRequired.

I could. But I don't really want to go outside the standard, as other developers and our partners wouldn't find it in the standard documentation 🙂

[drwpow]

Added in #626!