"prefixItems" in draft v7

[hudeany]

Hello good guys,

I have my own implementation of JSON schema validation programmed in JAVA.
As an integration test I use this implementation to check the JSON schema which is available at "http://json-schema.org/draft-07/schema#" against its own definition.

And so I came across the contained definition of "items" as a boolean:

"examples": {
"type": "array",
"items": true
},

Which I didn't understand at first, but now it seems like this has become an alias to the functionality like "additionalItems".
But in the documentation and examples it comes mostly with the keyword "prefixItems" which might replace the old "items" in this construct.

Here an example schema from "https://json-schema.org/understanding-json-schema/reference/array#additionalitems":
{
"type": "array",
"prefixItems": [
{ "type": "number" },
{ "type": "string" },
{ "enum": ["Street", "Avenue", "Boulevard"] },
{ "enum": ["NW", "NE", "SW", "SE"] }
],
"items": false
}

But here comes my question:

"prefixItems" is not mentioned in "http://json-schema.org/draft-07/schema#" at all.
How can this be?

[gregsdennis]

prefixItems was added in 2020-12 when we split the schema-form items and array-form` items.

In previous versions, you can have the schema form

{
  "items": { "type": "object" }
}

which requires that every item in the array is an object.

You can also have the array form

{
  "items": [
    { "type": "object" }
  ]
}

which only requires that the first item is an object, and you can add more subschemas to validate more items in sequence.

additionalItems validates any items not validated by items. This means that for the schema-form items, additionalItems does nothing because there aren't any more items to validate.

For 2020-12, we split the array form of items off to prefixItems and got rid of additionalItems.

So in previous drafts, you have

{
  "items": [
    { "type": "object" }
  ],
  "additionalItems": { "type": "string" }
}

but in 2020-12, you have

{
  "prefixItems": [
    { "type": "object" }
  ],
  "items": { "type": "string" }
}

It does look like we're complicating things by renaming keywords, but really we're simplifying things by making items only ever having a single form.

---

Here an example schema from "https://json-schema.org/understanding-json-schema/reference/array#additionalitems"

We've been finding a lot of stuff like this since updating the website. Thanks for pointing it out. I've opened an issue.

[jdesrosiers]

I came across the contained definition of "items" as a boolean [...] Which I didn't understand at first, but now it seems like this has become an alias to the functionality like "additionalItems".

That's not exactly what's happening. I think what's confusing you is the concept of boolean schemas. Starting in draft-06, you can use a boolean any place a schema is expected. true means any value passes and false means any value fails. Here's another example that might also look strange to you, but works the same way.

{
  "type": "object",
  "properties": {
    "foo": true
  },
  "additionalProperties": false
}

The value of the properties object are schemas, which means you can use a boolean there instead of a schema. In this case, any value is allowed for the "foo" property. The additionalProperties keyword is not saying that no additional properties are allowed, it's saying that all additional properties need to validate against the false schema. The effective result is that additional properties aren't allowed because there are no values that can pass the false schema.

So, the schema you gave as example is equivalent to the following, which probably makes more sense to you.

"examples": {
  "type": "array",
  "items": {}
},