Skip to content

Clarify spec wrt readOnly and writeOnly in referenced schemas #1622

@tedepstein

Description

@tedepstein

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions