Requirement of schema or content in parameter object is difficult to notice

[pbasista]

One of the paragraphs within the "Parameter Object" section of the current OpenAPI v3 specification contains this statement:

A parameter MUST contain either a schema property, or a content property, but not both.

The schema or content fields in the tables of fields in the "Parameter Object" section do not contain the REQUIRED keyword. That is okay, because these fields are not strictly required. But at the same time, the entries in these tables do not mention a combined requirement of one of those fields.

The statement mentioned at the beginning is easy to overlook. I think that the conditional requirement of any fields should also be mentioned in the table, because it is the first and often the only place where a person would normally look for the field's definition.

[darrelmiller]

We are open to adding some clarification if someone can suggest a clean annotation markup to the spec.

Should we duplicate the constraint in the each of the property descriptions? Suggestions are encouraged.

[pbasista]

I can see at least these two options:

1. Define a new keyword, phrase or a generic markup construction which shall be used consistently in the description column of all the fields whose presence, requirement or meaning is altered by the presence or value of other fields. For example, the description of the schema field of the Parameter Object may include: "<Markup for "attention please"> requirement is altered by [a link to paragraph explaining the more complex condition]".

2. For each object, create a separate "Constraints" table which will list more complex constraints that affect the object's fields. One column of such a table shall list all the affected fields and the other shall describe the condition. This would effectively move the paragraphs which describe the complex constraints into the constraints table. The advantage is that it should be easier to make a complete picture of these constraints and not overlook one.

Edit: commas

[fenollp]

A parameter MUST contain either a schema property, or a content property, but not both.

To me this needs only says there's a XOR constraint on setting these two fields. This phrasing should be clearer:

A parameter MUST contain exactly one of schema or content properties.

This emphasizes that at least one is required, which I'm still not sure is correct?

[handrews]

Hmm... this one is complicated because it's three separate tables of fixed fields: the general fields, and the each of the two mutually exclusive options. It's not just that exactly one of content or schema MUST be present. style and explode only make sense with schema (style depends on the type keyword, and explode depends on style). But the other keywords in the table with schema can presumably work with content: allowReserved (although see #3759), and the mutually-exclusive example and examples.

I think maybe a standard section after "Fixed Fields" listing relational constraints would be the best approach. Or maybe a "Field Combination Rules" table just before or after the Fixed Fields table without a section. But those Parameter Object tables need cleaning up anyway to make it clear that some keywords can be used with content as well as with schema.

[handrews]

Ah, I was actually wrong about part of it, example and examples only go with schema because they can be specified differently in content. It's actually not clear to me whether allowReserved can go with contetnt or not. I guess not? But I find that keyword odd to begin with as noted in the linked issue about it. Yeah.. this really needs cleaning up.

[handrews]

PRs for all active lines merged! Closing.