OpenAPI-Specification

OpenAPI-Specification copied to clipboard

In the spec currently this is valid:

type: object
required:
- name
properties:
  name:
    type: string

However, this is not:

type: object
readOnly:
- name
properties:
  name:
    type: string

This is needed because when using a ref (for example, to an enum) this does not work:

type: object
properties:
  somEnum:
    readOnly: true
    $ref: '#definitions/SomeEnum'

I believe this will be outside the initial 3.0 proposal, so labeling appropriately

The same problem exists on things like description and default. Is there any good way to resolve this in a way that solves this problem for those attributes as well?

description and default are unlikely to change as they are part of JSON Schema and that's just how it works. readOnly is different as it's our addition.

See issue 556 for (much) more on combining $ref and other properties.

I would expect this to work:

type: object
properties:
  somEnum:
    allOf:
      - readOnly: true
      - $ref: '#definitions/SomeEnum'

I take it this construct is not allowed? This is the second issue I have seen with this sort of thing.

(also, readOnly and writeOnly will be in JSON Schema's validation spec in draft-07, and should be compatible with OpenAPI)

@webron wrote:

description and default are unlikely to change as they are part of JSON Schema and that's just how it works. readOnly is different as it's our addition.

I would argue that readOnly is different because it is more strongly tied to the property than the schema . A single schema could be be read-only when used in the context of one property, but read-write (or even write-only) in another property.

@handrews, I like your allOf solution, and it does seem to work.

This also works:

definitions:
  SystemID:
    type: "string"
    readOnly: true
  Person:
    type: "object"
    minProperties: 1
    properties:
      id :
        $ref: '#/definitions/SystemID'
      firstName:
        type: string
      lastName:
        type: "string"

However, this doesn't allow for properties to override the readOnly or readWrite value; it's intrinsic to the schema.

@tedepstein we (JSON Schema project) have considered making readOnly and writeOnly arrays, but while I initially felt like that was the right direction, I became less sure of it as the discussion progressed. We probably won't change it in draft-07 (which should be published in the next couple of weeks), but we haven't dismissed the idea.

I would be very interested in hearing from as many people in the OpenAPI community as would care to comment on this. As major users of readOnly as a boolean (and AFAIK the only users of writeOnly in any form) the experience of this community will carry a lot of weight in the discussion:

https://github.com/json-schema-org/json-schema-spec/issues/364

Thanks, @handrews. I think you summarized my concern pretty neatly in this comment:

Validation schemas fundamentally describe a type, in the form of an acceptable set of values. "readOnly" not only does not impact that, but is highly context-dependent. It is likely to vary for the same type depending on where and how it is used.

Having readOnly and writeOnly as arrays on the object seems like a good way to address this. It seems cleaner and more obvious than the allOf solution you posted earlier.

Having said that, I'm not (yet) up-to-date on the contextual discussions concerning patternReadOnly, additionalReadOnly, $use, targetHints (in HyperSchema), and annotation keywords. So I can't see the full range of implications if JSON Schema were to adopt this change, and I don't know if there are any alternatives you're considering.

The important thing, IMO, is to separate the definition of a type (as a set of constraints) from usage of that type in a given context. readOnly and writeOnly, in almost all cases, seem like they fall in the latter category.

Side note: if you go in the direction of readOnly and writeOnly as object-level arrays, I don't think you need to support indexes for tuple-type arrays, unless there's strong evidence that people really need that level of control. I'm saying this, subjectively, only because I don't see much use of arrays as tuples, and because I think that feature is separable, easy enough to add in a later draft if there's demand for it.

@tedepstein I'd ignore $use as I think some other developments in draft-07 and likely proposals for draft-08 have made it irrelevant. The whole patternReadOnly/additoinalReadOnly/etc mess flows from the fact that not all instance object properties are defined by name in properties, so you can't necessarily define them by name in an array either. required has similar limitations, although keywords like minProperties partially solve those limitations.

Of course there's the question of how often one would want annotate properties described by patternProperties and additionalProperties with read/write-only anyway. It gets rather complex and that aspect is probably best discussed in the JSON Schema issue rather than here.