@formspec/build 0.1.0-alpha.27 → 0.1.0-alpha.29

package/dist/browser.cjs

@@ -50,6 +50,169 @@ module.exports = __toCommonJS(browser_exports);
 
 // src/canonicalize/chain-dsl-canonicalizer.ts
 var import_internals = require("@formspec/core/internals");
+
+// src/metadata/policy.ts
+var NOOP_INFLECT = () => "";
+function normalizePluralization(input) {
+  if (input?.mode === "infer-if-missing") {
+    return {
+      mode: "infer-if-missing",
+      infer: () => "",
+      inflect: input.inflect
+    };
+  }
+  if (input?.mode === "require-explicit") {
+    return {
+      mode: "require-explicit",
+      infer: () => "",
+      inflect: NOOP_INFLECT
+    };
+  }
+  return {
+    mode: "disabled",
+    infer: () => "",
+    inflect: NOOP_INFLECT
+  };
+}
+function normalizeScalarPolicy(input) {
+  if (input?.mode === "infer-if-missing") {
+    return {
+      mode: "infer-if-missing",
+      infer: input.infer,
+      pluralization: normalizePluralization(input.pluralization)
+    };
+  }
+  if (input?.mode === "require-explicit") {
+    return {
+      mode: "require-explicit",
+      infer: () => "",
+      pluralization: normalizePluralization(input.pluralization)
+    };
+  }
+  return {
+    mode: "disabled",
+    infer: () => "",
+    pluralization: normalizePluralization(input?.pluralization)
+  };
+}
+function normalizeDeclarationPolicy(input) {
+  return {
+    apiName: normalizeScalarPolicy(input?.apiName),
+    displayName: normalizeScalarPolicy(input?.displayName)
+  };
+}
+function normalizeMetadataPolicy(input) {
+  return {
+    type: normalizeDeclarationPolicy(input?.type),
+    field: normalizeDeclarationPolicy(input?.field),
+    method: normalizeDeclarationPolicy(input?.method)
+  };
+}
+function getDeclarationMetadataPolicy(policy, declarationKind) {
+  return policy[declarationKind];
+}
+function makeMetadataContext(surface, declarationKind, logicalName, buildContext) {
+  return {
+    surface,
+    declarationKind,
+    logicalName,
+    ...buildContext !== void 0 && { buildContext }
+  };
+}
+
+// src/metadata/resolve.ts
+function toExplicitScalar(value) {
+  return value !== void 0 && value.trim() !== "" ? { value, source: "explicit" } : void 0;
+}
+function toExplicitResolvedMetadata(explicit) {
+  if (explicit === void 0) {
+    return void 0;
+  }
+  const apiName = toExplicitScalar(explicit.apiName);
+  const displayName = toExplicitScalar(explicit.displayName);
+  const apiNamePlural = toExplicitScalar(explicit.apiNamePlural);
+  const displayNamePlural = toExplicitScalar(explicit.displayNamePlural);
+  const metadata = {
+    ...apiName !== void 0 && { apiName },
+    ...displayName !== void 0 && { displayName },
+    ...apiNamePlural !== void 0 && { apiNamePlural },
+    ...displayNamePlural !== void 0 && { displayNamePlural }
+  };
+  return Object.keys(metadata).length > 0 ? metadata : void 0;
+}
+function resolveScalar(current, policy, context, metadataLabel) {
+  if (current !== void 0) {
+    return current;
+  }
+  if (policy.mode === "require-explicit") {
+    throw new Error(
+      `Metadata policy requires explicit ${metadataLabel} for ${context.declarationKind} "${context.logicalName}" on the ${context.surface} surface.`
+    );
+  }
+  if (policy.mode !== "infer-if-missing") {
+    return void 0;
+  }
+  const inferredValue = policy.infer(context);
+  return inferredValue.trim() !== "" ? { value: inferredValue, source: "inferred" } : void 0;
+}
+function resolvePlural(current, singular, policy, context, metadataLabel) {
+  if (current !== void 0) {
+    return current;
+  }
+  if (policy.mode === "require-explicit") {
+    throw new Error(
+      `Metadata policy requires explicit ${metadataLabel} for ${context.declarationKind} "${context.logicalName}" on the ${context.surface} surface.`
+    );
+  }
+  if (singular === void 0 || policy.mode !== "infer-if-missing") {
+    return void 0;
+  }
+  const pluralValue = policy.inflect({ ...context, singular: singular.value });
+  return pluralValue.trim() !== "" ? { value: pluralValue, source: "inferred" } : void 0;
+}
+function resolveResolvedMetadata(current, policy, context) {
+  const apiName = resolveScalar(current?.apiName, policy.apiName, context, "apiName");
+  const displayName = resolveScalar(
+    current?.displayName,
+    policy.displayName,
+    context,
+    "displayName"
+  );
+  const apiNamePlural = resolvePlural(
+    current?.apiNamePlural,
+    apiName,
+    policy.apiName.pluralization,
+    context,
+    "apiNamePlural"
+  );
+  const displayNamePlural = resolvePlural(
+    current?.displayNamePlural,
+    displayName,
+    policy.displayName.pluralization,
+    context,
+    "displayNamePlural"
+  );
+  if (apiName === void 0 && displayName === void 0 && apiNamePlural === void 0 && displayNamePlural === void 0) {
+    return void 0;
+  }
+  return {
+    ...apiName !== void 0 && { apiName },
+    ...displayName !== void 0 && { displayName },
+    ...apiNamePlural !== void 0 && { apiNamePlural },
+    ...displayNamePlural !== void 0 && { displayNamePlural }
+  };
+}
+function resolveMetadata(explicit, policy, context) {
+  return resolveResolvedMetadata(toExplicitResolvedMetadata(explicit), policy, context);
+}
+function getSerializedName(logicalName, metadata) {
+  return metadata?.apiName?.value ?? logicalName;
+}
+function getDisplayName(metadata) {
+  return metadata?.displayName?.value;
+}
+
+// src/canonicalize/chain-dsl-canonicalizer.ts
 var CHAIN_DSL_PROVENANCE = {
   surface: "chain-dsl",
   file: "",
@@ -65,57 +228,60 @@ function isConditional(el) {
 function isField(el) {
   return el._type === "field";
 }
-function canonicalizeChainDSL(form) {
+function canonicalizeChainDSL(form, options) {
+  const metadataPolicy = normalizeMetadataPolicy(
+    options?.metadata ?? (0, import_internals._getFormSpecMetadataPolicy)(form)
+  );
   return {
     kind: "form-ir",
     irVersion: import_internals.IR_VERSION,
-    elements: canonicalizeElements(form.elements),
+    elements: canonicalizeElements(form.elements, metadataPolicy),
     rootAnnotations: [],
     typeRegistry: {},
     provenance: CHAIN_DSL_PROVENANCE
   };
 }
-function canonicalizeElements(elements) {
-  return elements.map(canonicalizeElement);
+function canonicalizeElements(elements, metadataPolicy) {
+  return elements.map((element) => canonicalizeElement(element, metadataPolicy));
 }
-function canonicalizeElement(element) {
+function canonicalizeElement(element, metadataPolicy) {
   if (isField(element)) {
-    return canonicalizeField(element);
+    return canonicalizeField(element, metadataPolicy);
   }
   if (isGroup(element)) {
-    return canonicalizeGroup(element);
+    return canonicalizeGroup(element, metadataPolicy);
   }
   if (isConditional(element)) {
-    return canonicalizeConditional(element);
+    return canonicalizeConditional(element, metadataPolicy);
   }
   const _exhaustive = element;
   throw new Error(`Unknown element type: ${JSON.stringify(_exhaustive)}`);
 }
-function canonicalizeField(field) {
+function canonicalizeField(field, metadataPolicy) {
   switch (field._field) {
     case "text":
-      return canonicalizeTextField(field);
+      return canonicalizeTextField(field, metadataPolicy);
     case "number":
-      return canonicalizeNumberField(field);
+      return canonicalizeNumberField(field, metadataPolicy);
     case "boolean":
-      return canonicalizeBooleanField(field);
+      return canonicalizeBooleanField(field, metadataPolicy);
     case "enum":
-      return canonicalizeStaticEnumField(field);
+      return canonicalizeStaticEnumField(field, metadataPolicy);
     case "dynamic_enum":
-      return canonicalizeDynamicEnumField(field);
+      return canonicalizeDynamicEnumField(field, metadataPolicy);
     case "dynamic_schema":
-      return canonicalizeDynamicSchemaField(field);
+      return canonicalizeDynamicSchemaField(field, metadataPolicy);
     case "array":
-      return canonicalizeArrayField(field);
+      return canonicalizeArrayField(field, metadataPolicy);
     case "object":
-      return canonicalizeObjectField(field);
+      return canonicalizeObjectField(field, metadataPolicy);
     default: {
       const _exhaustive = field;
       throw new Error(`Unknown field type: ${JSON.stringify(_exhaustive)}`);
     }
   }
 }
-function canonicalizeTextField(field) {
+function canonicalizeTextField(field, metadataPolicy) {
   const type = { kind: "primitive", primitiveKind: "string" };
   const constraints = [];
   if (field.minLength !== void 0) {
@@ -147,13 +313,14 @@ function canonicalizeTextField(field) {
   }
   return buildFieldNode(
     field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
     type,
     field.required,
-    buildAnnotations(field.label, field.placeholder),
+    buildAnnotations(getExplicitDisplayName(field), field.placeholder),
     constraints
   );
 }
-function canonicalizeNumberField(field) {
+function canonicalizeNumberField(field, metadataPolicy) {
   const type = { kind: "primitive", primitiveKind: "number" };
   const constraints = [];
   if (field.min !== void 0) {
@@ -185,17 +352,24 @@ function canonicalizeNumberField(field) {
   }
   return buildFieldNode(
     field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
     type,
     field.required,
-    buildAnnotations(field.label),
+    buildAnnotations(getExplicitDisplayName(field)),
     constraints
   );
 }
-function canonicalizeBooleanField(field) {
+function canonicalizeBooleanField(field, metadataPolicy) {
   const type = { kind: "primitive", primitiveKind: "boolean" };
-  return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
+  return buildFieldNode(
+    field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
+    type,
+    field.required,
+    buildAnnotations(getExplicitDisplayName(field))
+  );
 }
-function canonicalizeStaticEnumField(field) {
+function canonicalizeStaticEnumField(field, metadataPolicy) {
   const members = field.options.map((opt) => {
     if (typeof opt === "string") {
       return { value: opt };
@@ -203,28 +377,46 @@ function canonicalizeStaticEnumField(field) {
     return { value: opt.id, displayName: opt.label };
   });
   const type = { kind: "enum", members };
-  return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
+  return buildFieldNode(
+    field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
+    type,
+    field.required,
+    buildAnnotations(getExplicitDisplayName(field))
+  );
 }
-function canonicalizeDynamicEnumField(field) {
+function canonicalizeDynamicEnumField(field, metadataPolicy) {
   const type = {
     kind: "dynamic",
     dynamicKind: "enum",
     sourceKey: field.source,
     parameterFields: field.params ? [...field.params] : []
   };
-  return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
+  return buildFieldNode(
+    field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
+    type,
+    field.required,
+    buildAnnotations(getExplicitDisplayName(field))
+  );
 }
-function canonicalizeDynamicSchemaField(field) {
+function canonicalizeDynamicSchemaField(field, metadataPolicy) {
   const type = {
     kind: "dynamic",
     dynamicKind: "schema",
     sourceKey: field.schemaSource,
     parameterFields: []
   };
-  return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
+  return buildFieldNode(
+    field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
+    type,
+    field.required,
+    buildAnnotations(getExplicitDisplayName(field))
+  );
 }
-function canonicalizeArrayField(field) {
-  const itemProperties = buildObjectProperties(field.items);
+function canonicalizeArrayField(field, metadataPolicy) {
+  const itemProperties = buildObjectProperties(field.items, metadataPolicy);
   const itemsType = {
     kind: "object",
     properties: itemProperties,
@@ -252,37 +444,44 @@ function canonicalizeArrayField(field) {
   }
   return buildFieldNode(
     field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
     type,
     field.required,
-    buildAnnotations(field.label),
+    buildAnnotations(getExplicitDisplayName(field)),
     constraints
   );
 }
-function canonicalizeObjectField(field) {
-  const properties = buildObjectProperties(field.properties);
+function canonicalizeObjectField(field, metadataPolicy) {
+  const properties = buildObjectProperties(field.properties, metadataPolicy);
   const type = {
     kind: "object",
     properties,
     additionalProperties: true
   };
-  return buildFieldNode(field.name, type, field.required, buildAnnotations(field.label));
+  return buildFieldNode(
+    field.name,
+    resolveFieldMetadata(field.name, field, metadataPolicy),
+    type,
+    field.required,
+    buildAnnotations(getExplicitDisplayName(field))
+  );
 }
-function canonicalizeGroup(g) {
+function canonicalizeGroup(g, metadataPolicy) {
   return {
     kind: "group",
     label: g.label,
-    elements: canonicalizeElements(g.elements),
+    elements: canonicalizeElements(g.elements, metadataPolicy),
     provenance: CHAIN_DSL_PROVENANCE
   };
 }
-function canonicalizeConditional(c) {
+function canonicalizeConditional(c, metadataPolicy) {
   return {
     kind: "conditional",
     fieldName: c.field,
     // Conditional values from the chain DSL are JSON-serializable primitives
     // (strings, numbers, booleans) produced by the `is()` predicate helper.
     value: assertJsonValue(c.value),
-    elements: canonicalizeElements(c.elements),
+    elements: canonicalizeElements(c.elements, metadataPolicy),
     provenance: CHAIN_DSL_PROVENANCE
   };
 }
@@ -302,10 +501,11 @@ function assertJsonValue(v) {
   }
   throw new TypeError(`Conditional value is not a valid JsonValue: ${typeof v}`);
 }
-function buildFieldNode(name, type, required, annotations, constraints = []) {
+function buildFieldNode(name, metadata, type, required, annotations, constraints = []) {
   return {
     kind: "field",
     name,
+    ...metadata !== void 0 && { metadata },
     type,
     required: required === true,
     constraints,
@@ -335,13 +535,14 @@ function buildAnnotations(label, placeholder) {
   }
   return annotations;
 }
-function buildObjectProperties(elements, insideConditional = false) {
+function buildObjectProperties(elements, metadataPolicy, insideConditional = false) {
   const properties = [];
   for (const el of elements) {
     if (isField(el)) {
-      const fieldNode = canonicalizeField(el);
+      const fieldNode = canonicalizeField(el, metadataPolicy);
       properties.push({
         name: fieldNode.name,
+        ...fieldNode.metadata !== void 0 && { metadata: fieldNode.metadata },
         type: fieldNode.type,
         // Fields inside a conditional branch are always optional in the
         // data schema, regardless of their `required` flag — the condition
@@ -352,17 +553,148 @@ function buildObjectProperties(elements, insideConditional = false) {
         provenance: CHAIN_DSL_PROVENANCE
       });
     } else if (isGroup(el)) {
-      properties.push(...buildObjectProperties(el.elements, insideConditional));
+      properties.push(...buildObjectProperties(el.elements, metadataPolicy, insideConditional));
     } else if (isConditional(el)) {
-      properties.push(...buildObjectProperties(el.elements, true));
+      properties.push(...buildObjectProperties(el.elements, metadataPolicy, true));
     }
   }
   return properties;
 }
+function getExplicitDisplayName(field) {
+  if (field.label !== void 0 && field.displayName !== void 0) {
+    throw new Error('Chain DSL fields cannot specify both "label" and "displayName".');
+  }
+  return field.displayName ?? field.label;
+}
+function resolveFieldMetadata(logicalName, field, metadataPolicy) {
+  const displayName = getExplicitDisplayName(field);
+  return resolveMetadata(
+    {
+      ...field.apiName !== void 0 && { apiName: field.apiName },
+      ...displayName !== void 0 && { displayName }
+    },
+    getDeclarationMetadataPolicy(metadataPolicy, "field"),
+    makeMetadataContext("chain-dsl", "field", logicalName)
+  );
+}
 
 // src/canonicalize/tsdoc-canonicalizer.ts
 var import_internals2 = require("@formspec/core/internals");
 
+// src/metadata/collision-guards.ts
+function assertUniqueSerializedNames(entries, scope) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const previous = seen.get(entry.serializedName);
+    if (previous !== void 0) {
+      if (previous.logicalName === entry.logicalName && previous.category === entry.category) {
+        continue;
+      }
+      throw new Error(
+        `Serialized name collision in ${scope}: ${previous.category} "${previous.logicalName}" and ${entry.category} "${entry.logicalName}" both resolve to "${entry.serializedName}".`
+      );
+    }
+    seen.set(entry.serializedName, entry);
+  }
+}
+function collectFlattenedFields(elements) {
+  const fields = [];
+  for (const element of elements) {
+    switch (element.kind) {
+      case "field":
+        fields.push(element);
+        break;
+      case "group":
+      case "conditional":
+        fields.push(...collectFlattenedFields(element.elements));
+        break;
+      default: {
+        const exhaustive = element;
+        void exhaustive;
+      }
+    }
+  }
+  return fields;
+}
+function validateObjectProperties(properties, scope) {
+  assertUniqueSerializedNames(
+    properties.map((property) => ({
+      logicalName: property.name,
+      serializedName: getSerializedName(property.name, property.metadata),
+      category: "object property"
+    })),
+    scope
+  );
+  for (const property of properties) {
+    validateTypeNode(
+      property.type,
+      `${scope}.${getSerializedName(property.name, property.metadata)}`
+    );
+  }
+}
+function validateTypeNode(type, scope) {
+  switch (type.kind) {
+    case "array":
+      validateTypeNode(type.items, `${scope}[]`);
+      break;
+    case "object":
+      validateObjectProperties(type.properties, scope);
+      break;
+    case "record":
+      validateTypeNode(type.valueType, `${scope}.*`);
+      break;
+    case "union":
+      type.members.forEach((member, index) => {
+        validateTypeNode(member, `${scope}|${String(index)}`);
+      });
+      break;
+    case "reference":
+    case "primitive":
+    case "enum":
+    case "dynamic":
+    case "custom":
+      break;
+    default: {
+      const exhaustive = type;
+      void exhaustive;
+    }
+  }
+}
+function validateTypeDefinitions(typeRegistry) {
+  const definitions = Object.values(typeRegistry);
+  assertUniqueSerializedNames(
+    definitions.map((definition) => ({
+      logicalName: definition.name,
+      serializedName: getSerializedName(definition.name, definition.metadata),
+      category: "type definition"
+    })),
+    "$defs"
+  );
+  for (const definition of definitions) {
+    validateTypeDefinition(definition);
+  }
+}
+function validateTypeDefinition(definition) {
+  validateTypeNode(
+    definition.type,
+    `type "${getSerializedName(definition.name, definition.metadata)}"`
+  );
+}
+function assertNoSerializedNameCollisions(ir) {
+  assertUniqueSerializedNames(
+    collectFlattenedFields(ir.elements).map((field) => ({
+      logicalName: field.name,
+      serializedName: getSerializedName(field.name, field.metadata),
+      category: "field"
+    })),
+    "form root"
+  );
+  for (const field of collectFlattenedFields(ir.elements)) {
+    validateTypeNode(field.type, `field "${getSerializedName(field.name, field.metadata)}"`);
+  }
+  validateTypeDefinitions(ir.typeRegistry);
+}
+
 // src/json-schema/ir-generator.ts
 function makeContext(options) {
   const vendorPrefix = options?.vendorPrefix ?? "x-formspec";
@@ -373,19 +705,33 @@ function makeContext(options) {
   }
   return {
     defs: {},
+    typeNameMap: {},
+    typeRegistry: {},
     extensionRegistry: options?.extensionRegistry,
     vendorPrefix
   };
 }
 function generateJsonSchemaFromIR(ir, options) {
-  const ctx = makeContext(options);
+  assertNoSerializedNameCollisions(ir);
+  const ctx = {
+    ...makeContext(options),
+    typeRegistry: ir.typeRegistry,
+    typeNameMap: Object.fromEntries(
+      Object.entries(ir.typeRegistry).map(([name, typeDef]) => [
+        name,
+        getSerializedName(name, typeDef.metadata)
+      ])
+    )
+  };
   for (const [name, typeDef] of Object.entries(ir.typeRegistry)) {
-    ctx.defs[name] = generateTypeNode(typeDef.type, ctx);
+    const schemaName = ctx.typeNameMap[name] ?? name;
+    ctx.defs[schemaName] = generateTypeNode(typeDef.type, ctx);
+    applyResolvedMetadata(ctx.defs[schemaName], typeDef.metadata);
     if (typeDef.constraints && typeDef.constraints.length > 0) {
-      applyConstraints(ctx.defs[name], typeDef.constraints, ctx);
+      applyConstraints(ctx.defs[schemaName], typeDef.constraints, ctx);
     }
     if (typeDef.annotations && typeDef.annotations.length > 0) {
-      applyAnnotations(ctx.defs[name], typeDef.annotations, ctx);
+      applyAnnotations(ctx.defs[schemaName], typeDef.annotations, ctx);
     }
   }
   const properties = {};
@@ -398,6 +744,7 @@ function generateJsonSchemaFromIR(ir, options) {
     properties,
     ...uniqueRequired.length > 0 && { required: uniqueRequired }
   };
+  applyResolvedMetadata(result, ir.metadata);
   if (ir.annotations && ir.annotations.length > 0) {
     applyAnnotations(result, ir.annotations, ctx);
   }
@@ -410,9 +757,9 @@ function collectFields(elements, properties, required, ctx) {
   for (const element of elements) {
     switch (element.kind) {
       case "field":
-        properties[element.name] = generateFieldSchema(element, ctx);
+        properties[getSerializedName(element.name, element.metadata)] = generateFieldSchema(element, ctx);
         if (element.required) {
-          required.push(element.name);
+          required.push(getSerializedName(element.name, element.metadata));
         }
         break;
       case "group":
@@ -456,6 +803,7 @@ function generateFieldSchema(field, ctx) {
       rootAnnotations.push(annotation);
     }
   }
+  applyResolvedMetadata(schema, field.metadata);
   applyAnnotations(schema, rootAnnotations, ctx);
   if (itemStringSchema !== void 0) {
     applyAnnotations(itemStringSchema, itemAnnotations, ctx);
@@ -463,7 +811,7 @@ function generateFieldSchema(field, ctx) {
   if (pathConstraints.length === 0) {
     return schema;
   }
-  return applyPathTargetedConstraints(schema, pathConstraints, ctx);
+  return applyPathTargetedConstraints(schema, pathConstraints, ctx, field.type);
 }
 function isStringItemConstraint(constraint) {
   switch (constraint.constraintKind) {
@@ -475,9 +823,11 @@ function isStringItemConstraint(constraint) {
       return false;
   }
 }
-function applyPathTargetedConstraints(schema, pathConstraints, ctx) {
+function applyPathTargetedConstraints(schema, pathConstraints, ctx, typeNode) {
   if (schema.type === "array" && schema.items) {
-    schema.items = applyPathTargetedConstraints(schema.items, pathConstraints, ctx);
+    const referencedType = typeNode?.kind === "reference" ? resolveReferencedType(typeNode, ctx) : void 0;
+    const nestedType = typeNode?.kind === "array" ? typeNode.items : referencedType?.kind === "array" ? referencedType.items : void 0;
+    schema.items = applyPathTargetedConstraints(schema.items, pathConstraints, ctx, nestedType);
     return schema;
   }
   const byTarget = /* @__PURE__ */ new Map();
@@ -492,7 +842,7 @@ function applyPathTargetedConstraints(schema, pathConstraints, ctx) {
   for (const [target, constraints] of byTarget) {
     const subSchema = {};
     applyConstraints(subSchema, constraints, ctx);
-    propertyOverrides[target] = subSchema;
+    propertyOverrides[resolveSerializedPropertyName(target, typeNode, ctx)] = subSchema;
   }
   if (schema.$ref) {
     const { $ref, ...rest } = schema;
@@ -540,7 +890,7 @@ function generateTypeNode(type, ctx) {
     case "union":
       return generateUnionType(type, ctx);
     case "reference":
-      return generateReferenceType(type);
+      return generateReferenceType(type, ctx);
     case "dynamic":
       return generateDynamicType(type);
     case "custom":
@@ -581,9 +931,10 @@ function generateObjectType(type, ctx) {
   const properties = {};
   const required = [];
   for (const prop of type.properties) {
-    properties[prop.name] = generatePropertySchema(prop, ctx);
+    const propertyName = getSerializedName(prop.name, prop.metadata);
+    properties[propertyName] = generatePropertySchema(prop, ctx);
     if (!prop.optional) {
-      required.push(prop.name);
+      required.push(propertyName);
     }
   }
   const schema = { type: "object", properties };
@@ -604,6 +955,7 @@ function generateRecordType(type, ctx) {
 function generatePropertySchema(prop, ctx) {
   const schema = generateTypeNode(prop.type, ctx);
   applyConstraints(schema, prop.constraints, ctx);
+  applyResolvedMetadata(schema, prop.metadata);
   applyAnnotations(schema, prop.annotations, ctx);
   return schema;
 }
@@ -632,8 +984,28 @@ function isNullableUnion(type) {
   ).length;
   return nullCount === 1;
 }
-function generateReferenceType(type) {
-  return { $ref: `#/$defs/${type.name}` };
+function generateReferenceType(type, ctx) {
+  return { $ref: `#/$defs/${ctx.typeNameMap[type.name] ?? type.name}` };
+}
+function applyResolvedMetadata(schema, metadata) {
+  const displayName = getDisplayName(metadata);
+  if (displayName !== void 0) {
+    schema.title = displayName;
+  }
+}
+function resolveReferencedType(type, ctx) {
+  return ctx.typeRegistry[type.name]?.type;
+}
+function resolveSerializedPropertyName(logicalName, typeNode, ctx) {
+  if (typeNode?.kind === "object") {
+    const property = typeNode.properties.find((candidate) => candidate.name === logicalName);
+    return property === void 0 ? logicalName : getSerializedName(property.name, property.metadata);
+  }
+  if (typeNode?.kind === "reference") {
+    const referencedType = resolveReferencedType(typeNode, ctx);
+    return referencedType === void 0 ? logicalName : resolveSerializedPropertyName(logicalName, referencedType, ctx);
+  }
+  return logicalName;
 }
 function generateDynamicType(type) {
   if (type.dynamicKind === "enum") {
@@ -713,7 +1085,7 @@ function applyAnnotations(schema, annotations, ctx) {
   for (const annotation of annotations) {
     switch (annotation.annotationKind) {
       case "displayName":
-        schema.title = annotation.value;
+        schema.title ??= annotation.value;
         break;
       case "description":
         schema.description = annotation.value;
@@ -800,7 +1172,10 @@ function assignVendorPrefixedExtensionKeywords(schema, extensionSchema, vendorPr
 
 // src/json-schema/generator.ts
 function generateJsonSchema(form, options) {
-  const ir = canonicalizeChainDSL(form);
+  const ir = canonicalizeChainDSL(
+    form,
+    options?.metadata !== void 0 ? { metadata: options.metadata } : void 0
+  );
   const internalOptions = options?.vendorPrefix === void 0 ? void 0 : { vendorPrefix: options.vendorPrefix };
   return generateJsonSchemaFromIR(ir, internalOptions);
 }
@@ -970,13 +1345,21 @@ function combineRules(parentRule, childRule) {
     }
   };
 }
-function fieldNodeToControl(field, parentRule) {
-  const displayNameAnnotation = field.annotations.find((a) => a.annotationKind === "displayName");
+function getFieldDisplayName(field) {
+  const resolvedDisplayName = getDisplayName(field.metadata);
+  if (resolvedDisplayName !== void 0) {
+    return resolvedDisplayName;
+  }
+  return field.annotations.find((annotation) => annotation.annotationKind === "displayName")?.value;
+}
+function fieldNodeToControl(field, fieldNameMap, parentRule) {
   const placeholderAnnotation = field.annotations.find((a) => a.annotationKind === "placeholder");
+  const serializedName = fieldNameMap.get(field.name) ?? getSerializedName(field.name, field.metadata);
+  const displayName = getFieldDisplayName(field);
   const control = {
     type: "Control",
-    scope: fieldToScope(field.name),
-    ...displayNameAnnotation !== void 0 && { label: displayNameAnnotation.value },
+    scope: fieldToScope(serializedName),
+    ...displayName !== void 0 && { label: displayName },
     ...placeholderAnnotation !== void 0 && {
       options: { placeholder: placeholderAnnotation.value }
     },
@@ -984,30 +1367,30 @@ function fieldNodeToControl(field, parentRule) {
   };
   return control;
 }
-function groupNodeToLayout(group, parentRule) {
+function groupNodeToLayout(group, fieldNameMap, parentRule) {
   return {
     type: "Group",
     label: group.label,
-    elements: irElementsToUiSchema(group.elements, parentRule),
+    elements: irElementsToUiSchema(group.elements, fieldNameMap, parentRule),
     ...parentRule !== void 0 && { rule: parentRule }
   };
 }
-function irElementsToUiSchema(elements, parentRule) {
+function irElementsToUiSchema(elements, fieldNameMap, parentRule) {
   const result = [];
   for (const element of elements) {
     switch (element.kind) {
       case "field": {
-        result.push(fieldNodeToControl(element, parentRule));
+        result.push(fieldNodeToControl(element, fieldNameMap, parentRule));
         break;
       }
       case "group": {
-        result.push(groupNodeToLayout(element, parentRule));
+        result.push(groupNodeToLayout(element, fieldNameMap, parentRule));
         break;
       }
       case "conditional": {
-        const newRule = createShowRule(element.fieldName, element.value);
+        const newRule = createShowRule(fieldNameMap.get(element.fieldName) ?? element.fieldName, element.value);
         const combinedRule = parentRule !== void 0 ? combineRules(parentRule, newRule) : newRule;
-        const childElements = irElementsToUiSchema(element.elements, combinedRule);
+        const childElements = irElementsToUiSchema(element.elements, fieldNameMap, combinedRule);
         result.push(...childElements);
         break;
       }
@@ -1021,16 +1404,42 @@ function irElementsToUiSchema(elements, parentRule) {
   return result;
 }
 function generateUiSchemaFromIR(ir) {
+  assertNoSerializedNameCollisions(ir);
+  const fieldNameMap = collectFieldNameMap(ir.elements);
   const result = {
     type: "VerticalLayout",
-    elements: irElementsToUiSchema(ir.elements)
+    elements: irElementsToUiSchema(ir.elements, fieldNameMap)
   };
   return parseOrThrow(uiSchema, result, "UI Schema");
 }
+function collectFieldNameMap(elements) {
+  const map = /* @__PURE__ */ new Map();
+  for (const element of elements) {
+    switch (element.kind) {
+      case "field":
+        map.set(element.name, getSerializedName(element.name, element.metadata));
+        break;
+      case "group":
+      case "conditional":
+        for (const [key, value] of collectFieldNameMap(element.elements)) {
+          map.set(key, value);
+        }
+        break;
+      default: {
+        const _exhaustive = element;
+        void _exhaustive;
+      }
+    }
+  }
+  return map;
+}
 
 // src/ui-schema/generator.ts
-function generateUiSchema(form) {
-  const ir = canonicalizeChainDSL(form);
+function generateUiSchema(form, options) {
+  const ir = canonicalizeChainDSL(
+    form,
+    options?.metadata !== void 0 ? { metadata: options.metadata } : void 0
+  );
   return generateUiSchemaFromIR(ir);
 }
 
@@ -1261,7 +1670,7 @@ function validateIR(ir, options) {
 function buildFormSchemas(form, options) {
   return {
     jsonSchema: generateJsonSchema(form, options),
-    uiSchema: generateUiSchema(form)
+    uiSchema: generateUiSchema(form, options)
   };
 }
 // Annotate the CommonJS export names for ESM import in node: