Items Object should not be an array of object - #609

An array of objects is completely valid. The items value can be an object itself which applies a single JSON Schema to all items in the array or items can be an array of objects that will apply the schema to specific array items via its index.

I defer to @webron on this one but this is how I interpreted it and how the tooling I've written supports things.

@whitlockjc thanks for the quick response! You are absolutely right, the JSON Schema specification says that the items property of an array type "...MUST be either an object or an array. ..." [5.3.1.1].

However, the Swagger/OpenAPI specification is a bit more limiting. It defines that the "items" property is an Items Object. Which is specifically identified as being a subset of a JSON-Schema's item.

If it is the case that you can have an array of Items Objects, then I propose that the Swagger / OpenAPI spec should explicit say so since it seems that is not clearly expressed. Or should be included in future versions of the spec.

What is peculiar is that the swagger editor (with built validation) does not throw an error if given an array, however it doesn't know how to process the given array of objects. Not knowing how their validation system works, I would speculate that the intent of the spec was not to handle arrays.

I am looking forward to this discussion and getting @webron input.

@EricHenry you are correct. The Swagger editor is an implementation which supports the spec, but that doesn't make it prone to errors. Support for arrays under items actually is a bug--per the subset of JSON schema that the spec supports, it should not allow it.

Maintaining a human readable documentation (the 2.0 readme) is the goal, and unfortunately sometimes there are errors in it. The schema that is built manually from that readme's intent is not the official documentation of the spec, so tooling that use it (like the editor) may not reflect the spec itself.

@fehguy thanks for your response! I was in no way trying to attack the Swagger editor, I think it is a wonderful tool, and I use it quite often. I just wanted to make sure that the examples reflect the spec, to lessen potential errors or confusion.

I agree that maintaining human readable documentation is difficult, especially with such a large spec. Do you feel that the readme is specific enough in describing the Items Object?

Hey guys any update or other thoughts on this PR?

Yeah, the PR is right. Array values for items are not supported by the spec (2.0 at least).

Sorry to necro, but... I really need array values for items... How do I represent this? Is there some other funky way I can specify a specifically structured array?
E.g. Item 1 must be a string, Item 2 must be a number, etc.

Noting the array form of items is now supported in OAS 3.1 using the prefixItems keyword.