🧹 Clarification: missing definition of `required` for object schema properties

[drpump]

Specification section

Core, Section 10.3.2

What is unclear?

The semantics of the required keyword are undefined: it does not appear at all in the object subschemas section.

This leads to ambiguity in its application. For example, the following JSON schema fragment is interpreted differently by AJV and the OpenAPI generator:

  "allOf": [
    {
      "properties": {
        "resourceId": { "type": "string", "format": "uuid" },
        "self": { "type": "string", "format": "uri" }
      }
    },
    {
      "required": ["resourceId", "self"]
    }
  ]

AJV rejects JSON object instances that do not contain both properties identified as required. The OpenAPI generator interprets required only in its enclosing subschema context, and allows objects with neither property. If I add a duplicate definition of the properties in the second subschema, the OpenAPI generator then rejects objects that do not contain both properties.

While I believe the AJV interpretation is appropriate, the JSON schema specification does not define the expected behaviour so both could be considered correct.

Proposal

Explicitly define the expected behaviour of required in section 10.3.2, making the AJV interpretation the correct interpretation, that is, validation fails if any properties listed in the required array are not present in the instance.

Do you think this work might require an [Architectural Decision Record (ADR)]? (significant or noteworthy)

Yes

[jdesrosiers]

The semantics of the required keyword are undefined

The required keyword is defined in Section 6.5.3 of the Validation spec. I know it's confusing that the spec is in two pieces and it might also be confusing how things are split.

The semantics of required are define as following.

An object instance is valid against this keyword if every item in the array is the name of a property in the instance.

So, ajv is doing this correctly according to the spec and OpenAPI generator (which I'm not familiar with) is not behaving according to the spec and has a bug that should be reported.

[drpump]

Thanks, yes it is a little confusing having the spec split like that. The validation wording is clear, so closing this issue.

[drpump]

Will raise a corresponding bug against the OpenAPI generator.