No documentation for the "properties" object

[Sebi2020]

The OpenAPI specification misses an explanation for the "properties"-Object. It would be helpful if the specification would contain information on the uses of the properties object.

In direct definitions (under paths, without references to defintions and components) the properties object is not used, but it is in component definitions.

[handrews]

@Sebi2020 The properties keyword is only used in Schema Objects. This is true of all JSON Schema keywords, except when explicitly stated to be used in other objects as well.

[Sebi2020]

Okay, I just wanted to suggest that it might make sense to document the use case for "properties" objects.

[handrews]

@Sebi2020 for general use cases with JSON Schema concepts (particularly given that OAS 3.1 is likely to introduce full compatibility with JSON Schema draft 2019-09, per #1977), you should really look to JSON Schema resources such as Understanding JSON Schema which is now maintained by the JSON Schema project.

(although note that since 2019-09, formerly known as draft-08, was released just 8 days ago, Understanding JSON Schema has not yet been updated for that draft. It is, however, updated for draft-07.)

I don't think that explaining how to use JSON Schema is the responsibility of the OpenAPI spec. OAS should only have to explain their extensions.

[Sebi2020]

The documentation OAS 3.0 documentation states:

properties – individual property definitions must follow OpenAPI schema rules and not standard JSON Schema.
Source: https://swagger.io/docs/specification/data-models/keywords/

So if you explicitly state, that json schema does not apply to the OpenAPI properties keyword, the documentation should mention applicable rules for the properties keyword, because otherwise it's not obvious what is meant by "[...] and not standard json schema".

[handrews]

Blah. That doesn't mean "it doesn't work like JSON Schema at all" that just means "your subschemas need to use the OAS dialect just like your parent schemas."

I can definitely see that being non-obvious. We'll see if the TSC folks have any thoughts on changing this. It will be a lot more straightforward in OAS 3.1, but maybe a clarification can go in 3.0.3 in the meantime.

[handrews]

@webron this is fixed in 3.1 b/c the wording is no longer present. If it hasn't generally been a concern in 3.0.x this probably falls under the "let's not put more words in the spec" category we were discussion, in which case this should probably be closed?

I think the important thing here is that as of 3.1 this is no longer a concern anyway.

[MikeRalphson]

Closing as above.