Clarify spec wrt readOnly and writeOnly in referenced schemas

The current spec says that readOnly and writeOnly are “relevant only for Schema properties definitions.”

I have encountered at least two parsers, one new, one widely used, that interpret this in the most literal sense, meaning “discard readOnly and writeOnly if they occur in a top-level schema definition.”

The parsers either have their own logic that does this, or they parse into an object graph that:

• has separate classes for top-level schema objects vs. property subschemas; and
• the top-level schema object class has no way to represent readOnly and writeOnly.

With this interpretation, reusable schemas can’t be intrinsically readOnly or writeOnly by definition. The following won’t work:

components:
  schemas:
    project:
      type: object
      properties:
        projectID:
          type: string
        projectName: 
          type: sting
        created:
          $ref: "#/components/schemas/dataChangeEvent"
        updated: 
          $ref: "#/components/schemas/dataChangeEvent"
          
    dataChangeEvent:
      readOnly: true
      type: object
      properties:
        changedBy:
          type: string
        timestamp:
          type: string
          format: date-time

I would interpret “relevant” to mean that the readOnly and writeOnly annotations are only effective in the context of a property subschema. Not that they are disallowed, safe to ignore, or safe to discard when declared in other contexts.

I think my interpretation is probably consistent with the original intent, but I wasn’t part of that discussion. The word “relevant” is ambiguous, and the spec only uses that word in the readOnly and writeOnly descriptions.

I think the simple answer is to clarify the meaning of the spec. The current spec for readOnly starts like this:

Relevant only for Schema “properties” definitions. Declares the property as “read only”.

I’d propose changing it to:

MAY occur in any Schema Object. When used in a property subschema, either directly or by reference, a true value declares the property as “read only”.

Similar change proposed for writeOnly. Happy to open a PR with this change if the TSC agrees.

[ChaitanyaBabar]

@darrelmiller @tedepstein Since we seem very likely to move to JSON Schema 2019-09 in OAS 3.1, this problem will go away since (as noted above) the issue is now addressed in the JSON Schema spec. We haven’t had anyone complain about how we specified it so it seems to be working out OK.

@handrews I had gone through above discussion and since the docs change by @tedepstein is not yet reflected in trunk just wanted to sure that I have interpreted the discussion correctly so asking few Questions below.

@handrews @philsturgeon @darrelmiller Can you please put in your thoughts/comments about the same.

• Question 1 :- Does above comment mean that readOnly would be supported in root context in current OAS specifications ?

• Question 2 :- If that is the case what would happen when readOnly is used along side $ref ? As per docs official here it says siblings property along side $ref are ignored , so is the use of readOnly along side $ref supported ?

• Question 3 :- Is there any difference between use/interpretion of readOnly between OAS 3.0.X and OAS 3.1.X versions ?

[MikeRalphson]

I would be in favour of pointing people at the schema pre-processing solutions suggested by @tedepstein if/when this comes up (i.e. not in the spec itself)