Support @readOnly/@writeOnly in JSON Schema and OpenAPI?

[ouvreboite]

In the decorators documentation, there is a mention of a @readOnly decorator. But I'm unable to find it in the playground.

Maybe it's outdated?

model Dog {
  name: string;
}

@@readOnly(Dog.name);

Related to that, I would like to understand what's the current state about supporting readOnly/writeOnly in OpenAPI 3.0 and JsonSchema 2020-12 (that both support it). From this issue it seems some work has been done, but I couldn't find a way to produce a "readOnly" property in OpenAPI

[timotheeguerin]

It doesn't that doc just shows the concept of augment decorator, though might be better we use a known one to reduce confusion.

This is what you can use to set readonly property.

@visibility("read") 

[bterlson]

We should definitely not use a non-existent decorator 😁

Also, note that the JSON Schema emitter does not presently support this annotation. There is a workaround for now, which is to use the extension mechanism. The following would work for both emitters:

model Test {
  @JsonSchema.extension("readOnly", JsonSchema.Json<true>)
  @visibility("read")
  x: string
}

[markcowl]

Write-only generally means that the property appears only in resource 'create' and 'update' requests, and in http operations, this is represented with: @visibility("create", "update")

[ouvreboite]

Thank you.

@JsonSchema.Extension seems a useful workaround, but quite verbose. Is there any plan (or would a PR be accepted) to create proper @ReadOnly and @WriteOnly decorators ? (Either only in the JsonSchema namespace or also for OpenApi)

[bterlson]

I think there are some design questions here we need to settle. I think the main design question is, should JSON Schema use visibility like OpenAPI, or no? On the one hand, it would allow the same models to work everywhere, getting identical semantics across OpenAPI and JSON Schema, with only the visibility decorators. On the other hand, it seems strange to teach a vanilla schema emitter about HTTP/Rest visibility - visibility is a more complex feature that links an operation's lifecycle method to the fields that are visible in the model, which isn't something JSON Schema should care about.

So, perhaps @readOnly/@writeOnly makes sense for the JSON Schema library. Then perhaps we might want to allow that also in OpenAPI 3 as well, despite the previous conversation deciding against it. These decorators would be allowed anyway in later OpenAPI versions and emitters because 3.1+ aligns OpenAPI Schema and JSON Schema to a degree that we can just use the JSON Schema vocabulary directly and dispense with the OpenAPI-specific ones.

[bterlson]

Let's just use this issue as the design issue, I've updated the label and description.