feat: include the expected value in const errors by Dhairya-007 · Pull Request #326 · atlassian/better-ajv-errors

Dhairya-007 · 2026-11-04T16:00:00Z

Closes #162.

The issue asked whether the expected constant could be included in the message. ajv already hands it to us in params.allowedValue; it was just being dropped, because const had no handler and fell through to DefaultValidationError.

Before / after

Using the exact schema from the issue:

- /node: const must be equal to constant
+ /node must be equal to constant: ">=18.12.0"

CLI format:

CONST must be equal to constant
(">=18.12.0")

  1 | {
  2 |   "engines": {
> 3 |     "node": ">=18.12.1"
    |             ^^^^^^^^^^^ 👈🏽  Should be equal to ">=18.12.0"
  4 |   }
  5 | }

Approach

A ConstValidationError class, modelled on EnumValidationError — which already appends its allowed values in the same shape — rather than special-casing const inside the default handler. So: new ConstParams type, the class, the barrel export, and one case 'const': in createErrorInstances.

The expected value is printed with JSON.stringify, not String. For a single value that's worth it: it keeps ">=18.12.0" distinguishable from a bare token, and null, false and 8080 print unambiguously. EnumValidationError uses String because it joins a list, where quoting every item would be noisy — happy to match it instead if you'd rather have them identical.

Tests

Three integration tests in src/__tests__/index.ts (real ajv, then toEqual on the js output — matching the newer tests in that file rather than adding fixtures and snapshots):

the issue's case, with the expected value in the message
non-string constants: 8080, null, false
the cli output contains the value, both in the header and the codeframe pointer

With the case 'const': routing reverted, all three fail with the old "/node: const must be equal to constant", so they're pinning the actual behaviour.

No existing test or snapshot covered const, so nothing else moved.

Checks

vp test 84/84, format:check clean, lint (vp lint + publint) clean.

Note: run on Node 22. On Node 20 the build step (and so lint) fails with Promise.withResolvers is not a function inside vite-plus, which also happens on a clean main — unrelated to this PR.

ajv reports const failures as "must be equal to constant" with the expected value in params.allowedValue, which was dropped. Mirrors the enum error, which already appends its allowed values.

Covers the js and cli formats, and non-string constants.

changeset-bot · 2026-11-04T16:00:05Z

🦋 Changeset detected

Latest commit: 177154d

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

atlassian-cla-bot · 2026-11-04T16:00:06Z

Hooray! All contributors have signed the CLA.

codecov-commenter · 2026-11-05T11:17:05Z

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.41%. Comparing base (eaa5a3c) to head (1472525).
⚠️ Report is 51 commits behind head on main.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #326      +/-   ##
==========================================
+ Coverage   90.78%   98.41%   +7.63%     
==========================================
  Files          12       15       +3     
  Lines         217      316      +99     
  Branches       69       81      +12     
==========================================
+ Hits          197      311     +114     
+ Misses         19        5      -14     
+ Partials        1        0       -1

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

torifat

Thanks for this. The oneOf case in helpers.ts is the main one, the rest is small.

torifat · 2026-11-05T11:25:55Z

            return ret.concat(
              new RequiredValidationError(error as AjvError<RequiredParams>, options)
            );
+          case 'const':


const skips the enum handling in filterRedundantErrors and the merge above, which breaks oneOf unions. With

oneOf: [ { properties: { kind: { const: 'a' }, x: { type: 'number' } } }, { properties: { kind: { const: 'b' }, y: { type: 'string' } } }, ]

and { kind: 'a', x: 'nope' }, we now print /kind must be equal to constant: "b". That tells the user to change the one value that's right. enum: ['b'] there gets filtered out. Two anyOf branches with const: 'a' and const: 'b' also give two errors on /kind instead of one.

Could const be handled as a one-value enum, allowedValues: [params.allowedValue]? That fixes both and adds the "Did you mean" suggestion.

Done , const is now rewritten to { keyword: 'enum', params: { allowedValues: [allowedValue] } } before the tree is built, so it goes through the enum path. Your example now gives /x: type must be number plus the oneOf error, with no /kind error, and the two anyOf branches collapse into one.

torifat · 2026-11-05T11:25:55Z

+
+// The allowed value is printed as JSON so a string is quoted and tells the reader
+// that the schema expects exactly that text.
+const toText = (value: unknown): string => JSON.stringify(value) ?? String(value);


JSON.stringify throws on a circular object or a BigInt, so betterAjvErrors would now throw where it used to return errors. It also prints NaN and Infinity as null. A try/catch falling back to String(value) would cover the throw.

Also, enum's toText uses String, so enum: ['a'] prints a and const: 'a' prints "a". I'd keep them the same.

Resolved by removing the file. The shared enum rendering uses String(), so circular objects, BigInt, NaN and Infinity no longer throw, and const matches enum by construction rather than by agreement.

torifat · 2026-11-05T11:25:55Z

+
+    const output = [
+      styleText('red', styleText('bold', 'CONST') + ' ' + message),
+      styleText('red', `(${toText(allowedValue)})\n`),


A large object constant prints in full here and again in the pointer line. Maybe truncate it past some length?

Nothing is truncated, but nothing long is printed either: String() gives [object Object] for an object and 1,2,3 for an array. The length problem is gone, at the cost of an object constant no longer showing its contents. That matches enum: [someObject] today. If you'd rather keep the detail, I'll add a shared toText on BaseValidationError that stringifies with a try/catch and truncates, used by both.

torifat · 2026-11-05T11:25:55Z

+"better-ajv-errors": minor
+---
+
+Name the expected value in `const` errors. ajv reports a `const` failure as `must be equal to constant` and carries the expected value in `params.allowedValue`, which was dropped because `const` had no handler of its own. A `const` error now reads `/node must be equal to constant: ">=18.12.0"`, with the value printed as JSON so strings stay quoted and `null`, `false` and numbers are unambiguous. The `cli` format gains the value in its header and in the codeframe pointer.


The cli header doesn't change, it's still CONST must be equal to constant. The value goes on the next line and in the pointer.

Reworded to describe the enum rewrite and drop the header claim.

torifat · 2026-11-05T11:25:55Z

    ]);
  });

+  describe('const', () => {


Can you add a oneOf case like the one in helpers.ts, and a circular constant once toText handles it?

Added: a oneOf case asserting no /kind error, the circular constant, and a parity test that const and enum give the same paths and counts for both the oneOf and anyOf shapes.

Dropping ConstValidationError and rewriting the ajv error to an enum with one allowed value means const goes through the enum path instead of around it, so oneOf branches that don't match no longer get reported and sibling branches merge into one error. Also gets the did-you-mean suggestion for free, and drops the JSON.stringify that threw on circular values.

Dhairya-007 · 2026-11-07T15:26:04Z

Thanks, the oneOf point was right and the one-value-enum suggestion turned out to fix all three code comments at once. const is now rewritten to { keyword: 'enum', params: { allowedValues: [allowedValue] } } before the tree is built, so it goes through the existing enum path rather than around it. ConstValidationError and its toText are gone.

Your example now gives:

/x: type must be number
oneOf must match exactly one schema in oneOf

/kind must be equal to constant: "b" is no longer reported, and the two anyOf branches collapse to a single error. Since the enum path is shared, the did-you-mean suggestion comes along too, and the circular/BigInt/NaN problems disappear with JSON.stringify — enum's String-based rendering handles them. There is a test asserting const and enum produce the same paths and counts for both the oneOf and anyOf shapes, plus the circular constant you asked for.

Two things worth your call:

Sibling consts are now filtered like sibling enums. { port: { const: 8080 }, flag: { const: false } } failing on both used to report two errors and now reports one, because filterRedundantErrors drops enum nodes whose siblings also have errors. It matches enum exactly, but it is a visible change from main. Happy to special-case it if you would rather keep both.
const: null renders as an empty value, the same way enum: [null] does today (asserted in the existing allowed values: , 5 test). I left that alone rather than widen this PR, but it looks like a real bug in EnumValidationError.getError(), which uses a raw join() while print() works around it. Glad to fix it separately.

The changeset is reworded — you were right that the cli header never changed.

Dhairya-007 · 2026-11-07T15:26:48Z

One more on your truncation point, which I glossed over above. Nothing is truncated, but nothing long is printed either: the shared enum rendering uses String(), so an object constant comes out as [object Object] and an array as 1,2,3. So the length problem is gone, at the cost of an object constant no longer showing its contents, where the previous JSON.stringify showed them in full.

That is exactly what enum: [someObject] already does today, so it is consistent, but it is a real loss of detail against the version you reviewed. If you would rather keep the detail, the natural place is a shared toText on BaseValidationError that JSON-stringifies with a try/catch and truncates past some length, used by both enum and const. Say the word and I will do that here, otherwise I will leave the behaviour matching enum.

Dhairya-007 · 2026-11-08T06:33:04Z

Hii @torifat , good for re-review now

Dhairya-007 added 3 commits November 4, 2026 21:28

feat: add a const validation error that names the expected value

fa5b7ce

ajv reports const failures as "must be equal to constant" with the expected value in params.allowedValue, which was dropped. Mirrors the enum error, which already appends its allowed values.

feat: route const errors to the new error class

c828153

test: cover const errors naming the expected value

78b1419

Covers the js and cli formats, and non-string constants.

chore: add a changeset

1472525

torifat reviewed Nov 5, 2026

View reviewed changes

Dhairya-007 requested a review from torifat November 7, 2026 15:31

Conversation

Dhairya-007 commented Nov 4, 2026

Before / after

Approach

Tests

Checks

Uh oh!

changeset-bot Bot commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

atlassian-cla-bot Bot commented Nov 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Nov 5, 2026

Codecov Report

Uh oh!

torifat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

torifat Nov 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Dhairya-007 commented Nov 7, 2026

Uh oh!

Dhairya-007 commented Nov 7, 2026

Uh oh!

Dhairya-007 commented Nov 8, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot Bot commented Nov 4, 2026 •

edited

Loading

atlassian-cla-bot Bot commented Nov 4, 2026 •

edited

Loading

torifat Nov 5, 2026 •

edited

Loading