Add support for draft-2019-09

[jdesrosiers]

We need to add support for the following keywords to support draft-2019-09.

items - https://json-schema.org/keyword/draft-04/items
additionalItems - https://json-schema.org/keyword/draft-04/additionalItems

[jdesrosiers]

@Adityakumar37 There are only two keywords that you need to implement for this one, so this is a better place to start. As a first step, do some reading to make sure you understand what these keywords do and which draft-2020-12 keywords they are similar to. Respond here telling me what you learned.

[Adityakumar37]

@jdesrosiers
I’ve added a minimal failing test for items (tuple validation) marked with "compatibility": "2019".

The test fails with Encountered unknown dialect 'https://json-schema.org/draft/2019-09/schema', confirming that draft-2019-09 is not yet registered.

I’ll proceed with registering the dialect and wiring the keyword handlers unless you’d prefer a different approach.

[jdesrosiers]

make sure you understand what these keywords do and which draft-2020-12 keywords they are similar to. Respond here telling me what you learned.

@Adityakumar37 I asked you to respond here telling me your understanding of how these keywords work. You haven't done that yet. Writing tests before you implement is a great practice, but we haven't yet established that you understand how these keywords work well enough to write tests that demonstrate the correct behavior. If the test is not correct, then you'll end up implementing the wrong thing.

I'm not trying to micro-manage how you write code. I'm just trying to make sure you understand what you need to build. That way I can redirect you if you're going in the wrong direction and you don't waste time building the wrong thing.

Start by telling me how items/additionalItems changed from draft-2019-09 to draft-2020-12. If you can describe the changes correctly, then we both can be reasonably sure that you have the right idea and you can start working on a solution. Hint: Look for the draft-2020-12 release notes on the website.

[Adityakumar37]

@jdesrosiers
Here’s my understanding of how items and additionalItems changed between draft-2019-09 and draft-2020-12.

In draft-2019-09 (and earlier drafts), the items keyword serves two different roles:

1. If items is a single schema, that schema is applied to every element in the array.
   1 If items is an array of schemas, it performs tuple validation, where each array index is validated against the corresponding schema.

In the tuple case, additionalItems becomes relevant. It only applies when items is an array and controls how elements beyond the tuple are handled. If additionalItems is false, extra elements are disallowed. If it’s a schema, that schema is applied to any remaining elements.

In draft-2020-12, this behavior was split into separate keywords:

1. Tuple validation moved from items to a new keyword, prefixItems.
2. items now only applies to elements after the prefix items.
3. As a resuladditionalItems was removed entirely, since its role is now covered by items.

Because of this change, draft-2019-09 requires the older, combined semantics for items and additionalItems, while draft-2020-12 uses the newer prefixItems / items split.

From an implementation perspective in json-schema-errors, this means that supporting draft-2019-09 isn’t just a matter of wiring new URIs, but restoring the older semantics for items and its interaction with additionalItems, while keeping the existing draft-2020-12 behavior unchanged

My intention is to handle draft-2019-09 explicitly using those older semantics, rather than trying to map them onto the newer model. Before proceeding, I wanted to make sure this understanding is correct so I don’t end up encoding the wrong behavior in either the tests or the handlers.

Please let me know if this matches your understanding or if there’s anything I’m missing.

[jdesrosiers]

Great! That's exactly right.

My intention is to handle draft-2019-09 explicitly using those older semantics, rather than trying to map them onto the newer model.

Good. I'm expecting we'll have a new error handler for each of these keywords, but if you do that and find there's a good way to combine them with the existing handlers, that works too. The messages should be the same though. I'm not expecting you'll need to add to Localization.

For the tests, however, I think the "mapping" approach is a good one. I think you'll want to go through each existing test with prefixItems and/or items and convert them to items/unevaluatedItems tests. Not all of those mappings will be a distinct test. You shouldn't have duplicates in that case. For example, if the test has items without prefixItems the behavior is the same and you don't need a separate test. For the added tests, the compatibility field should be "<=2019".

Go ahead and get started. Let me know if you have questions along the way. Remember you can always create a PR in "draft" mode if you want feedback before you're done. Then you can take it out of draft when it's done.

[Adityakumar37]

Hi @jdesrosiers, thanks again for all the guidance so far — I wanted to share a quick status update and describe the exact issue I’m stuck on, in case you can help unblock me.

What I’ve done so far

Based on your earlier feedback, I followed this approach:

1. Tests first

I added new tests for draft-2019-09 tuple validation using items with compatibility: "<=2019".

These are mapped from the existing prefixItems/items tests in 2020-12, converted back to the older items / additionalItems semantics (no duplicate cases where behavior is identical).

2. Separate handlers for old semantics

I created new normalization handlers:

• items-draft04.js (used for draft-2019-09 tuple behavior)
• additionalItems-draft04.js

These intentionally follow the pre-2020 semantics: tuple validation via items as an array, and extra elements controlled by additionalItems.

3. Explicit keyword registration

I registered these handlers explicitly for the 2019-09 keyword URIs:

setNormalizationHandler(
  "https://json-schema.org/keyword/draft-2019-09/items",
  itemsDraft04
);

setNormalizationHandler(
  "https://json-schema.org/keyword/draft-2019-09/additionalItems",
  additionalItemsDraft04
);

All existing 2020-12 handlers remain unchanged.

What’s working

• All draft-2020-12 tests still pass.
• Most draft-2019-09 tests pass.
• The new handlers are definitely being picked up (the previous “unsupported keyword” error is gone).

The specific problem I’m stuck on

There’s one remaining failing test:

items (tuple validation) - draft 2019-09
Expected: type error at #/0
Received: []

So tuple validation does run, but no error makes it into the final jsonSchemaErrors output.

At the same time, TypeScript reports a related issue:

evaluate returns (NormalizedOutput | null)[],
but NormalizationHandler.evaluate expects void | NormalizedOutput[].

I’ve tried:

• returning [] instead of null
• filtering falsy values
• matching the structure used by existing handlers

…but I’m clearly missing something more fundamental.

Where I think the confusion is

It looks like evaluateSchema is being called for each tuple index, but the resulting NormalizedOutput is either:

• not being merged correctly, or
• being ignored due to how simpleApplicator handlers are expected to return output.

So my core uncertainty is about the contract of evaluate for older tuple semantics.

What I’m hoping you can clarify

For draft-2019-09 items (tuple form), should the handler:

• directly call evaluateSchema per index and return those outputs (similar to prefixItems), or
• rely on some interaction with additionalItems / unevaluated tracking that I’m missing?

Is there an existing handler (e.g. prefixItems, contains, etc.) that you’d recommend mirroring most closely for this case?

Thanks again for the guidance, really appreciate your time.

[jdesrosiers]

I registered these handlers explicitly for the 2019-09 keyword URIs:

You have the wrong keyword URIs. See the issue description for the correct URIs. If those aren't right, the handlers won't get picked up correctly.

evaluate returns (NormalizedOutput | null)[],
but NormalizationHandler.evaluate expects void | NormalizedOutput[].

It's hard to say what's wrong here without seeing the code, but you definitely shouldn't be returning null. Because this is a simple applicator, it should be returning a NormalizedOutput[].

For draft-2019-09 items (tuple form), should the handler:

• directly call evaluateSchema per index and return those outputs (similar to prefixItems)

Yes. It should work exactly like prefixItems.

Is there an existing handler (e.g. prefixItems, contains, etc.) that you’d recommend mirroring most closely for this case?

The additionalItems handler should look almost exactly like the draft-2020-12 items handler. The draft-04 items handler should look very similar to the prefixItems handler, but also take into account the non-tuple case.

[Adityakumar37]

Hi @jdesrosiers, quick update now that I’ve got everything passing. Thanks a lot for the guidance — it helped narrow things down.

What was going wrong

• I initially used the wrong keyword URIs, so the handlers weren’t always being picked up correctly.
• My first draft of the handlers returned null in some cases, which broke the simpleApplicator contract (evaluate must always return a NormalizedOutput[]).
• For additionalItems, I also incorrectly tried to read context.schema, but EvaluationContext doesn’t expose schema data that way.

What I changed

• Added two explicit normalization handlers:

• items-draft04.js — implements draft-2019-09 tuple semantics

• additionalItems-draft04.js — implements legacy additionalItems behavior

• Registered them using the correct keyword URIs:

• https://json-schema.org/keyword/draft-04/items

• https://json-schema.org/keyword/draft-04/additionalItems

• Reworked items-draft04 to mirror prefixItems closely:

• Iterate over tuple indices

• Call evaluateSchema per index

• Always return a NormalizedOutput[]

• Reworked additionalItems-draft04 to mirror the draft-2020-12 items handler:

• Only applies when items is a tuple

• Starts validating at items.length

• Handles true, false, and schema forms correctly

• Removed all null returns and ensured both handlers are proper simpleApplicators.

Current state

• All existing tests still pass
• New draft-2019-09 tuple tests pass
• 2020-12 behavior is unchanged
• No TypeScript errors remain

I think this matches the intended semantics now, but I’m happy to adjust anything if you spot an issue. Thanks again for the help!