@fedify/vocab-tools 2.5.0-dev.2289 → 2.5.0-dev.2304

package/README.md

@@ -64,3 +64,43 @@ of trusting a matching origin.  Locally constructed values, previously fetched
 values, and the explicit `crossOrigin: "trust"` option retain their usual
 behavior.  This does not verify id-less embedded objects or establish publishing
 authority.
+
+
+Redundant properties
+--------------------
+
+Both functional and non-functional property schemas can declare synonyms in
+`redundantProperties`.  On reading, the canonical property takes precedence,
+followed by synonyms in declaration order.  The first non-empty raw value set
+is decoded in full, preserving its order and multiplicity.  Values from other
+synonyms are never merged, even when the selected values fail range validation.
+List and graph containers are decoded only after choosing the property.
+
+`redundantPropertiesWrite` defaults to `all`, which writes the canonical
+property and every synonym with the same complete container representation.
+Set it to `canonical` to write only the canonical property while still accepting
+synonyms on reading:
+
+~~~~ yaml
+- singularName: license
+  pluralName: licenses
+  uri: "https://example.com/license"
+  description: The licenses of the object.
+  range:
+    - "http://www.w3.org/2001/XMLSchema#anyURI"
+  redundantProperties:
+    - uri: "https://schema.org/license"
+    - uri: "http://creativecommons.org/ns#license"
+  redundantPropertiesWrite: canonical
+~~~~
+
+A synonym's `compactName` is optional.  Without it, serialization uses the
+JSON-LD processor to select a context term or retain the full URI.  For IRI
+values, context terms must declare `"@type": "@id"`; container terms must
+carry the appropriate `@container`.  Writable container synonyms also use the
+processor to preserve their representation.  Explicit caller contexts take
+precedence over the default context.
+
+As with other properties, an object parsed with `fromJsonLd()` retains its
+original JSON-LD document for default serialization.  Pass `format: "compact"`
+or `format: "expand"` to serialize its decoded values under the write policy.

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-tools",
-  "version": "2.5.0-dev.2289+111f0945",
+  "version": "2.5.0-dev.2304+3a599380",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts"

package/dist/mod.cjs

@@ -8,7 +8,7 @@ let yaml = require("yaml");
 let es_toolkit = require("es-toolkit");
 //#region deno.json
 var name = "@fedify/vocab-tools";
-var version = "2.5.0-dev.2289+111f0945";
+var version = "2.5.0-dev.2304+3a599380";
 //#endregion
 //#region src/type.ts
 const HEURISTICS_CONTEXTS = [
@@ -844,12 +844,15 @@ async function* generateEncoder(typeUri, types) {
           ? compactItems
           : compactItems[0];
         `;
-				if (property.functional && property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
+				if (property.redundantPropertiesWrite !== "canonical" && property.redundantProperties != null && !(isNonFunctionalProperty(property) && property.container != null)) for (const prop of property.redundantProperties) {
+					if (prop.compactName == null) continue;
+					yield `
             result[${JSON.stringify(prop.compactName)}]
               = compactItems.length > 1
               ? compactItems
               : compactItems[0];
             `;
+				}
 			} else yield `
         result[${JSON.stringify(property.compactName)}] = compactItems;
         `;
@@ -916,7 +919,7 @@ async function* generateEncoder(typeUri, types) {
       );
       values[${JSON.stringify(property.uri)}] = propValue;
     `;
-		if (property.functional && property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
+		if (property.redundantPropertiesWrite !== "canonical" && property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
         values[${JSON.stringify(prop.uri)}] = propValue;
         `;
 		yield `
@@ -988,7 +991,7 @@ async function* generateEncoder(typeUri, types) {
 
   protected ${emitOverride$1(typeUri, types)} isCompactable(): boolean {
 `;
-	for (const property of type.properties) if (property.extraContext != null || !property.range.every((r) => isCompactableType(r, types))) yield `
+	for (const property of type.properties) if (property.extraContext != null || property.redundantPropertiesWrite !== "canonical" && property.redundantProperties != null && property.redundantProperties.length > 0 && (property.redundantProperties.some((p) => p.compactName == null) || isNonFunctionalProperty(property) && property.container != null) || !property.range.every((r) => isCompactableType(r, types))) yield `
       if (
         this.${await getFieldName(property.uri)} != null &&
         this.${await getFieldName(property.uri)}.length > 0
@@ -1167,7 +1170,7 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
 		yield `
     let ${arrayVariable} = ${property.uri === "https://w3id.org/fep/ef61/gateways" ? "getPortableActorGateways(values) as typeof values[string]" : `values[${JSON.stringify(property.uri)}]`};
     `;
-		if (property.functional && property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
+		if (property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
         if (${arrayVariable} == null || ${arrayVariable}.length < 1) {
           ${arrayVariable} = values[${JSON.stringify(prop.uri)}];
         }

package/dist/mod.d.cts

@@ -68,6 +68,22 @@ interface TypeSchema {
   defaultContext: Context;
 }
 interface PropertySchemaBase {
+  /**
+  * Synonyms read after the canonical property, in declaration order.
+  * Deserialization selects the first non-empty raw value set before decoding
+  * its values and containers; it never merges synonyms or retries invalid
+  * values.  Serialization writes all synonyms by default.
+  */
+  redundantProperties?: {
+    /** The qualified URI of the synonym. */uri: string; /** The synonym's key in the default compact JSON-LD context. */
+    compactName?: string;
+  }[];
+  /**
+  * Whether serialization writes every synonym or only the canonical property.
+  * Defaults to `"all"`.  This does not change deserialization precedence or
+  * the existing cache of parsed JSON-LD documents.
+  */
+  redundantPropertiesWrite?: "all" | "canonical";
   /**
   * A context URL added to the default serialization context when this
   * property's expanded IRI appears in the compacted document.  Explicit
@@ -193,23 +209,6 @@ type PropertySchema = PropertySchemaBase & PropertySchemaTyping & {
   * and `singularAccessor` should not be specified.
   */
   functional: true;
-  /**
-  * If it's present, those redundant properties are also filled with
-  * the same value altogether when the object is serialized into
-  * JSON-LD.  When it's deserialized from JSON-LD, it tries to
-  * parse the values of the specified properties in order.
-  */
-  redundantProperties?: {
-    /**
-    * The qualified URI of the property.
-    */
-    uri: string;
-    /**
-    * The property name used in the compacted JSON-LD document.  It is used
-    * as the key of the property.
-    */
-    compactName?: string;
-  }[];
 };
 /**
 * A JSON-LD context, which is placed in the `@context` property of a JSON-LD

package/dist/mod.d.ts

@@ -68,6 +68,22 @@ interface TypeSchema {
   defaultContext: Context;
 }
 interface PropertySchemaBase {
+  /**
+  * Synonyms read after the canonical property, in declaration order.
+  * Deserialization selects the first non-empty raw value set before decoding
+  * its values and containers; it never merges synonyms or retries invalid
+  * values.  Serialization writes all synonyms by default.
+  */
+  redundantProperties?: {
+    /** The qualified URI of the synonym. */uri: string; /** The synonym's key in the default compact JSON-LD context. */
+    compactName?: string;
+  }[];
+  /**
+  * Whether serialization writes every synonym or only the canonical property.
+  * Defaults to `"all"`.  This does not change deserialization precedence or
+  * the existing cache of parsed JSON-LD documents.
+  */
+  redundantPropertiesWrite?: "all" | "canonical";
   /**
   * A context URL added to the default serialization context when this
   * property's expanded IRI appears in the compacted document.  Explicit
@@ -193,23 +209,6 @@ type PropertySchema = PropertySchemaBase & PropertySchemaTyping & {
   * and `singularAccessor` should not be specified.
   */
   functional: true;
-  /**
-  * If it's present, those redundant properties are also filled with
-  * the same value altogether when the object is serialized into
-  * JSON-LD.  When it's deserialized from JSON-LD, it tries to
-  * parse the values of the specified properties in order.
-  */
-  redundantProperties?: {
-    /**
-    * The qualified URI of the property.
-    */
-    uri: string;
-    /**
-    * The property name used in the compacted JSON-LD document.  It is used
-    * as the key of the property.
-    */
-    compactName?: string;
-  }[];
 };
 /**
 * A JSON-LD context, which is placed in the `@context` property of a JSON-LD

package/dist/mod.js

@@ -7,7 +7,7 @@ import { parse } from "yaml";
 import { pascalCase } from "es-toolkit";
 //#region deno.json
 var name = "@fedify/vocab-tools";
-var version = "2.5.0-dev.2289+111f0945";
+var version = "2.5.0-dev.2304+3a599380";
 //#endregion
 //#region src/type.ts
 const HEURISTICS_CONTEXTS = [
@@ -843,12 +843,15 @@ async function* generateEncoder(typeUri, types) {
           ? compactItems
           : compactItems[0];
         `;
-				if (property.functional && property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
+				if (property.redundantPropertiesWrite !== "canonical" && property.redundantProperties != null && !(isNonFunctionalProperty(property) && property.container != null)) for (const prop of property.redundantProperties) {
+					if (prop.compactName == null) continue;
+					yield `
             result[${JSON.stringify(prop.compactName)}]
               = compactItems.length > 1
               ? compactItems
               : compactItems[0];
             `;
+				}
 			} else yield `
         result[${JSON.stringify(property.compactName)}] = compactItems;
         `;
@@ -915,7 +918,7 @@ async function* generateEncoder(typeUri, types) {
       );
       values[${JSON.stringify(property.uri)}] = propValue;
     `;
-		if (property.functional && property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
+		if (property.redundantPropertiesWrite !== "canonical" && property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
         values[${JSON.stringify(prop.uri)}] = propValue;
         `;
 		yield `
@@ -987,7 +990,7 @@ async function* generateEncoder(typeUri, types) {
 
   protected ${emitOverride$1(typeUri, types)} isCompactable(): boolean {
 `;
-	for (const property of type.properties) if (property.extraContext != null || !property.range.every((r) => isCompactableType(r, types))) yield `
+	for (const property of type.properties) if (property.extraContext != null || property.redundantPropertiesWrite !== "canonical" && property.redundantProperties != null && property.redundantProperties.length > 0 && (property.redundantProperties.some((p) => p.compactName == null) || isNonFunctionalProperty(property) && property.container != null) || !property.range.every((r) => isCompactableType(r, types))) yield `
       if (
         this.${await getFieldName(property.uri)} != null &&
         this.${await getFieldName(property.uri)}.length > 0
@@ -1166,7 +1169,7 @@ async function* generateDecoder(typeUri, types, moduleVarNames) {
 		yield `
     let ${arrayVariable} = ${property.uri === "https://w3id.org/fep/ef61/gateways" ? "getPortableActorGateways(values) as typeof values[string]" : `values[${JSON.stringify(property.uri)}]`};
     `;
-		if (property.functional && property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
+		if (property.redundantProperties != null) for (const prop of property.redundantProperties) yield `
         if (${arrayVariable} == null || ${arrayVariable}.length < 1) {
           ${arrayVariable} = values[${JSON.stringify(prop.uri)}];
         }

package/dist/schema.yaml

@@ -45,33 +45,41 @@ $defs:
           functional:
             description: *functional-description
             const: true
-          redundantProperties::
-            description: >-
-              If it's present, those redundant properties are also filled with
-              the same value altogether when the object is serialized into
-              JSON-LD.  When it's deserialized from JSON-LD, it tries to
-              parse the values of the specified properties in order.
-            type: array
-            items:
-              type: object
-              properties:
-                uri:
-                  description: The qualified URI of the property.
-                  type: string
-                  format: uri
-                compactName:
-                  description: >-
-                    The property name used in the compacted JSON-LD document.
-                    It is used as the key of the property.
-                  type: string
-              required:
-              - uri
         required:
         - functional
 
   property-base:
     type: object
     properties:
+      redundantProperties:
+        description: >-
+          Synonyms read after the canonical property in declaration order.
+          The first non-empty raw value set is selected before decoding values
+          and containers. Synonyms are never merged or retried on invalid values.
+          Serialization writes all synonyms by default.
+        type: array
+        items:
+          type: object
+          properties:
+            uri:
+              description: The qualified URI of the property.
+              type: string
+              format: uri
+            compactName:
+              description: >-
+                The property name used in the compacted JSON-LD document.
+                It is used as the key of the property.
+              type: string
+          required:
+          - uri
+      redundantPropertiesWrite:
+        description: >-
+          Whether serialization writes all synonyms or only the canonical
+          property. Does not change deserialization precedence.
+        enum:
+        - all
+        - canonical
+        default: all
       extraContext:
         description: >-
           A context URL added to default serialization when this property's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-tools",
-  "version": "2.5.0-dev.2289+111f0945",
+  "version": "2.5.0-dev.2304+3a599380",
   "description": "Code generator for Activity Vocabulary APIs",
   "homepage": "https://fedify.dev/",
   "repository": {
@@ -46,9 +46,12 @@
   },
   "license": "MIT",
   "devDependencies": {
+    "@logtape/logtape": "^2.2.0",
+    "@opentelemetry/api": "^1.9.1",
     "@types/node": "^24.12.2",
     "tsdown": "^0.22.0",
-    "typescript": "^6.0.0"
+    "typescript": "^6.0.0",
+    "@fedify/vocab-runtime": "^2.5.0-dev.2304+3a599380"
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",

package/src/codec.test.ts

@@ -0,0 +1,409 @@
+import { deepStrictEqual, match, ok, rejects } from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { pathToFileURL } from "node:url";
+import { generateClasses } from "./class.ts";
+import type { PropertySchema, TypeSchema } from "./schema.ts";
+
+const NS = "https://example.com/";
+const AS = "https://www.w3.org/ns/activitystreams";
+const CONTEXT = `${NS}context`;
+const XSD = "http://www.w3.org/2001/XMLSchema#";
+const context = {
+  type: "@type",
+  id: "@id",
+  Fixture: `${NS}Fixture`,
+  Value: `${NS}Value`,
+  label: `${NS}label`,
+  value: `${NS}value`,
+  first: `${NS}first`,
+  second: `${NS}second`,
+};
+
+interface Instance {
+  values: unknown[];
+  value: unknown;
+  toJsonLd(options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+interface FixtureClass {
+  new (values?: Record<string, unknown>): Instance;
+  fromJsonLd(
+    document: unknown,
+    options?: Record<string, unknown>,
+  ): Promise<Instance>;
+}
+
+async function withFixture(
+  options: Partial<PropertySchema>,
+  run: (
+    Fixture: FixtureClass,
+    loader: (url: string) => Promise<unknown>,
+    source: string,
+  ) => Promise<void>,
+) {
+  const property = {
+    singularName: "value",
+    pluralName: "values",
+    uri: `${NS}value`,
+    compactName: "value",
+    description: "A value.",
+    range: [`${XSD}string`],
+    redundantProperties: [
+      { uri: `${NS}first`, compactName: "first" },
+      { uri: `${NS}second`, compactName: "second" },
+    ],
+    ...options,
+  } as PropertySchema;
+  const terms: Record<string, unknown> = { ...context };
+  for (const name of ["value", "first", "second"]) {
+    const term: Record<string, unknown> = { "@id": `${NS}${name}` };
+    if (property.range[0] === `${XSD}anyURI`) term["@type"] = "@id";
+    if ("container" in property && property.container != null) {
+      term["@container"] = `@${property.container}`;
+    }
+    terms[name] = term;
+  }
+  const loader = (url: string) => {
+    if (url !== AS && url !== CONTEXT) {
+      throw new Error(`Unexpected context: ${url}`);
+    }
+    return Promise.resolve({
+      contextUrl: null,
+      documentUrl: url,
+      document: {
+        "@context": url === AS ? { type: "@type", id: "@id" } : terms,
+      },
+    });
+  };
+  const types: Record<string, TypeSchema> = {
+    [`${NS}Fixture`]: {
+      name: "Fixture",
+      uri: `${NS}Fixture`,
+      compactName: "Fixture",
+      entity: false,
+      description: "A fixture.",
+      defaultContext: [AS, CONTEXT] as unknown as TypeSchema["defaultContext"],
+      properties: [property],
+    },
+    [`${NS}Value`]: {
+      name: "Value",
+      uri: `${NS}Value`,
+      compactName: "Value",
+      entity: false,
+      description: "An embedded value.",
+      defaultContext: [AS, CONTEXT] as unknown as TypeSchema["defaultContext"],
+      properties: [{
+        singularName: "label",
+        functional: true,
+        uri: `${NS}label`,
+        compactName: "label",
+        description: "A label.",
+        range: [`${XSD}string`],
+      }],
+    },
+  };
+  const source = (await Array.fromAsync(generateClasses(types))).join("");
+  const resolved = source.replace(
+    /from\s+"([^"]+)"/g,
+    (_, specifier: string) =>
+      `from ${JSON.stringify(import.meta.resolve(specifier))}`,
+  );
+  const dir = await mkdtemp(join(tmpdir(), "fedify-codec-"));
+  try {
+    const file = join(dir, "fixture.mts");
+    await writeFile(file, resolved);
+    const { Fixture } = await import(pathToFileURL(file).href);
+    await run(Fixture, loader, source);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+const literal = (value: unknown) => ({ "@value": value });
+const document = (properties: Record<string, unknown>) => ({
+  "@type": [`${NS}Fixture`],
+  ...properties,
+});
+
+test("redundant properties select the first non-empty entire set", async () => {
+  await withFixture({}, async (Fixture, contextLoader) => {
+    for (
+      const [properties, expected] of [
+        [{ [`${NS}first`]: [literal("a"), literal("b"), literal("a")] }, [
+          "a",
+          "b",
+          "a",
+        ]],
+        [{ [`${NS}value`]: [], [`${NS}first`]: [literal("a")] }, ["a"]],
+        [{ [`${NS}first`]: [], [`${NS}second`]: [literal("b")] }, ["b"]],
+        [{ [`${NS}value`]: [literal("c")], [`${NS}first`]: [literal("a")] }, [
+          "c",
+        ]],
+        [{ [`${NS}first`]: [literal("a")], [`${NS}second`]: [literal("b")] }, [
+          "a",
+        ]],
+        [{}, []],
+      ] as const
+    ) {
+      const parsed = await Fixture.fromJsonLd(document(properties), {
+        contextLoader,
+      });
+      deepStrictEqual(parsed.values, expected);
+    }
+    const parsed = await Fixture.fromJsonLd({
+      "@context": termsForRead(),
+      type: "Fixture",
+      alternate: ["a", "b", "a"],
+    }, { contextLoader });
+    deepStrictEqual(parsed.values, ["a", "b", "a"]);
+  });
+});
+
+function termsForRead() {
+  return { ...context, alternate: `${NS}first` };
+}
+
+test("redundant properties do not retry invalid canonical values", async () => {
+  await withFixture({
+    range: [
+      `${XSD}string`,
+      "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString",
+    ],
+  }, async (Fixture, contextLoader) => {
+    const parsed = await Fixture.fromJsonLd(
+      document({
+        [`${NS}value`]: [literal(42)],
+        [`${NS}first`]: [literal("fallback")],
+      }),
+      { contextLoader },
+    );
+    deepStrictEqual(parsed.values, []);
+  });
+  await withFixture(
+    { range: ["fedify:url"] },
+    async (Fixture, contextLoader) => {
+      const parsed = await Fixture.fromJsonLd(
+        document({
+          [`${NS}value`]: [literal("http://[")],
+          [`${NS}first`]: [literal("https://example.com/fallback")],
+        }),
+        { contextLoader },
+      );
+      deepStrictEqual(parsed.values, []);
+    },
+  );
+  await withFixture(
+    { range: [`${XSD}anyURI`] },
+    async (Fixture, contextLoader) => {
+      await rejects(Fixture.fromJsonLd(
+        document({
+          [`${NS}value`]: [{ "@id": "http://[" }],
+          [`${NS}first`]: [{ "@id": "https://example.com/fallback" }],
+        }),
+        { contextLoader },
+      ));
+    },
+  );
+});
+
+for (const policy of [undefined, "all", "canonical"] as const) {
+  test(`redundant properties write policy ${policy ?? "default"}`, async () => {
+    await withFixture(
+      { redundantPropertiesWrite: policy },
+      async (Fixture, contextLoader) => {
+        for (const values of [[], ["a"], ["a", "b", "a"]]) {
+          const instance = new Fixture({ values });
+          const compact = await instance.toJsonLd({
+            format: "compact",
+            contextLoader,
+          });
+          deepStrictEqual(await instance.toJsonLd({ contextLoader }), compact);
+          const expanded = await instance.toJsonLd({
+            format: "expand",
+            contextLoader,
+          }) as unknown as Record<string, unknown>[];
+          for (const alias of ["first", "second"]) {
+            if (policy === "canonical" || values.length === 0) {
+              ok(!(alias in compact));
+              ok(!(`${NS}${alias}` in expanded[0]));
+            } else {
+              deepStrictEqual(compact[alias], compact.value);
+              deepStrictEqual(
+                expanded[0][`${NS}${alias}`],
+                expanded[0][`${NS}value`],
+              );
+            }
+          }
+          const custom = await instance.toJsonLd({
+            format: "compact",
+            contextLoader,
+            context: { ...context, renamed: `${NS}value` },
+          });
+          deepStrictEqual(
+            (await Fixture.fromJsonLd(custom, { contextLoader })).values,
+            values,
+          );
+        }
+        const aliasOnly = await Fixture.fromJsonLd(
+          document({ [`${NS}first`]: [literal("read")] }),
+          { contextLoader },
+        );
+        deepStrictEqual(aliasOnly.values, ["read"]);
+      },
+    );
+  });
+}
+
+for (const container of ["list", "graph"] as const) {
+  for (const policy of ["all", "canonical"] as const) {
+    test(`redundant ${container} containers with ${policy} writes`, async () => {
+      await withFixture({
+        container,
+        redundantPropertiesWrite: policy,
+        range: container === "graph" ? [`${NS}Value`] : [`${XSD}string`],
+      }, async (Fixture, contextLoader) => {
+        const items = container === "list"
+          ? [literal("a"), literal("b"), literal("a")]
+          : [
+            { "@type": [`${NS}Value`], [`${NS}label`]: [literal("a")] },
+            { "@type": [`${NS}Value`], [`${NS}label`]: [literal("b")] },
+          ];
+        const set = container === "list"
+          ? [{ "@list": items }]
+          : items.map((item) => ({ "@graph": [item] }));
+        const parsed = await Fixture.fromJsonLd(
+          document({
+            [`${NS}first`]: set,
+            [`${NS}second`]: [{ "@list": [literal("other")] }],
+          }),
+          { contextLoader },
+        );
+        deepStrictEqual(
+          container === "list"
+            ? parsed.values
+            : parsed.values.map((v) => (v as { label: string }).label),
+          container === "list" ? ["a", "b", "a"] : ["a", "b"],
+        );
+        const instance = new Fixture({ values: parsed.values });
+        const compact = await instance.toJsonLd({
+          format: "compact",
+          contextLoader,
+        });
+        if (container === "list" || policy === "all") {
+          deepStrictEqual(await instance.toJsonLd({ contextLoader }), compact);
+        } else {
+          // Parsed children retain expanded caches in the heuristic path.
+          const defaultOutput = await instance.toJsonLd({ contextLoader });
+          const decoded = await Fixture.fromJsonLd(defaultOutput, {
+            contextLoader,
+          });
+          deepStrictEqual(
+            decoded.values.map((v) => (v as { label: string }).label),
+            ["a", "b"],
+          );
+        }
+        const expanded = await instance.toJsonLd({
+          format: "expand",
+          contextLoader,
+        }) as unknown as Record<string, unknown>[];
+        for (const alias of ["first", "second"]) {
+          if (policy === "canonical") {
+            ok(!(`${NS}${alias}` in expanded[0]));
+            ok(!(alias in compact));
+          } else {
+            deepStrictEqual(
+              expanded[0][`${NS}${alias}`],
+              expanded[0][`${NS}value`],
+            );
+            deepStrictEqual(compact[alias], compact.value);
+          }
+        }
+        const roundtrip = await Fixture.fromJsonLd(compact, { contextLoader });
+        deepStrictEqual(
+          container === "list"
+            ? roundtrip.values
+            : roundtrip.values.map((v) => (v as { label: string }).label),
+          container === "list" ? ["a", "b", "a"] : ["a", "b"],
+        );
+        const empty = await Fixture.fromJsonLd(
+          document({
+            [`${NS}value`]: [{ [`@${container}`]: [] }],
+            [`${NS}first`]: set,
+          }),
+          { contextLoader },
+        );
+        deepStrictEqual(empty.values, []);
+      });
+    });
+  }
+}
+
+for (const functional of [false, true]) {
+  test(`URI-only aliases and portable read keys (functional=${functional})`, async () => {
+    for (const policy of ["all", "canonical"] as const) {
+      await withFixture({
+        ...(functional ? { functional: true } : {}),
+        range: [`${XSD}anyURI`],
+        redundantPropertiesWrite: policy,
+        redundantProperties: [{ uri: `${NS}first` }],
+      }, async (Fixture, contextLoader, source) => {
+        ok(!source.includes("result[undefined]"));
+        match(source, /PORTABLE_IRI_KEYS[^\n]+https:\/\/example.com\/first/);
+        const url = new URL("https://example.com/object");
+        const instance = new Fixture(
+          functional ? { value: url } : { values: [url] },
+        );
+        const compact = await instance.toJsonLd({
+          format: "compact",
+          contextLoader,
+        });
+        deepStrictEqual(await instance.toJsonLd({ contextLoader }), compact);
+        const expanded = await instance.toJsonLd({
+          format: "expand",
+          contextLoader,
+        }) as unknown as Record<string, unknown>[];
+        if (policy === "all") {
+          deepStrictEqual(expanded[0][`${NS}first`], [{ "@id": url.href }]);
+        } else ok(!(`${NS}first` in expanded[0]));
+        const custom = await instance.toJsonLd({
+          format: "compact",
+          contextLoader,
+          context: {
+            type: "@type",
+            Fixture: `${NS}Fixture`,
+            value: { "@id": `${NS}value`, "@type": "@id" },
+          },
+        });
+        if (policy === "all") {
+          deepStrictEqual(custom[`${NS}first`], { "@id": url.href });
+        } else {
+          ok(!(`${NS}first` in custom));
+        }
+        const parsed = await Fixture.fromJsonLd(
+          document({
+            [`${NS}first`]: [{ "@id": "ap://did:key:z6Mkabc/objects/1" }],
+          }),
+          { contextLoader },
+        );
+        const value = functional ? parsed.value : parsed.values[0];
+        ok(value instanceof URL);
+        const cached = await parsed.toJsonLd({ contextLoader });
+        deepStrictEqual(cached[`${NS}first`], [{
+          "@id": "ap+ef61://did:key:z6Mkabc/objects/1",
+        }]);
+        const compactInput = await Fixture.fromJsonLd({
+          "@context": [AS, CONTEXT],
+          type: "Fixture",
+          first: "ap://did:key:z6Mkabc/objects/1",
+        }, { contextLoader });
+        const compactCache = await compactInput.toJsonLd({ contextLoader });
+        deepStrictEqual(
+          compactCache.first,
+          "ap+ef61://did:key:z6Mkabc/objects/1",
+        );
+      });
+    }
+  });
+}

package/src/codec.ts

@@ -162,8 +162,13 @@ export async function* generateEncoder(
           ? compactItems
           : compactItems[0];
         `;
-        if (property.functional && property.redundantProperties != null) {
+        if (
+          property.redundantPropertiesWrite !== "canonical" &&
+          property.redundantProperties != null &&
+          !(isNonFunctionalProperty(property) && property.container != null)
+        ) {
           for (const prop of property.redundantProperties) {
+            if (prop.compactName == null) continue;
             yield `
             result[${JSON.stringify(prop.compactName)}]
               = compactItems.length > 1
@@ -255,7 +260,10 @@ export async function* generateEncoder(
       );
       values[${JSON.stringify(property.uri)}] = propValue;
     `;
-    if (property.functional && property.redundantProperties != null) {
+    if (
+      property.redundantPropertiesWrite !== "canonical" &&
+      property.redundantProperties != null
+    ) {
       for (const prop of property.redundantProperties) {
         yield `
         values[${JSON.stringify(prop.uri)}] = propValue;
@@ -348,6 +356,11 @@ export async function* generateEncoder(
   for (const property of type.properties) {
     if (
       property.extraContext != null ||
+      (property.redundantPropertiesWrite !== "canonical" &&
+        property.redundantProperties != null &&
+        property.redundantProperties.length > 0 &&
+        (property.redundantProperties.some((p) => p.compactName == null) ||
+          (isNonFunctionalProperty(property) && property.container != null))) ||
       !property.range.every((r) => isCompactableType(r, types))
     ) {
       yield `
@@ -544,7 +557,7 @@ export async function* generateDecoder(
     yield `
     let ${arrayVariable} = ${propertyValues};
     `;
-    if (property.functional && property.redundantProperties != null) {
+    if (property.redundantProperties != null) {
       for (const prop of property.redundantProperties) {
         yield `
         if (${arrayVariable} == null || ${arrayVariable}.length < 1) {

package/src/schema.test.ts

@@ -1,8 +1,13 @@
-import { deepStrictEqual, ok, throws } from "node:assert";
+import { deepStrictEqual, ok, rejects, throws } from "node:assert";
 import { test } from "node:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stringify } from "yaml";
 import {
   hasSingularAccessor,
   isNonFunctionalProperty,
+  loadSchemaFiles,
   type PropertySchema,
   type TypeSchema,
   type TypeUri,
@@ -244,3 +249,71 @@ test("validateTypeSchemas() rejects mixed fedify:vocabEntityType ranges", () =>
     },
   );
 });
+
+test("loadSchemaFiles validates redundant properties on both property kinds", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "fedify-schema-"));
+  try {
+    for (const functional of [false, true]) {
+      const property = {
+        singularName: "value",
+        ...(functional ? { functional: true } : { pluralName: "values" }),
+        uri: "https://example.com/value",
+        description: "A value.",
+        range: ["http://www.w3.org/2001/XMLSchema#string"],
+        redundantProperties: [{ uri: "https://example.com/alias" }],
+      };
+      const type = {
+        name: "Fixture",
+        uri: "https://example.com/Fixture",
+        entity: false,
+        description: "A fixture.",
+        defaultContext: {},
+        properties: [property],
+      };
+      for (const policy of [undefined, "all", "canonical"]) {
+        await writeFile(
+          join(dir, "fixture.yaml"),
+          stringify({
+            ...type,
+            properties: [{ ...property, redundantPropertiesWrite: policy }],
+          }),
+        );
+        const types = await loadSchemaFiles(dir);
+        deepStrictEqual(
+          types[type.uri].properties[0].redundantProperties,
+          property.redundantProperties,
+        );
+        deepStrictEqual(
+          types[type.uri].properties[0].redundantPropertiesWrite,
+          policy,
+        );
+      }
+      for (
+        const invalid of [
+          { redundantPropertiesWrite: "merge" },
+          { redundantPropertiesWrite: 42 },
+          { redundantProperties: "alias" },
+          { redundantProperties: [{}] },
+          { redundantProperties: [{ uri: 42 }] },
+          {
+            redundantProperties: [{
+              uri: "https://example.com/alias",
+              compactName: 42,
+            }],
+          },
+        ]
+      ) {
+        await writeFile(
+          join(dir, "fixture.yaml"),
+          stringify({
+            ...type,
+            properties: [{ ...property, ...invalid }],
+          }),
+        );
+        await rejects(loadSchemaFiles(dir), AggregateError);
+      }
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/schema.ts

@@ -85,6 +85,27 @@ export interface TypeSchema {
 }
 
 export interface PropertySchemaBase {
+  /**
+   * Synonyms read after the canonical property, in declaration order.
+   * Deserialization selects the first non-empty raw value set before decoding
+   * its values and containers; it never merges synonyms or retries invalid
+   * values.  Serialization writes all synonyms by default.
+   */
+  redundantProperties?: {
+    /** The qualified URI of the synonym. */
+    uri: string;
+
+    /** The synonym's key in the default compact JSON-LD context. */
+    compactName?: string;
+  }[];
+
+  /**
+   * Whether serialization writes every synonym or only the canonical property.
+   * Defaults to `"all"`.  This does not change deserialization precedence or
+   * the existing cache of parsed JSON-LD documents.
+   */
+  redundantPropertiesWrite?: "all" | "canonical";
+
   /**
    * A context URL added to the default serialization context when this
    * property's expanded IRI appears in the compacted document.  Explicit
@@ -229,25 +250,6 @@ export type PropertySchema =
      * and `singularAccessor` should not be specified.
      */
     functional: true;
-
-    /**
-     * If it's present, those redundant properties are also filled with
-     * the same value altogether when the object is serialized into
-     * JSON-LD.  When it's deserialized from JSON-LD, it tries to
-     * parse the values of the specified properties in order.
-     */
-    redundantProperties?: {
-      /**
-       * The qualified URI of the property.
-       */
-      uri: string;
-
-      /**
-       * The property name used in the compacted JSON-LD document.  It is used
-       * as the key of the property.
-       */
-      compactName?: string;
-    }[];
   };
 
 /**

package/src/schema.yaml

@@ -45,33 +45,41 @@ $defs:
           functional:
             description: *functional-description
             const: true
-          redundantProperties::
-            description: >-
-              If it's present, those redundant properties are also filled with
-              the same value altogether when the object is serialized into
-              JSON-LD.  When it's deserialized from JSON-LD, it tries to
-              parse the values of the specified properties in order.
-            type: array
-            items:
-              type: object
-              properties:
-                uri:
-                  description: The qualified URI of the property.
-                  type: string
-                  format: uri
-                compactName:
-                  description: >-
-                    The property name used in the compacted JSON-LD document.
-                    It is used as the key of the property.
-                  type: string
-              required:
-              - uri
         required:
         - functional
 
   property-base:
     type: object
     properties:
+      redundantProperties:
+        description: >-
+          Synonyms read after the canonical property in declaration order.
+          The first non-empty raw value set is selected before decoding values
+          and containers. Synonyms are never merged or retried on invalid values.
+          Serialization writes all synonyms by default.
+        type: array
+        items:
+          type: object
+          properties:
+            uri:
+              description: The qualified URI of the property.
+              type: string
+              format: uri
+            compactName:
+              description: >-
+                The property name used in the compacted JSON-LD document.
+                It is used as the key of the property.
+              type: string
+          required:
+          - uri
+      redundantPropertiesWrite:
+        description: >-
+          Whether serialization writes all synonyms or only the canonical
+          property. Does not change deserialization precedence.
+        enum:
+        - all
+        - canonical
+        default: all
       extraContext:
         description: >-
           A context URL added to default serialization when this property's