From ce09b5522f18103a4648667cfdb385b6f4fd50dd Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Mon, 23 Mar 2026 01:22:03 +0900
Subject: [PATCH 1/5] Add xsd:decimal runtime and codegen support

Add the branded Decimal runtime type with isDecimal() and
parseDecimal() so exact xsd:decimal values can be validated
without introducing a decimal arithmetic dependency.

Teach the vocabulary code generator to map xsd:decimal to
Decimal, use the shared runtime predicate in generated guards,
and decode typed literals through parseDecimal().

Update the vocabulary manual and changelog to document the new
runtime APIs and the xsd:decimal code generation support.

https://github.com/fedify-dev/fedify/issues/617

Co-Authored-By: OpenAI Codex <codex@openai.com>
---
 CHANGES.md                                    | 15 ++++
 docs/manual/vocab.md                          | 16 ++++
 packages/vocab-runtime/src/decimal.test.ts    | 66 ++++++++++++++++
 packages/vocab-runtime/src/decimal.ts         | 79 +++++++++++++++++++
 packages/vocab-runtime/src/mod.ts             |  1 +
 .../src/__snapshots__/class.test.ts.deno.snap |  5 +-
 .../src/__snapshots__/class.test.ts.node.snap |  5 +-
 .../src/__snapshots__/class.test.ts.snap      |  5 +-
 packages/vocab-tools/src/class.test.ts        | 37 ++++++++-
 packages/vocab-tools/src/class.ts             | 30 ++++---
 packages/vocab-tools/src/type.ts              | 24 ++++++
 11 files changed, 267 insertions(+), 16 deletions(-)
 create mode 100644 packages/vocab-runtime/src/decimal.test.ts
 create mode 100644 packages/vocab-runtime/src/decimal.ts

diff --git a/CHANGES.md b/CHANGES.md
index cd76f0ea7..0164dda33 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -53,6 +53,13 @@ To be released.
 
 ### @fedify/vocab-runtime
 
+ -  Added `Decimal`, a branded string type for exact `xsd:decimal` values,
+    along with `isDecimal()` and `parseDecimal()` for checking and validating
+    XML Schema decimal lexical forms without introducing a decimal arithmetic
+    dependency.  This lays the runtime groundwork for precision-safe
+    marketplace and measurement values such as those needed by [FEP-0837].
+    [[#617], [#640]]
+
  -  Updated the preloaded <https://gotosocial.org/ns> JSON-LD context to
     match the current [GoToSocial] v0.21+ namespace, adding new type terms
     (`LikeRequest`, `LikeAuthorization`, etc.) and property terms
@@ -66,9 +73,12 @@ To be released.
     APIs to distinguish transport failures from specific HTTP fetch failures.
     [[#611]]
 
+[FEP-0837]: https://w3id.org/fep/0837
 [GoToSocial]: https://gotosocial.org/
 [#453]: https://github.com/fedify-dev/fedify/issues/453
+[#617]: https://github.com/fedify-dev/fedify/issues/617
 [#622]: https://github.com/fedify-dev/fedify/pull/622
+[#640]: https://github.com/fedify-dev/fedify/pull/640
 
 ### @fedify/cli
 
@@ -134,6 +144,11 @@ To be released.
 
 ### @fedify/vocab-tools
 
+ -  Added `xsd:decimal` support to the vocabulary code generator.  Properties
+    with that range are now generated as `Decimal` in TypeScript, serialized
+    as `xsd:decimal` JSON-LD literals, and validated through
+    `parseDecimal()` when decoded.  [[#617], [#640]]
+
  -  Added `typeless` field to the type YAML schema.  When set to `true`,
     the generated `toJsonLd()` method does not emit `@type` (or `type` in
     compact form) in the serialized JSON-LD.  This is useful for types
diff --git a/docs/manual/vocab.md b/docs/manual/vocab.md
index dbcae5506..cf6800b4b 100644
--- a/docs/manual/vocab.md
+++ b/docs/manual/vocab.md
@@ -508,6 +508,7 @@ corresponding TypeScript types:
 | `xsd:integer`            | `number`                                                                                                      |
 | `xsd:nonNegativeInteger` | `number`                                                                                                      |
 | `xsd:float`              | `number`                                                                                                      |
+| `xsd:decimal`            | `Decimal`                                                                                                     |
 | `xsd:string`             | `string`                                                                                                      |
 | `xsd:anyURI`             | [`URL`]                                                                                                       |
 | `xsd:dateTime`           | [`Temporal.Instant`]                                                                                          |
@@ -521,6 +522,21 @@ corresponding TypeScript types:
 | Proof purpose            | `"assertionMethod" \| "authentication" \| "capabilityInvocation" \| "capabilityDelegation" \| "keyAgreement"` |
 | Units                    | `"cm" \| "feet" \| "inches" \| "km" \| "m" \| "miles" \| URL`                                                 |
 
+`Decimal` values come from `@fedify/vocab-runtime` as a branded string type.
+Use `parseDecimal()` to validate a string against the `xsd:decimal` lexical
+form before passing it to generated vocabulary APIs:
+
+~~~~ typescript twoslash
+import type { Decimal } from "@fedify/vocab-runtime";
+import { parseDecimal } from "@fedify/vocab-runtime";
+
+const price: Decimal = parseDecimal("12.50");
+~~~~
+
+`Decimal` keeps the original string at runtime instead of converting it to
+JavaScript `number`, which avoids floating-point precision loss for exact
+decimal values such as prices and measurements.
+
 [`Temporal.Instant`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant
 [`Temporal.Duration`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration
 [`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
diff --git a/packages/vocab-runtime/src/decimal.test.ts b/packages/vocab-runtime/src/decimal.test.ts
new file mode 100644
index 000000000..20672d122
--- /dev/null
+++ b/packages/vocab-runtime/src/decimal.test.ts
@@ -0,0 +1,66 @@
+import { deepStrictEqual, throws } from "node:assert";
+import { test } from "node:test";
+import { isDecimal, parseDecimal } from "./decimal.ts";
+import {
+  isDecimal as isDecimalFromModule,
+  parseDecimal as parseDecimalFromModule,
+} from "./mod.ts";
+
+test("parseDecimal() accepts valid xsd:decimal lexical forms", () => {
+  const values = [
+    "-1.23",
+    "12678967.543233",
+    "+100000.00",
+    "210",
+    ".5",
+    "5.",
+    "0",
+    "-0.0",
+  ];
+
+  for (const value of values) {
+    deepStrictEqual(parseDecimal(value), value);
+  }
+});
+
+test("isDecimal() reports valid xsd:decimal lexical forms", () => {
+  deepStrictEqual(isDecimal("12.50"), true);
+  deepStrictEqual(isDecimal(".5"), true);
+  deepStrictEqual(isDecimal("1e3"), false);
+  deepStrictEqual(isDecimal(" 12.50 "), false);
+});
+
+test("parseDecimal() rejects invalid xsd:decimal lexical forms", () => {
+  const values = [
+    "",
+    ".",
+    "+",
+    "-",
+    "1e3",
+    "NaN",
+    "INF",
+    " 1.2 ",
+    "1,2",
+    "1..2",
+  ];
+
+  for (const value of values) {
+    throws(
+      () => parseDecimal(value),
+      {
+        name: "TypeError",
+        message: `${
+          JSON.stringify(value)
+        } is not a valid xsd:decimal lexical form.`,
+      },
+    );
+  }
+});
+
+test("parseDecimal() is exported from the package root", () => {
+  deepStrictEqual(parseDecimalFromModule("12.50"), "12.50");
+});
+
+test("isDecimal() is exported from the package root", () => {
+  deepStrictEqual(isDecimalFromModule("12.50"), true);
+});
diff --git a/packages/vocab-runtime/src/decimal.ts b/packages/vocab-runtime/src/decimal.ts
new file mode 100644
index 000000000..b2a09745d
--- /dev/null
+++ b/packages/vocab-runtime/src/decimal.ts
@@ -0,0 +1,79 @@
+const DECIMAL_PATTERN = /^(\+|-)?([0-9]+(\.[0-9]*)?|\.[0-9]+)$/;
+
+/**
+ * A branded string representing an `xsd:decimal` value.
+ *
+ * Unlike JavaScript's `number`, `xsd:decimal` is intended for exact decimal
+ * values such as prices, quantities, and measurements where binary
+ * floating-point rounding would be inappropriate.  Fedify therefore represents
+ * these values as validated strings at runtime while preserving a distinct
+ * TypeScript type.
+ *
+ * Values of this type must be created through {@link parseDecimal}, which
+ * validates that the string matches the XML Schema `xsd:decimal` lexical form.
+ *
+ * The runtime representation is still a plain string.  The brand exists only
+ * at the type level so APIs can distinguish arbitrary strings from validated
+ * decimal literals without introducing a decimal arithmetic dependency.
+ *
+ * Supported lexical forms include signed and unsigned integers and decimal
+ * fractions such as `"-1.23"`, `"+100000.00"`, `"210"`, `".5"`, and `"5."`.
+ * Scientific notation such as `"1e3"`, special values like `"NaN"`, and
+ * strings with surrounding whitespace are rejected.
+ *
+ * This representation is designed to be forward-compatible with a future
+ * native decimal type if JavaScript eventually gains one, while keeping the
+ * public API semantically precise today.
+ *
+ * @since 2.1.0
+ */
+export type Decimal = string & { readonly __brand: "Decimal" };
+
+/**
+ * Checks whether a string is a valid `xsd:decimal` lexical form.
+ *
+ * This predicate performs the same validation as {@link parseDecimal}
+ * without throwing an exception.  It is useful for generated guards and other
+ * boolean validation paths where callers need to branch instead of handling an
+ * exception.
+ *
+ * @param value A candidate `xsd:decimal` lexical form.
+ * @returns `true` if the string matches the XML Schema `xsd:decimal` lexical
+ *          form, or `false` otherwise.
+ * @since 2.1.0
+ */
+export function isDecimal(value: string): value is Decimal {
+  return DECIMAL_PATTERN.test(value);
+}
+
+/**
+ * Parses a string as an `xsd:decimal` lexical form and returns it as a
+ * branded {@link Decimal}.
+ *
+ * This function validates the input against the XML Schema `xsd:decimal`
+ * lexical space and returns the original string unchanged when it is valid.
+ * It does not trim whitespace, collapse spaces, or canonicalize the decimal
+ * representation.
+ *
+ * @param value A candidate `xsd:decimal` lexical form.
+ * @returns The original string branded as {@link Decimal}.
+ * @throws {TypeError} Thrown when the value is not a valid `xsd:decimal`
+ *                     lexical form.
+ * @example
+ * ```typescript
+ * const price = parseDecimal("12.50");
+ * ```
+ * @example
+ * ```typescript
+ * parseDecimal("1e3"); // throws TypeError
+ * ```
+ * @since 2.1.0
+ */
+export function parseDecimal(value: string): Decimal {
+  if (!isDecimal(value)) {
+    throw new TypeError(
+      `${JSON.stringify(value)} is not a valid xsd:decimal lexical form.`,
+    );
+  }
+  return value as Decimal;
+}
diff --git a/packages/vocab-runtime/src/mod.ts b/packages/vocab-runtime/src/mod.ts
index ef969898f..3b88cd93f 100644
--- a/packages/vocab-runtime/src/mod.ts
+++ b/packages/vocab-runtime/src/mod.ts
@@ -24,6 +24,7 @@ export {
   importPkcs1,
   importSpki,
 } from "./key.ts";
+export { type Decimal, isDecimal, parseDecimal } from "./decimal.ts";
 export { LanguageString } from "./langstr.ts";
 export {
   decodeMultibase,
diff --git a/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap b/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap
index 1703c280e..215d7536b 100644
--- a/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap
+++ b/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap
@@ -8,6 +8,7 @@ import { type Span, SpanStatusCode, type TracerProvider, trace }
     from \\"@opentelemetry/api\\";
 import {
     decodeMultibase,
+    type Decimal,
     type DocumentLoader,
     encodeMultibase,
     exportMultibaseKey,
@@ -15,8 +16,10 @@ import {
     getDocumentLoader,
     importMultibaseKey,
     importPem,
+    isDecimal,
     LanguageString,
-    type RemoteDocument,
+    parseDecimal,
+    type RemoteDocument
 } from \\"@fedify/vocab-runtime\\";
 
 
diff --git a/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap b/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap
index 8d2df61d9..938489913 100644
--- a/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap
+++ b/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap
@@ -6,6 +6,7 @@ import { type Span, SpanStatusCode, type TracerProvider, trace }
     from \\"@opentelemetry/api\\";
 import {
     decodeMultibase,
+    type Decimal,
     type DocumentLoader,
     encodeMultibase,
     exportMultibaseKey,
@@ -13,8 +14,10 @@ import {
     getDocumentLoader,
     importMultibaseKey,
     importPem,
+    isDecimal,
     LanguageString,
-    type RemoteDocument,
+    parseDecimal,
+    type RemoteDocument
 } from \\"@fedify/vocab-runtime\\";
 
 
diff --git a/packages/vocab-tools/src/__snapshots__/class.test.ts.snap b/packages/vocab-tools/src/__snapshots__/class.test.ts.snap
index 51b59dc62..fbf45e414 100644
--- a/packages/vocab-tools/src/__snapshots__/class.test.ts.snap
+++ b/packages/vocab-tools/src/__snapshots__/class.test.ts.snap
@@ -8,6 +8,7 @@ import { type Span, SpanStatusCode, type TracerProvider, trace }
     from "@opentelemetry/api";
 import {
     decodeMultibase,
+    type Decimal,
     type DocumentLoader,
     encodeMultibase,
     exportMultibaseKey,
@@ -15,8 +16,10 @@ import {
     getDocumentLoader,
     importMultibaseKey,
     importPem,
+    isDecimal,
     LanguageString,
-    type RemoteDocument,
+    parseDecimal,
+    type RemoteDocument
 } from "@fedify/vocab-runtime";
 
 
diff --git a/packages/vocab-tools/src/class.test.ts b/packages/vocab-tools/src/class.test.ts
index f58f82dee..d072f0c19 100644
--- a/packages/vocab-tools/src/class.test.ts
+++ b/packages/vocab-tools/src/class.test.ts
@@ -3,7 +3,7 @@ import { basename, dirname, extname, join } from "node:path";
 import { test } from "node:test";
 import metadata from "../deno.json" with { type: "json" };
 import { generateClasses, sortTopologically } from "./class.ts";
-import { loadSchemaFiles } from "./schema.ts";
+import { loadSchemaFiles, type TypeSchema } from "./schema.ts";
 
 test("sortTopologically()", () => {
   const sorted = sortTopologically({
@@ -69,6 +69,16 @@ test("generateClasses() imports the browser-safe jsonld entrypoint", async () =>
   match(entireCode, /import jsonld from "@fedify\/vocab-runtime\/jsonld";/);
 });
 
+test("generateClasses() imports Decimal helpers for xsd:decimal", async () => {
+  const entireCode = await getDecimalFixtureCode();
+  match(entireCode, /isDecimal,/);
+  match(entireCode, /type Decimal,/);
+  match(entireCode, /parseDecimal/);
+  match(entireCode, /amount\?: Decimal \| null;/);
+  match(entireCode, /isDecimal\(values\.amount\)/);
+  match(entireCode, /parseDecimal\(v\["@value"\]\)/);
+});
+
 if ("Deno" in globalThis) {
   const { assertSnapshot } = await import("@std/testing/snapshot");
   Deno.test("generateClasses()", async (t) => {
@@ -101,6 +111,31 @@ async function getEntireCode() {
   return entireCode;
 }
 
+async function getDecimalFixtureCode() {
+  const types: Record<string, TypeSchema> = {
+    "https://example.com/measure": {
+      name: "Measure",
+      uri: "https://example.com/measure",
+      compactName: "Measure",
+      entity: false,
+      description: "A measure.",
+      properties: [
+        {
+          singularName: "amount",
+          functional: true,
+          compactName: "amount",
+          uri: "https://example.com/amount",
+          description: "An exact decimal amount.",
+          range: ["http://www.w3.org/2001/XMLSchema#decimal"],
+        },
+      ],
+      defaultContext:
+        "https://example.com/context" as TypeSchema["defaultContext"],
+    },
+  };
+  return (await Array.fromAsync(generateClasses(types))).join("");
+}
+
 async function changeNodeSnapshotPath() {
   const { snapshot } = await import("node:test");
   snapshot.setResolveSnapshotPath(
diff --git a/packages/vocab-tools/src/class.ts b/packages/vocab-tools/src/class.ts
index 94a3f4de7..f094451e1 100644
--- a/packages/vocab-tools/src/class.ts
+++ b/packages/vocab-tools/src/class.ts
@@ -117,23 +117,29 @@ async function* generateClass(
 export async function* generateClasses(
   types: Record<string, TypeSchema>,
 ): AsyncIterable<string> {
+  const runtimeImports = [
+    "decodeMultibase",
+    "type Decimal",
+    "type DocumentLoader",
+    "encodeMultibase",
+    "exportMultibaseKey",
+    "exportSpki",
+    "getDocumentLoader",
+    "importMultibaseKey",
+    "importPem",
+    "isDecimal",
+    "LanguageString",
+    "parseDecimal",
+    "type RemoteDocument",
+  ];
   yield "// deno-lint-ignore-file ban-unused-ignore prefer-const\n";
   yield 'import jsonld from "@fedify/vocab-runtime/jsonld";\n';
   yield 'import { getLogger } from "@logtape/logtape";\n';
   yield `import { type Span, SpanStatusCode, type TracerProvider, trace }
     from "@opentelemetry/api";\n`;
-  yield `import {
-    decodeMultibase,
-    type DocumentLoader,
-    encodeMultibase,
-    exportMultibaseKey,
-    exportSpki,
-    getDocumentLoader,
-    importMultibaseKey,
-    importPem,
-    LanguageString,
-    type RemoteDocument,
-} from "@fedify/vocab-runtime";\n`;
+  yield `import {\n    ${
+    runtimeImports.join(",\n    ")
+  }\n} from "@fedify/vocab-runtime";\n`;
   yield "\n\n";
   const sorted = sortTopologically(types);
   for (const typeUri of sorted) {
diff --git a/packages/vocab-tools/src/type.ts b/packages/vocab-tools/src/type.ts
index 49b84d20f..7b694c7dc 100644
--- a/packages/vocab-tools/src/type.ts
+++ b/packages/vocab-tools/src/type.ts
@@ -108,6 +108,30 @@ const scalarTypes: Record<string, ScalarType> = {
       return `${v}["@value"]`;
     },
   },
+  "http://www.w3.org/2001/XMLSchema#decimal": {
+    name: "Decimal",
+    typeGuard(v) {
+      return `typeof ${v} === "string" && isDecimal(${v})`;
+    },
+    encoder(v) {
+      return `{
+        "@type": "http://www.w3.org/2001/XMLSchema#decimal",
+        "@value": ${v},
+      }`;
+    },
+    compactEncoder(v) {
+      return v;
+    },
+    dataCheck(v) {
+      return `typeof ${v} === "object" && "@type" in ${v}
+        && ${v}["@type"] === "http://www.w3.org/2001/XMLSchema#decimal"
+        && "@value" in ${v} && typeof ${v}["@value"] === "string"
+        && isDecimal(${v}["@value"])`;
+    },
+    decoder(v) {
+      return `parseDecimal(${v}["@value"])`;
+    },
+  },
   "http://www.w3.org/2001/XMLSchema#string": {
     name: "string",
     typeGuard(v) {

From 9445abae5577aaa23a274a1d096a28351449dfec Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Mon, 23 Mar 2026 01:47:42 +0900
Subject: [PATCH 2/5] Relax generated vocab lint rules

Suppress no-unused-vars and verbatim-module-syntax in generated
vocabulary files so the unconditional Decimal helper imports do not
break linting before any schema actually uses xsd:decimal.

Keep the generated snapshots in sync with the updated file header.

Co-Authored-By: OpenAI Codex <codex@openai.com>
---
 packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap | 2 +-
 packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap | 2 +-
 packages/vocab-tools/src/__snapshots__/class.test.ts.snap      | 2 +-
 packages/vocab-tools/src/class.ts                              | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap b/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap
index 215d7536b..09bbbdee3 100644
--- a/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap
+++ b/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap
@@ -1,7 +1,7 @@
 export const snapshot = {};
 
 snapshot[`generateClasses() 1`] = `
-"// deno-lint-ignore-file ban-unused-ignore prefer-const
+"// deno-lint-ignore-file ban-unused-ignore no-unused-vars prefer-const verbatim-module-syntax
 import jsonld from \\"@fedify/vocab-runtime/jsonld\\";
 import { getLogger } from \\"@logtape/logtape\\";
 import { type Span, SpanStatusCode, type TracerProvider, trace }
diff --git a/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap b/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap
index 938489913..782294ee1 100644
--- a/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap
+++ b/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap
@@ -1,5 +1,5 @@
 exports[`generateClasses() 1`] = `
-"// deno-lint-ignore-file ban-unused-ignore prefer-const
+"// deno-lint-ignore-file ban-unused-ignore no-unused-vars prefer-const verbatim-module-syntax
 import jsonld from \\"@fedify/vocab-runtime/jsonld\\";
 import { getLogger } from \\"@logtape/logtape\\";
 import { type Span, SpanStatusCode, type TracerProvider, trace }
diff --git a/packages/vocab-tools/src/__snapshots__/class.test.ts.snap b/packages/vocab-tools/src/__snapshots__/class.test.ts.snap
index fbf45e414..d7ff14b5f 100644
--- a/packages/vocab-tools/src/__snapshots__/class.test.ts.snap
+++ b/packages/vocab-tools/src/__snapshots__/class.test.ts.snap
@@ -1,7 +1,7 @@
 // Bun Snapshot v1, https://bun.sh/docs/test/snapshots
 
 exports[`generateClasses() 1`] = `
-"// deno-lint-ignore-file ban-unused-ignore prefer-const
+"// deno-lint-ignore-file ban-unused-ignore no-unused-vars prefer-const verbatim-module-syntax
 import jsonld from "@fedify/vocab-runtime/jsonld";
 import { getLogger } from "@logtape/logtape";
 import { type Span, SpanStatusCode, type TracerProvider, trace }
diff --git a/packages/vocab-tools/src/class.ts b/packages/vocab-tools/src/class.ts
index f094451e1..a071d467d 100644
--- a/packages/vocab-tools/src/class.ts
+++ b/packages/vocab-tools/src/class.ts
@@ -132,7 +132,7 @@ export async function* generateClasses(
     "parseDecimal",
     "type RemoteDocument",
   ];
-  yield "// deno-lint-ignore-file ban-unused-ignore prefer-const\n";
+  yield "// deno-lint-ignore-file ban-unused-ignore no-unused-vars prefer-const verbatim-module-syntax\n";
   yield 'import jsonld from "@fedify/vocab-runtime/jsonld";\n';
   yield 'import { getLogger } from "@logtape/logtape";\n';
   yield `import { type Span, SpanStatusCode, type TracerProvider, trace }

From 207f8aa7a1d6596ab741a315264dbf6b15d952b1 Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Mon, 23 Mar 2026 01:52:51 +0900
Subject: [PATCH 3/5] Fix parseDecimal doctest example

Rewrite the throwing parseDecimal() JSDoc example so it catches
the expected TypeError instead of failing when doctests execute
the snippet directly.

Co-Authored-By: OpenAI Codex <codex@openai.com>
---
 packages/vocab-runtime/src/decimal.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/vocab-runtime/src/decimal.ts b/packages/vocab-runtime/src/decimal.ts
index b2a09745d..527b181cf 100644
--- a/packages/vocab-runtime/src/decimal.ts
+++ b/packages/vocab-runtime/src/decimal.ts
@@ -65,7 +65,11 @@ export function isDecimal(value: string): value is Decimal {
  * ```
  * @example
  * ```typescript
- * parseDecimal("1e3"); // throws TypeError
+ * try {
+ *   parseDecimal("1e3");
+ * } catch (error) {
+ *   console.assert(error instanceof TypeError);
+ * }
  * ```
  * @since 2.1.0
  */

From 05d793d4812026b26436879ac849ee0aa38c0764 Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Mon, 23 Mar 2026 02:14:53 +0900
Subject: [PATCH 4/5] Handle xsd:decimal whitespace normalization

Add canParseDecimal() alongside the strict isDecimal() guard so
xsd:decimal parsing can follow XML Schema whitespace normalization
without weakening the Decimal type guard.

Update parseDecimal() to normalize XML Schema whitespace before
validation, adjust generated decimal data checks to use
canParseDecimal(), and refresh the related tests and documentation.

https://github.com/fedify-dev/fedify/pull/640#discussion_r2971750477

Co-Authored-By: OpenAI Codex <codex@openai.com>
---
 CHANGES.md                                    | 15 +++---
 docs/manual/vocab.md                          | 24 +++++++--
 packages/vocab-runtime/src/decimal.test.ts    | 28 +++++++++-
 packages/vocab-runtime/src/decimal.ts         | 53 ++++++++++++++-----
 packages/vocab-runtime/src/mod.ts             |  7 ++-
 .../src/__snapshots__/class.test.ts.deno.snap |  1 +
 .../src/__snapshots__/class.test.ts.node.snap |  1 +
 .../src/__snapshots__/class.test.ts.snap      |  1 +
 packages/vocab-tools/src/class.test.ts        | 34 ++++++++++++
 packages/vocab-tools/src/class.ts             |  1 +
 packages/vocab-tools/src/type.ts              |  2 +-
 11 files changed, 140 insertions(+), 27 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 0164dda33..bb19a711a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -54,11 +54,13 @@ To be released.
 ### @fedify/vocab-runtime
 
  -  Added `Decimal`, a branded string type for exact `xsd:decimal` values,
-    along with `isDecimal()` and `parseDecimal()` for checking and validating
-    XML Schema decimal lexical forms without introducing a decimal arithmetic
-    dependency.  This lays the runtime groundwork for precision-safe
-    marketplace and measurement values such as those needed by [FEP-0837].
-    [[#617], [#640]]
+    along with `isDecimal()`, `canParseDecimal()`, and `parseDecimal()` for
+    checking and validating XML Schema decimal lexical forms without
+    introducing a decimal arithmetic dependency.  `isDecimal()` performs a
+    strict lexical-form check, while `canParseDecimal()` and `parseDecimal()`
+    apply XML Schema whitespace normalization first.  This lays the runtime
+    groundwork for precision-safe marketplace and measurement values such as
+    those needed by [FEP-0837].  [[#617], [#640]]
 
  -  Updated the preloaded <https://gotosocial.org/ns> JSON-LD context to
     match the current [GoToSocial] v0.21+ namespace, adding new type terms
@@ -146,7 +148,8 @@ To be released.
 
  -  Added `xsd:decimal` support to the vocabulary code generator.  Properties
     with that range are now generated as `Decimal` in TypeScript, serialized
-    as `xsd:decimal` JSON-LD literals, and validated through
+    as `xsd:decimal` JSON-LD literals, validated through
+    `canParseDecimal()` when checking input data, and normalized through
     `parseDecimal()` when decoded.  [[#617], [#640]]
 
  -  Added `typeless` field to the type YAML schema.  When set to `true`,
diff --git a/docs/manual/vocab.md b/docs/manual/vocab.md
index cf6800b4b..b88f12cf0 100644
--- a/docs/manual/vocab.md
+++ b/docs/manual/vocab.md
@@ -523,19 +523,33 @@ corresponding TypeScript types:
 | Units                    | `"cm" \| "feet" \| "inches" \| "km" \| "m" \| "miles" \| URL`                                                 |
 
 `Decimal` values come from `@fedify/vocab-runtime` as a branded string type.
-Use `parseDecimal()` to validate a string against the `xsd:decimal` lexical
-form before passing it to generated vocabulary APIs:
+Use `isDecimal()` when you need to check whether a string is already in the
+normalized `xsd:decimal` lexical form, and use `canParseDecimal()` or
+`parseDecimal()` when you need XML Schema whitespace normalization before
+validation:
 
 ~~~~ typescript twoslash
 import type { Decimal } from "@fedify/vocab-runtime";
-import { parseDecimal } from "@fedify/vocab-runtime";
+import {
+  canParseDecimal,
+  isDecimal,
+  parseDecimal,
+} from "@fedify/vocab-runtime";
 
-const price: Decimal = parseDecimal("12.50");
+const raw = " 12.50 ";
+
+isDecimal(raw); // false
+canParseDecimal(raw); // true
+
+const price: Decimal = parseDecimal(raw);
+price; // "12.50"
 ~~~~
 
 `Decimal` keeps the original string at runtime instead of converting it to
 JavaScript `number`, which avoids floating-point precision loss for exact
-decimal values such as prices and measurements.
+decimal values such as prices and measurements.  `parseDecimal()` normalizes
+XML Schema whitespace before returning the branded value, so the runtime
+representation always uses the normalized lexical form.
 
 [`Temporal.Instant`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant
 [`Temporal.Duration`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration
diff --git a/packages/vocab-runtime/src/decimal.test.ts b/packages/vocab-runtime/src/decimal.test.ts
index 20672d122..93bd04029 100644
--- a/packages/vocab-runtime/src/decimal.test.ts
+++ b/packages/vocab-runtime/src/decimal.test.ts
@@ -1,7 +1,8 @@
 import { deepStrictEqual, throws } from "node:assert";
 import { test } from "node:test";
-import { isDecimal, parseDecimal } from "./decimal.ts";
+import { canParseDecimal, isDecimal, parseDecimal } from "./decimal.ts";
 import {
+  canParseDecimal as canParseDecimalFromModule,
   isDecimal as isDecimalFromModule,
   parseDecimal as parseDecimalFromModule,
 } from "./mod.ts";
@@ -28,6 +29,24 @@ test("isDecimal() reports valid xsd:decimal lexical forms", () => {
   deepStrictEqual(isDecimal(".5"), true);
   deepStrictEqual(isDecimal("1e3"), false);
   deepStrictEqual(isDecimal(" 12.50 "), false);
+  deepStrictEqual(isDecimal("\t12.50\n"), false);
+});
+
+test("canParseDecimal() accepts whitespace-normalized xsd:decimal strings", () => {
+  deepStrictEqual(canParseDecimal("12.50"), true);
+  deepStrictEqual(canParseDecimal(" 12.50 "), true);
+  deepStrictEqual(canParseDecimal("\t+100000.00\r\n"), true);
+  deepStrictEqual(canParseDecimal("  .5  "), true);
+  deepStrictEqual(canParseDecimal("1e3"), false);
+  deepStrictEqual(canParseDecimal("1 2.50"), false);
+  deepStrictEqual(canParseDecimal("1\t2.50"), false);
+});
+
+test("parseDecimal() normalizes XML Schema whitespace", () => {
+  deepStrictEqual(parseDecimal("12.50"), "12.50");
+  deepStrictEqual(parseDecimal(" 12.50 "), "12.50");
+  deepStrictEqual(parseDecimal("\t+100000.00\r\n"), "+100000.00");
+  deepStrictEqual(parseDecimal("  .5  "), ".5");
 });
 
 test("parseDecimal() rejects invalid xsd:decimal lexical forms", () => {
@@ -39,9 +58,10 @@ test("parseDecimal() rejects invalid xsd:decimal lexical forms", () => {
     "1e3",
     "NaN",
     "INF",
-    " 1.2 ",
     "1,2",
     "1..2",
+    "1 2.3",
+    "1\t2.3",
   ];
 
   for (const value of values) {
@@ -61,6 +81,10 @@ test("parseDecimal() is exported from the package root", () => {
   deepStrictEqual(parseDecimalFromModule("12.50"), "12.50");
 });
 
+test("canParseDecimal() is exported from the package root", () => {
+  deepStrictEqual(canParseDecimalFromModule(" 12.50 "), true);
+});
+
 test("isDecimal() is exported from the package root", () => {
   deepStrictEqual(isDecimalFromModule("12.50"), true);
 });
diff --git a/packages/vocab-runtime/src/decimal.ts b/packages/vocab-runtime/src/decimal.ts
index 527b181cf..5eb11a6cd 100644
--- a/packages/vocab-runtime/src/decimal.ts
+++ b/packages/vocab-runtime/src/decimal.ts
@@ -1,4 +1,9 @@
 const DECIMAL_PATTERN = /^(\+|-)?([0-9]+(\.[0-9]*)?|\.[0-9]+)$/;
+const XML_SCHEMA_WHITESPACE_PATTERN = /[\t\n\r ]+/g;
+
+function collapseXmlSchemaWhitespace(value: string): string {
+  return value.replace(XML_SCHEMA_WHITESPACE_PATTERN, " ").trim();
+}
 
 /**
  * A branded string representing an `xsd:decimal` value.
@@ -18,8 +23,10 @@ const DECIMAL_PATTERN = /^(\+|-)?([0-9]+(\.[0-9]*)?|\.[0-9]+)$/;
  *
  * Supported lexical forms include signed and unsigned integers and decimal
  * fractions such as `"-1.23"`, `"+100000.00"`, `"210"`, `".5"`, and `"5."`.
- * Scientific notation such as `"1e3"`, special values like `"NaN"`, and
- * strings with surrounding whitespace are rejected.
+ * Scientific notation such as `"1e3"` and special values like `"NaN"` are
+ * rejected.  Strings with surrounding XML Schema whitespace can be normalized
+ * by {@link parseDecimal}, but values of this type are always stored in their
+ * normalized lexical form.
  *
  * This representation is designed to be forward-compatible with a future
  * native decimal type if JavaScript eventually gains one, while keeping the
@@ -32,10 +39,9 @@ export type Decimal = string & { readonly __brand: "Decimal" };
 /**
  * Checks whether a string is a valid `xsd:decimal` lexical form.
  *
- * This predicate performs the same validation as {@link parseDecimal}
- * without throwing an exception.  It is useful for generated guards and other
- * boolean validation paths where callers need to branch instead of handling an
- * exception.
+ * This predicate checks the lexical form strictly, without applying XML Schema
+ * whitespace normalization first.  It is useful as a type guard for values
+ * that are already expected to be normalized decimal strings.
  *
  * @param value A candidate `xsd:decimal` lexical form.
  * @returns `true` if the string matches the XML Schema `xsd:decimal` lexical
@@ -46,17 +52,34 @@ export function isDecimal(value: string): value is Decimal {
   return DECIMAL_PATTERN.test(value);
 }
 
+/**
+ * Checks whether a string can be parsed as an `xsd:decimal` lexical form.
+ *
+ * Unlike {@link isDecimal}, this predicate first applies the XML Schema
+ * `whiteSpace="collapse"` normalization step and then validates the
+ * normalized string.  This means values like `" 12.50 "` are parseable even
+ * though they are not already normalized decimal literals.
+ *
+ * @param value A candidate `xsd:decimal` lexical form.
+ * @returns `true` if the normalized string matches the XML Schema
+ *          `xsd:decimal` lexical form, or `false` otherwise.
+ * @since 2.1.0
+ */
+export function canParseDecimal(value: string): boolean {
+  return isDecimal(collapseXmlSchemaWhitespace(value));
+}
+
 /**
  * Parses a string as an `xsd:decimal` lexical form and returns it as a
  * branded {@link Decimal}.
  *
  * This function validates the input against the XML Schema `xsd:decimal`
- * lexical space and returns the original string unchanged when it is valid.
- * It does not trim whitespace, collapse spaces, or canonicalize the decimal
- * representation.
+ * lexical space after applying the XML Schema `whiteSpace="collapse"`
+ * normalization step.  It returns the normalized string without any further
+ * canonicalization.
  *
  * @param value A candidate `xsd:decimal` lexical form.
- * @returns The original string branded as {@link Decimal}.
+ * @returns The normalized string branded as {@link Decimal}.
  * @throws {TypeError} Thrown when the value is not a valid `xsd:decimal`
  *                     lexical form.
  * @example
@@ -65,6 +88,11 @@ export function isDecimal(value: string): value is Decimal {
  * ```
  * @example
  * ```typescript
+ * const price = parseDecimal(" 12.50 ");
+ * console.assert(price === "12.50");
+ * ```
+ * @example
+ * ```typescript
  * try {
  *   parseDecimal("1e3");
  * } catch (error) {
@@ -74,10 +102,11 @@ export function isDecimal(value: string): value is Decimal {
  * @since 2.1.0
  */
 export function parseDecimal(value: string): Decimal {
-  if (!isDecimal(value)) {
+  const normalized = collapseXmlSchemaWhitespace(value);
+  if (!isDecimal(normalized)) {
     throw new TypeError(
       `${JSON.stringify(value)} is not a valid xsd:decimal lexical form.`,
     );
   }
-  return value as Decimal;
+  return normalized as Decimal;
 }
diff --git a/packages/vocab-runtime/src/mod.ts b/packages/vocab-runtime/src/mod.ts
index 3b88cd93f..1a6bda9e7 100644
--- a/packages/vocab-runtime/src/mod.ts
+++ b/packages/vocab-runtime/src/mod.ts
@@ -24,7 +24,12 @@ export {
   importPkcs1,
   importSpki,
 } from "./key.ts";
-export { type Decimal, isDecimal, parseDecimal } from "./decimal.ts";
+export {
+  canParseDecimal,
+  type Decimal,
+  isDecimal,
+  parseDecimal,
+} from "./decimal.ts";
 export { LanguageString } from "./langstr.ts";
 export {
   decodeMultibase,
diff --git a/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap b/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap
index 09bbbdee3..f4edcf682 100644
--- a/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap
+++ b/packages/vocab-tools/src/__snapshots__/class.test.ts.deno.snap
@@ -7,6 +7,7 @@ import { getLogger } from \\"@logtape/logtape\\";
 import { type Span, SpanStatusCode, type TracerProvider, trace }
     from \\"@opentelemetry/api\\";
 import {
+    canParseDecimal,
     decodeMultibase,
     type Decimal,
     type DocumentLoader,
diff --git a/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap b/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap
index 782294ee1..4d3583af9 100644
--- a/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap
+++ b/packages/vocab-tools/src/__snapshots__/class.test.ts.node.snap
@@ -5,6 +5,7 @@ import { getLogger } from \\"@logtape/logtape\\";
 import { type Span, SpanStatusCode, type TracerProvider, trace }
     from \\"@opentelemetry/api\\";
 import {
+    canParseDecimal,
     decodeMultibase,
     type Decimal,
     type DocumentLoader,
diff --git a/packages/vocab-tools/src/__snapshots__/class.test.ts.snap b/packages/vocab-tools/src/__snapshots__/class.test.ts.snap
index d7ff14b5f..e65a687f7 100644
--- a/packages/vocab-tools/src/__snapshots__/class.test.ts.snap
+++ b/packages/vocab-tools/src/__snapshots__/class.test.ts.snap
@@ -7,6 +7,7 @@ import { getLogger } from "@logtape/logtape";
 import { type Span, SpanStatusCode, type TracerProvider, trace }
     from "@opentelemetry/api";
 import {
+    canParseDecimal,
     decodeMultibase,
     type Decimal,
     type DocumentLoader,
diff --git a/packages/vocab-tools/src/class.test.ts b/packages/vocab-tools/src/class.test.ts
index d072f0c19..1a5aa0a1e 100644
--- a/packages/vocab-tools/src/class.test.ts
+++ b/packages/vocab-tools/src/class.test.ts
@@ -71,6 +71,7 @@ test("generateClasses() imports the browser-safe jsonld entrypoint", async () =>
 
 test("generateClasses() imports Decimal helpers for xsd:decimal", async () => {
   const entireCode = await getDecimalFixtureCode();
+  match(entireCode, /canParseDecimal,/);
   match(entireCode, /isDecimal,/);
   match(entireCode, /type Decimal,/);
   match(entireCode, /parseDecimal/);
@@ -79,6 +80,11 @@ test("generateClasses() imports Decimal helpers for xsd:decimal", async () => {
   match(entireCode, /parseDecimal\(v\["@value"\]\)/);
 });
 
+test("generateClasses() uses canParseDecimal() in xsd:decimal data checks", async () => {
+  const entireCode = await getDecimalUnionFixtureCode();
+  match(entireCode, /canParseDecimal\(v\["@value"\]\)/);
+});
+
 if ("Deno" in globalThis) {
   const { assertSnapshot } = await import("@std/testing/snapshot");
   Deno.test("generateClasses()", async (t) => {
@@ -136,6 +142,34 @@ async function getDecimalFixtureCode() {
   return (await Array.fromAsync(generateClasses(types))).join("");
 }
 
+async function getDecimalUnionFixtureCode() {
+  const types: Record<string, TypeSchema> = {
+    "https://example.com/measure": {
+      name: "Measure",
+      uri: "https://example.com/measure",
+      compactName: "Measure",
+      entity: false,
+      description: "A measure.",
+      properties: [
+        {
+          singularName: "amount",
+          functional: true,
+          compactName: "amount",
+          uri: "https://example.com/amount",
+          description: "An exact decimal amount.",
+          range: [
+            "http://www.w3.org/2001/XMLSchema#decimal",
+            "http://www.w3.org/2001/XMLSchema#string",
+          ],
+        },
+      ],
+      defaultContext:
+        "https://example.com/context" as TypeSchema["defaultContext"],
+    },
+  };
+  return (await Array.fromAsync(generateClasses(types))).join("");
+}
+
 async function changeNodeSnapshotPath() {
   const { snapshot } = await import("node:test");
   snapshot.setResolveSnapshotPath(
diff --git a/packages/vocab-tools/src/class.ts b/packages/vocab-tools/src/class.ts
index a071d467d..6c79cc7e5 100644
--- a/packages/vocab-tools/src/class.ts
+++ b/packages/vocab-tools/src/class.ts
@@ -118,6 +118,7 @@ export async function* generateClasses(
   types: Record<string, TypeSchema>,
 ): AsyncIterable<string> {
   const runtimeImports = [
+    "canParseDecimal",
     "decodeMultibase",
     "type Decimal",
     "type DocumentLoader",
diff --git a/packages/vocab-tools/src/type.ts b/packages/vocab-tools/src/type.ts
index 7b694c7dc..99f1bb6bc 100644
--- a/packages/vocab-tools/src/type.ts
+++ b/packages/vocab-tools/src/type.ts
@@ -126,7 +126,7 @@ const scalarTypes: Record<string, ScalarType> = {
       return `typeof ${v} === "object" && "@type" in ${v}
         && ${v}["@type"] === "http://www.w3.org/2001/XMLSchema#decimal"
         && "@value" in ${v} && typeof ${v}["@value"] === "string"
-        && isDecimal(${v}["@value"])`;
+        && canParseDecimal(${v}["@value"])`;
     },
     decoder(v) {
       return `parseDecimal(${v}["@value"])`;

From af8de5a4d596e481ee960941e9bfff913a8c46c1 Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Mon, 23 Mar 2026 02:45:02 +0900
Subject: [PATCH 5/5] Reject ambiguous decimal/string unions

Reject property ranges that mix xsd:string and xsd:decimal during
code generation, since both map to runtime strings and the generated
encoder cannot disambiguate them reliably.

Update the vocab-tools tests to cover the rejection path directly,
and document the restriction in the manual and changelog.

https://github.com/fedify-dev/fedify/pull/640#discussion_r2971801567

Co-Authored-By: OpenAI Codex <codex@openai.com>
---
 CHANGES.md                             |  4 +-
 docs/manual/vocab.md                   |  5 ++
 packages/vocab-tools/src/class.test.ts | 71 ++++++++++++++------------
 packages/vocab-tools/src/class.ts      |  3 +-
 packages/vocab-tools/src/schema.ts     | 32 ++++++++++++
 5 files changed, 81 insertions(+), 34 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index bb19a711a..eabc514ea 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -150,7 +150,9 @@ To be released.
     with that range are now generated as `Decimal` in TypeScript, serialized
     as `xsd:decimal` JSON-LD literals, validated through
     `canParseDecimal()` when checking input data, and normalized through
-    `parseDecimal()` when decoded.  [[#617], [#640]]
+    `parseDecimal()` when decoded.  Code generation now also rejects property
+    ranges that mix `xsd:string` and `xsd:decimal`, since both map to runtime
+    strings and would make serialization ambiguous.  [[#617], [#640]]
 
  -  Added `typeless` field to the type YAML schema.  When set to `true`,
     the generated `toJsonLd()` method does not emit `@type` (or `type` in
diff --git a/docs/manual/vocab.md b/docs/manual/vocab.md
index b88f12cf0..a92a38c1f 100644
--- a/docs/manual/vocab.md
+++ b/docs/manual/vocab.md
@@ -551,6 +551,11 @@ decimal values such as prices and measurements.  `parseDecimal()` normalizes
 XML Schema whitespace before returning the branded value, so the runtime
 representation always uses the normalized lexical form.
 
+A property range must not combine `xsd:string` and `xsd:decimal`.  Both map to
+runtime strings, so the generated encoder cannot distinguish them reliably
+during JSON-LD serialization and Fedify rejects such schema definitions at code
+generation time.
+
 [`Temporal.Instant`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Instant
 [`Temporal.Duration`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration
 [`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
diff --git a/packages/vocab-tools/src/class.test.ts b/packages/vocab-tools/src/class.test.ts
index 1a5aa0a1e..4c743a883 100644
--- a/packages/vocab-tools/src/class.test.ts
+++ b/packages/vocab-tools/src/class.test.ts
@@ -1,8 +1,9 @@
-import { deepStrictEqual, match } from "node:assert";
+import { deepStrictEqual, match, rejects } from "node:assert";
 import { basename, dirname, extname, join } from "node:path";
 import { test } from "node:test";
 import metadata from "../deno.json" with { type: "json" };
 import { generateClasses, sortTopologically } from "./class.ts";
+import { getDataCheck } from "./type.ts";
 import { loadSchemaFiles, type TypeSchema } from "./schema.ts";
 
 test("sortTopologically()", () => {
@@ -80,9 +81,43 @@ test("generateClasses() imports Decimal helpers for xsd:decimal", async () => {
   match(entireCode, /parseDecimal\(v\["@value"\]\)/);
 });
 
-test("generateClasses() uses canParseDecimal() in xsd:decimal data checks", async () => {
-  const entireCode = await getDecimalUnionFixtureCode();
-  match(entireCode, /canParseDecimal\(v\["@value"\]\)/);
+test("getDataCheck() uses canParseDecimal() for xsd:decimal", () => {
+  const check = getDataCheck(
+    "http://www.w3.org/2001/XMLSchema#decimal",
+    {},
+    "v",
+  );
+  match(check, /canParseDecimal\(v\["@value"\]\)/);
+});
+
+test("generateClasses() rejects xsd:string and xsd:decimal unions", async () => {
+  await rejects(
+    Array.fromAsync(generateClasses({
+      "https://example.com/measure": {
+        name: "Measure",
+        uri: "https://example.com/measure",
+        compactName: "Measure",
+        entity: false,
+        description: "A measure.",
+        properties: [
+          {
+            singularName: "amount",
+            functional: true,
+            compactName: "amount",
+            uri: "https://example.com/amount",
+            description: "An exact decimal amount.",
+            range: [
+              "http://www.w3.org/2001/XMLSchema#decimal",
+              "http://www.w3.org/2001/XMLSchema#string",
+            ],
+          },
+        ],
+        defaultContext:
+          "https://example.com/context" as TypeSchema["defaultContext"],
+      },
+    })),
+    /cannot have both xsd:string and xsd:decimal in its range/,
+  );
 });
 
 if ("Deno" in globalThis) {
@@ -142,34 +177,6 @@ async function getDecimalFixtureCode() {
   return (await Array.fromAsync(generateClasses(types))).join("");
 }
 
-async function getDecimalUnionFixtureCode() {
-  const types: Record<string, TypeSchema> = {
-    "https://example.com/measure": {
-      name: "Measure",
-      uri: "https://example.com/measure",
-      compactName: "Measure",
-      entity: false,
-      description: "A measure.",
-      properties: [
-        {
-          singularName: "amount",
-          functional: true,
-          compactName: "amount",
-          uri: "https://example.com/amount",
-          description: "An exact decimal amount.",
-          range: [
-            "http://www.w3.org/2001/XMLSchema#decimal",
-            "http://www.w3.org/2001/XMLSchema#string",
-          ],
-        },
-      ],
-      defaultContext:
-        "https://example.com/context" as TypeSchema["defaultContext"],
-    },
-  };
-  return (await Array.fromAsync(generateClasses(types))).join("");
-}
-
 async function changeNodeSnapshotPath() {
   const { snapshot } = await import("node:test");
   snapshot.setResolveSnapshotPath(
diff --git a/packages/vocab-tools/src/class.ts b/packages/vocab-tools/src/class.ts
index 6c79cc7e5..87f7fd2ba 100644
--- a/packages/vocab-tools/src/class.ts
+++ b/packages/vocab-tools/src/class.ts
@@ -3,7 +3,7 @@ import { generateCloner, generateConstructor } from "./constructor.ts";
 import { generateFields } from "./field.ts";
 import { generateInspector, generateInspectorPostClass } from "./inspector.ts";
 import { generateProperties } from "./property.ts";
-import type { TypeSchema } from "./schema.ts";
+import { type TypeSchema, validateTypeSchemas } from "./schema.ts";
 import { emitOverride } from "./type.ts";
 
 /**
@@ -117,6 +117,7 @@ async function* generateClass(
 export async function* generateClasses(
   types: Record<string, TypeSchema>,
 ): AsyncIterable<string> {
+  validateTypeSchemas(types);
   const runtimeImports = [
     "canParseDecimal",
     "decodeMultibase",
diff --git a/packages/vocab-tools/src/schema.ts b/packages/vocab-tools/src/schema.ts
index 769ae95cc..4e08d9204 100644
--- a/packages/vocab-tools/src/schema.ts
+++ b/packages/vocab-tools/src/schema.ts
@@ -240,6 +240,38 @@ export function hasSingularAccessor(property: PropertySchema): boolean {
     property.singularAccessor === true;
 }
 
+const XSD_STRING_URI = "http://www.w3.org/2001/XMLSchema#string";
+const XSD_DECIMAL_URI = "http://www.w3.org/2001/XMLSchema#decimal";
+
+/**
+ * Validates schema combinations that cannot be represented safely by the
+ * generated code.
+ *
+ * In particular, `xsd:string` and `xsd:decimal` cannot coexist in the same
+ * property range because both are represented as runtime strings, which makes
+ * JSON-LD serialization ambiguous and order-dependent.
+ *
+ * @param types The loaded type schemas to validate.
+ * @throws {TypeError} Thrown when an unsupported range combination is found.
+ */
+export function validateTypeSchemas(
+  types: Record<string, TypeSchema>,
+): void {
+  for (const type of Object.values(types)) {
+    for (const property of type.properties) {
+      const hasString = property.range.includes(XSD_STRING_URI);
+      const hasDecimal = property.range.includes(XSD_DECIMAL_URI);
+      if (hasString && hasDecimal) {
+        throw new TypeError(
+          `The property ${type.name}.${property.singularName} cannot have ` +
+            `both xsd:string and xsd:decimal in its range because the ` +
+            `generated encoder cannot disambiguate them at runtime.`,
+        );
+      }
+    }
+  }
+}
+
 /**
  * An error that occurred while loading a schema file.
  */