Enhancement: Collapse overlapping numeric constraint error messages in anyOf/oneOf

[srivastava-diya]

Problem Description

Currently, when validating against an anyOf or oneOf schema that has multiple overlapping numeric or string constraints, the error output returns a separate message for every failed alternative like so ,

{
  "anyOf": [
    {
      "type": "string",
      "maxLength": 2
    },
    {
      "type": "string",
      "maxLength": 4
    }
  ]
}

• If we validate an instance like "hello" (length 5), the errors retured are:

Expected one or more of the alternatives to pass validation:
- Expected a string with no more than 2 characters
- Expected a string with no more than 4 characters

Proposed Enhancement

As pointed out by @jdesrosiers here since these constraints are somehow testing the same attribute (string length) and one constraint is a subset of the other, they could be collapsed into a single, more concise error message.

For the example above, the ideal collapsed output for the user would be:

"Expected a string with no more than 4 characters"

Opening this issue to discuss

• What logic should be used to determine if two alternative errors are collapsible?
• Feedback and suggestions are very welcome.

[Ahmedmhmud]

I think it can be done in two different ways but the same logic
Since we have the access on the instance, we can get the best constraint value if it is in multiple alternatives by iterating on them but there is something that will make the logic too complex
We want two know if the alternatives are identical except in the targeted keywords like minLength, so

Recommended logic:
We make a new directory as a selection tool to use in the error handler method of the targeted keywords that may include more than one alternative (anyOf, oneOf, ... )
They use the alternative object that is resulted from the logic of the error handler like that:

const anyOfErrorHandler = async (normalizedErrors, instance, localization) => {
  /** @type ErrorObject[] */
  const errors = [];

  for (const schemaLocation in normalizedErrors["https://json-schema.org/keyword/anyOf"]) {
    const anyOf = normalizedErrors["https://json-schema.org/keyword/anyOf"][schemaLocation];
    if (typeof anyOf === "boolean") {
      continue;
    }

    const alternatives = [];
    for (const alternative of anyOf) {
      alternatives.push(await getErrors(alternative, instance, localization));
    }

    // Use the selector methods to collapse the duplicated messages of the same type

    errors.push({
      message: localization.getAnyOfErrorMessage(),
      alternatives: alternatives,
      instanceLocation: Instance.uri(instance),
      schemaLocations: [schemaLocation]
    });
  }

  return errors;
};

By iterating the alternatives for each keyword that causes the duplication and see the best one to choose over the others like it is done in maxLength error handler for example
This will take some time but overall it is for very specific keywords like allOf that accept multiple alternatives, and we can optimize it by choosing the proper data structure for storing the errors.

[animeshsahoo1]

If we intercept the errors before getErrors runs, we can work directly with the raw NormalizedOutput data.
Here is what i have thought of:

1. create a map with "Failure Unique Key"
   first, we look at exactly which keywords caused each alternative to fail. We create a "unique key" (a sorted list of the failed keyword URIs) and group the alternatives together. Two alternatives only end up in the same bucket if they failed for the exact same reasons.

2. Filter for Collapsible Rules
   next, we check if the group is safe to merge. We only want to collapse groups where every failed keyword is a simple boundary limit (e.g., maximum, minimum, maxLength, minLength, maxItems, maxProperties, etc).
   If a group tripped up on a structural rule like type, pattern, etc we back off and leave the errors exactly as they are.

3. Collapse to widest Rule
   For the groups that are safe to collapse, we just reduce them down to the biggest limit. We keep the largest value for "max" rules and the smallest value for "min" rules.

example:
{
"anyOf": [
{ "type": "string", "maxLength": 2 },
{ "type": "string", "maxLength": 4 }
]
}

case A: The data is a string
The type check passes for both, but maxLength fails for both.
The Fingerprint: ["maxLength"].
Since maxLength is on our safe list, we group them and keep the most permissive rule (maxLength: 4).

casee B: The data is a number
Now, both type and maxLength fail.
The unique key: ["type", "maxLength"]
Because type is not on our safe list, the filter stops the collapse. Both alternatives are shown normally to the user so they can see exactly where the structure broke down.

[Sam-61s]

My suggestion over this issue is in two phases

Phase 1 — Fix inconsistent boundary handlers first.
minimum.js and maximum.js currently emit one error per violation, which should give the most permissive value. Before cross-alternative collapsing, we should have to make all boundary handlers consistent — maximum.js keeps highest value, minimum.js keeps lowest. Same pattern for exclusiveMaximum, exclusiveMinimum, maxItems, maxProperties etc.

Phase 2 — Cross-alternative collapsing in anyOf.js / oneOf.js.
As @animeshsahoo1 suggested, work at the NormalizedOutput level before getErrors runs. For each alternative, compute a failure fingerprint — the sorted list of keyword URIs that have any failing entry. Group alternatives with identical fingerprints. Only collapse a group if every keyword in the fingerprint belongs to this safe list: maxLength, minLength, maximum, minimum, exclusiveMaximum, maxItems, maxProperties etc. If any keyword outside this list appears (type, const, enum, pattern, etc.), leave those alternatives uncollapsed. For safe groups, merge their NormalizedOutput objects into one and call getErrors once — the Phase 1 handlers then automatically pick the most permissive value from the merged data, so no new collapsing logic is needed elsewhere.

Example

{ "anyOf": [
  { "type": "string", "maxLength": 2 },
  { "type": "string", "maxLength": 4 },
  { "type": "number", "minimum": 2 }
]}

Instance: "hello"

Group A (alts 0 + 1): fingerprint ["maxLength"] — in safe list → merge
"Expected a string with no more than 4 characters"

Group B (alt 2): fingerprint ["minimum", "type"] — type not in safe list → keep as-is

Final anyOf error has two alternatives instead of three — one for the collapsed string constraint, one for the number branch.

[suruanush]

This PR introduces Error Collapsing for anyOf and oneOf schemas to eliminate redundant validation noise. Currently, if an input fails multiple overlapping constraints—such as maxLength: 2 and maxLength: 4—the validator outputs every failure, overwhelming the developer with a "wall of text."My solution implements a Widest Constraint filter. When multiple sub-schemas fail on the same attribute, the engine identifies the least restrictive threshold and surfaces only that error.

[srivastava-diya]

hey @jdesrosiers
I’m planning to start working on this and was thinking of opening a draft PR based on the discussion and my current understanding. Before I begin, I wanted to clarify a couple of points:

1. When collapsing, the chosen error could reference only its own schemaLocation, or it could include all the schemaLocations from the collapsed alternatives ? I was thinking of merging them.

2. If alternatives have errors from different keywords (e.g., one has maxLength and another has minLength), we do not collapse, right ?

Thanks!

[jdesrosiers]

I haven't paid attention to this one yet because I don't think it's high priority, but reading it now, I don't think this is ready to implement. There's a more general concept here that the discussion is missing. This isn't just about numeric constraints. It could occur in almost any schema with many more keywords than have been considered so far. I think this is a much bigger task than anyone realizes.

Consider this example.

{
  "anyOf": [
    { "type": "string" },
    { "type": "string", "minLength": 3 } // subsumed
  ]
}

Given a number, we'd get two alternatives that both say the instance is expected the be a string. In this case, alternative 1 subsumes alternative 2 and we should be able to return just alternative 1.

Here are some more examples using const/enum/type. Notice it doesn't always have to be the same keyword failing.

{
  "anyOf": [
    { "enum": ["a", "b"] },
    { "enum": ["a"] } // subsumed
  ]
}

{
  "anyOf": [
    { "enum": ["a", "b"] },
    { "const": "a" } // subsumed
  ]
}

{
  "anyOf": [
    { "enum": ["a", "b"] }, // subsumed
    { "const": "a" }, // subsumed
    { "type": "string" }
  ]
}

{
  "anyOf": [
    { "type": ["string", "number"] },
    { "type": "string" } // subsumed
  ]
}

Now consider nested structures like objects and arrays.

{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "foo": { "type": "string" }
      }
    },
    {
      "type": "object",
      "properties": {
        "foo": { "type": "string", "minLength": 3 } // subsumed
      }
    }
  ]
}

Given { "foo": 42 }, we should be able to collapse to the first alternative.

We also need to consider nested alternative keywords. For example,

{
  "anyOf": [
    {
      "anyOf": [
        { "const": "a" },
        { "const": "b" }
      ]
    },
    { "const": "a" } // subsumed
  ]
}

---

I think we're going to want to start a function that takes two alternatives as instances of NormalizedOutput and returns whether one subsumes the other. Then once we have that function well tested, we should be able to add a filter to the anyOf and oneOf handlers relatively easily. We don't need to handle every case all at once, but we should keep the general concept in mind and some of the edge case presented here so we're building something that will scale to all the different cases we'll want to consider.

[srivastava-diya]

hey @jdesrosiers You are completely right, this is a much bigger and more general concept. Looking at it through "subsumption" logic rather than just numeric constraints makes more sense, and those const/enum and nested object examples really highlight why a generalized approach is needed.

I love the idea of building a standalone subsumes(alt1, alt2) utility that operates directly on the NormalizedOutput. Isolating this logic will make it so much easier to test all of these edge cases before we ever touch the anyOf or oneOf handlers.

• I can provide a Draft PR focused solely on the subsumes utility. Write a good test suite for it, starting with the exact examples you provided above (types, enums, strings, and nested objects).

• I was thinking of writing the isSubsumed() function and placing it in src/subsumption.js and testing it in src/subsumption.test.js

• Once we get the feel that subsumes function scales well and the tests pass, we can drop it into the anyof/oneOf error handlers.

• as you suggested we don't have to support the entire JSON schema vocabulary in version 1 of the function, but designing it this way ensures it is built to scale. Does this sound like a good starting point to you?

[Ahmedmhmud]

I think that @srivastava-diya is right about the starting point by making the function that @jdesrosiers mentioned above by taking two alternatives and see if they are subsumed.

After that we need to know how we will use it in the error reporting
In the example of nested anyOf, we can deal with it as it is a big outer anyOf with all the alternatives in the inner ones, it can be done by recursion by passing an empty context and adding the alternatives whose in the anyOf.

But it can't be done with oneOf why?
If two instances can be subsumed and they both passes, oneOf fails, but with subsumming logic, we deal with them as one alternative or we will better leave it until the subsumming logic.

That is the solution of the nested alternatives for me

And it partially depends on subsumming logic so I suggest we first implement the subsumming function.

And for subsumming function, I will think of its logic and leave another comment later.