`v.multipleOf` does not handle some non-integer inputs well

[esdmr]

It seems that v.multipleOf tries to find the remainder of the input divided by the requirement. This might not yield an appropriate result if their division has floating point precision errors:

const Length = v.pipe(v.number(), v.multipleOf(0.01), v.description('in meters, with centimeter precision'));

toJsonSchema(Length) // {"type": "number", "multipleOf": 0.01, "description": ...}

v.parse(Length, 3); // Invalid multiple: Expected %0.01 but received 3

[fabian-hiller]

Hey, thank you for reaching out! What would you recommend us to change?

[esdmr]

Different libraries seem to be handling this case differently

Test case for different libraries

{
  "private": true,
  "type": "module",
  "dependencies": {
    "ajv": "^8.17.1",
    "arktype": "^2.1.29",
    "joi": "^18.0.2",
    "typebox": "^1.0.69",
    "valibot": "^1.2.0",
    "zod": "^4.2.1"
  },
  "devDependencies": {
    "@types/node": "22"
  }
}

import assert from "node:assert/strict";
import { describe, it } from "node:test";
import * as ajv from "ajv";
import * as arktype from "arktype";
import * as joi from "joi";
import * as typeboxType from "typebox";
import * as typeboxCompile from "typebox/compile";
import * as typeboxValue from "typebox/value";
import * as valibot from "valibot";
import * as zod from "zod";
import * as zodV3 from "zod/v3";
import * as zodMini from "zod/mini";

describe("valibot", () => {
  it("handles multipleOf(0.1) correctly", () => {
    const schema = valibot.pipe(valibot.number(), valibot.multipleOf(0.1));
    assert.ok(valibot.safeParse(schema, 3).typed);
    assert.ok(valibot.safeParse(schema, 3.3).typed);
    assert.ok(!valibot.safeParse(schema, 3.03).typed);
  });
});

describe("zod", () => {
  describe('v4', () => {
    it("handles multipleOf(0.1) correctly", () => {
      const schema = zod.number().multipleOf(0.1);
      assert.ok(zod.safeParse(schema, 3).success);
      assert.ok(zod.safeParse(schema, 3.3).success);
      assert.ok(!zod.safeParse(schema, 3.03).success);
    });
  });

  describe("v3", () => {
    it("handles multipleOf(0.1) correctly", () => {
      const schema = zodV3.number().multipleOf(0.1);
      assert.ok(schema.safeParse(3).success);
      assert.ok(schema.safeParse(3.3).success);
      assert.ok(!schema.safeParse(3.03).success);
    });
  });

  describe("mini", () => {
    it("handles multipleOf(0.1) correctly", () => {
      const schema = zodMini.number().check(zodMini.multipleOf(0.1));
      assert.ok(zodMini.safeParse(schema, 3).success);
      assert.ok(zodMini.safeParse(schema, 3.3).success);
      assert.ok(!zodMini.safeParse(schema, 3.03).success);
    });
  });
});

describe("ajv", () => {
  it('handles "multipleOf": 0.1 correctly (no multipleOfPrecision)', () => {
    const schema = { type: "number", multipleOf: 0.1 };
    assert.ok(new ajv.Ajv().validate(schema, 3));
    assert.ok(new ajv.Ajv().validate(schema, 3.3));
    assert.ok(!new ajv.Ajv().validate(schema, 3.03));
  });

  it('handles "multipleOf": 0.1 correctly (multipleOfPrecision = 1)', () => {
    const schema = { type: "number", multipleOf: 0.1 };
    assert.ok(new ajv.Ajv({ multipleOfPrecision: 1 }).validate(schema, 3));
    assert.ok(new ajv.Ajv({ multipleOfPrecision: 1 }).validate(schema, 3.3));
    assert.ok(!new ajv.Ajv({ multipleOfPrecision: 1 }).validate(schema, 3.03));
  });

  it('handles "multipleOf": 0.1 correctly (multipleOfPrecision = 2)', () => {
    const schema = { type: "number", multipleOf: 0.1 };
    assert.ok(new ajv.Ajv({ multipleOfPrecision: 2 }).validate(schema, 3));
    assert.ok(new ajv.Ajv({ multipleOfPrecision: 2 }).validate(schema, 3.3));
    assert.ok(!new ajv.Ajv({ multipleOfPrecision: 2 }).validate(schema, 3.03));
  });
});

describe("arktype", () => {
  it("handles % 0.1 correctly", () => {
    const schema = arktype.type("number % 0.1");
    assert.equal(schema(3), 3);
    assert.equal(schema(3.3), 3.3);
    assert.notEqual(schema(3.03), 3.03);
  });
});

describe("joi", () => {
  it("handles multiple(0.1) correctly", () => {
    const schema = joi.number().multiple(0.1);
    assert.equal(schema.validate(3).error, undefined);
    assert.equal(schema.validate(3.3).error, undefined);
    assert.notEqual(schema.validate(3.03).error, undefined);
  });

  it("handles precision(1) correctly", () => {
    const schema = joi.number().precision(1);
    assert.equal(schema.validate(3).error, undefined);
    assert.equal(schema.validate(3.3).error, undefined);
    assert.notEqual(schema.validate(3.03).error, undefined);
  });
});

describe("typebox", () => {
  describe("Value", () => {
    it("handles multipleOf: 0.1 correctly", () => {
      const schema = typeboxType.Number({ multipleOf: 0.1 });
      assert.ok(typeboxValue.Check(schema, 3));
      assert.ok(typeboxValue.Check(schema, 3.3));
      assert.ok(!typeboxValue.Check(schema, 3.03));
    });
  });

  describe("Compile", () => {
    it("handles multipleOf: 0.1 correctly", () => {
      const schema = typeboxCompile.Compile(
        typeboxType.Number({ multipleOf: 0.1 })
      );
      assert.ok(schema.Check(3));
      assert.ok(schema.Check(3.3));
      assert.ok(!schema.Check(3.03));
    });
  });
});

(Alphabetical order)

library name	options	ok	description
ajv	multipleOfPrecision = 0	❌	parseInt after /
ajv	multipleOfPrecision > 0	⚠️	(requires enough precision) checks error after /
arktype	-	❌	does not parse non-integer modulus
joi	using multiple	✔️	shifts decimals to integer prior to %
joi	using precision	⚠️	coerces, not validates, into the correct precision
typebox	-	✔️	checks error after %
valibot	-	❌	uses % only
zod	-	✔️	shifts decimals to integer prior to %

• ajv's issue: multipleOf precision ajv-validator/ajv#84
• arktype's issue: Allow non-integer divisors arktypeio/arktype#1002
• joi's issues: Updated multiple rule to support decimal/float base hapijs/joi#2666 and Multiple doesn't work correct hapijs/joi#2962
• typebox's issue: JS floating point precision bug causes multipleOf validation to fail sinclairzx81/typebox#754

Shifting decimals to integer prior to %: joi's implementation, jsonschema's implementation, zod's implementation

Checking error after //%: ajv's implementation, typebox's implementation

Alternatively, if you wish not to implement decimal multipleOf, may I suggest a warning in the docs (and maybe a runtime error)?

[fabian-hiller]

Thank you for your great research! What's your recommendation? Cast it to an integer or return an issue?

Hint: Users can already check for integers with v.integer() when placed in the pipe before v.multipleOf(…).

[sillvva]

Here is a float-safe modulo function. It handles decimal and negative numbers correctly, whereas the % operator in JS does not.

function mod(a: number, n: number): number {
  const result = a - n * Math.floor(a / n);
  
  const getDecimalPlaces = (num: number): number => {
    const str = num.toString();
    const decimalIndex = str.indexOf('.');
    return decimalIndex === -1 ? 0 : Math.min(str.length - decimalIndex - 1, 10);
  };
  
  const precision = Math.max(getDecimalPlaces(a), getDecimalPlaces(n));
  const multiplier = Math.pow(10, precision);
  
  return Math.round(result * multiplier) / multiplier;
}

This

[mod(3,0.4), 3 % 0.4]
[mod(3,0.2), 3 % 0.2]
[mod(-5,3), -5 % 3]
[mod(-6,3), -6 % 3]

Results in this:

[0.2, 0.19999999999999984] // ✅ fixes floating point
[0, 0.19999999999999984] // ✅ correct value, 3 is a multiple of 0.2
[1, -2] // ✅ Remainders should never be negative
[0, -0] // ✅ Remainders should never be negative