2020-12 Schema: Tuples and Backwards Compatibility

[mlcohen]

Hi -- In the JSON Schema 2020-12 release notes, there is a section going over the changes made to the item and additionalItems field. The notes say the following:

The items and additionalItems keywords have been replaced with prefixItems and items where prefixItems has the same functionality as the array-of-schemas for of the old items and the new items keyword has the same functionality as the old additionalItems keyword.

Given the change, should a JSON Schema library that handles the 2020-12 schema be implemented in a way that it remains backwards compatible with how a tuple is defined using the 2019-09 schema? For example, would the following schemas still be valid for when validated against JSON Schema 2020-12:

// Open tuple
{
  "items": [
    { "$ref": "#/$defs/foo" },
    { "$ref": "#/$defs/bar" }
  ]
}

// Closed tuple
{
  "items": [
    { "$ref": "#/$defs/foo" },
    { "$ref": "#/$defs/bar" }
  ],
  "additionalItems": false
}

// Tuple with constrained additional items
{
  "items": [
    { "$ref": "#/$defs/foo" },
    { "$ref": "#/$defs/bar" }
  ],
  "additionalItems": { "$ref": "#/$defs/baz" }
}

My assumption is that, no, defining a tuple using the JSON Schema 2020-12 spec is not backwards compatible with how tuples are defined in the JSON Schema 2019-09 spec.

[gregsdennis]

You're correct, because additionalItems isn't a keyword anymore, this isn't a compatible change from 2019-09 to 2020-12. None of those schemas you posted are valid for 2020-12.

However, the split of the array form of items to prefixItems provides the same functionality.

The following are now what you'll need to record the same requirements.

// Open tuple
{
  "prefixItems": [
    { "$ref": "#/$defs/foo" },
    { "$ref": "#/$defs/bar" }
  ]
}

// Closed tuple
{
  "prefixItems": [
    { "$ref": "#/$defs/foo" },
    { "$ref": "#/$defs/bar" }
  ],
  "items": false
}

// Tuple with constrained additional items
{
  "prefixItems": [
    { "$ref": "#/$defs/foo" },
    { "$ref": "#/$defs/bar" }
  ],
  "items": { "$ref": "#/$defs/baz" }
}

[gregsdennis]

An additional note on the backwards compatibility issue, were working to address those kinds of changes for future versions.

[mlcohen]

Thanks for the help!

As a follow up, would it be better to have an explicit tuple type rather than overloading the array type to serve as a basic array and tuple? With a tuple type, the prefixItems field would be exclusive to that type. You could even go back to using items and additionalItems for tuple. That would help simplify the array type where you only need an items field. Addition of a tuple type would make the intent clear. For example:

{
  "type": "tuple"
  "prefixItems": [
    { "$ref": "#/$defs/foo" },
    { "$ref": "#/$defs/bar" }
  ],
  "items": { "$ref": "#/$defs/baz" }
}

// or even...

{
  "type": "tuple"
  "items": [
    { "$ref": "#/$defs/foo" },
    { "$ref": "#/$defs/bar" }
  ],
  "additionaItems": { "$ref": "#/$defs/baz" }
}

[Relequestual]

Hey @mlcohen, we are (mostly) constrained by what is in JSON itself*. If we add one more extra type, that opens the flood gates to many more which would be equally warranted.

*We have both Number and Integer. I can't remember the specific justifications at the time. If you're interested, you could probably find out, or someone else might recall.

[jdesrosiers]

I can't remember the specific justifications at the time.

The "integer" type was included from the beginning, long before anyone currently involved in the project was around. It really shouldn't be included because it isn't a JSON type. I'd say that the reason it's there is because it always has been.

IMO, "integer" or "tuple" should be format values. The format keyword signals to applications how to interpret a value of a type that can't be expressed in JSON. The "date" format is a more obvious example. JSON doesn't have a way to express a Date, so you have to just encode it as a JSON string. The same would apply to Integers encoded as JSON numbers or Tuples encoded as JSON arrays.

[mlcohen]

@Relequestual Yeah, makes sense. The integer type being the one special case. From the JSON Schema learning docs:

The integer type is used for integral numbers. JSON does not have distinct types for integers and floating-point values. Therefore, the presence or absence of a decimal point is not enough to distinguish between integers and non-integers

Thanks for the help!