@formspec/build 0.1.0-alpha.28 → 0.1.0-alpha.30

package/dist/index.cjs

@@ -46,6 +46,315 @@ module.exports = __toCommonJS(index_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 pickResolvedMetadataValue(baseValue, overlayValue) {
+  if (overlayValue?.source === "explicit") {
+    return overlayValue;
+  }
+  if (baseValue?.source === "explicit") {
+    return baseValue;
+  }
+  return baseValue ?? overlayValue;
+}
+function resolveTypeNodeMetadata(type, options) {
+  switch (type.kind) {
+    case "array":
+      return {
+        ...type,
+        items: resolveTypeNodeMetadata(type.items, options)
+      };
+    case "object":
+      return {
+        ...type,
+        properties: type.properties.map((property) => resolveObjectPropertyMetadata(property, options))
+      };
+    case "record":
+      return {
+        ...type,
+        valueType: resolveTypeNodeMetadata(type.valueType, options)
+      };
+    case "union":
+      return {
+        ...type,
+        members: type.members.map((member) => resolveTypeNodeMetadata(member, options))
+      };
+    case "reference":
+    case "primitive":
+    case "enum":
+    case "dynamic":
+    case "custom":
+      return type;
+    default: {
+      const _exhaustive = type;
+      return _exhaustive;
+    }
+  }
+}
+function resolveObjectPropertyMetadata(property, options) {
+  const metadata = resolveResolvedMetadata(property.metadata, options.policy.field, {
+    surface: options.surface,
+    declarationKind: "field",
+    logicalName: property.name,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...property,
+    ...metadata !== void 0 && { metadata },
+    type: resolveTypeNodeMetadata(property.type, options)
+  };
+}
+function resolveFieldMetadataNode(field, options) {
+  const metadata = resolveResolvedMetadata(field.metadata, options.policy.field, {
+    surface: options.surface,
+    declarationKind: "field",
+    logicalName: field.name,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...field,
+    ...metadata !== void 0 && { metadata },
+    type: resolveTypeNodeMetadata(field.type, options)
+  };
+}
+function resolveFormElementMetadata(element, options) {
+  switch (element.kind) {
+    case "field":
+      return resolveFieldMetadataNode(element, options);
+    case "group":
+      return {
+        ...element,
+        elements: element.elements.map((child) => resolveFormElementMetadata(child, options))
+      };
+    case "conditional":
+      return {
+        ...element,
+        elements: element.elements.map((child) => resolveFormElementMetadata(child, options))
+      };
+    default: {
+      const _exhaustive = element;
+      return _exhaustive;
+    }
+  }
+}
+function resolveTypeDefinitionMetadata(typeDefinition, options) {
+  const metadata = resolveResolvedMetadata(typeDefinition.metadata, options.policy.type, {
+    surface: options.surface,
+    declarationKind: "type",
+    logicalName: typeDefinition.name,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...typeDefinition,
+    ...metadata !== void 0 && { metadata },
+    type: resolveTypeNodeMetadata(typeDefinition.type, options)
+  };
+}
+function resolveMetadata(explicit, policy, context) {
+  return resolveResolvedMetadata(toExplicitResolvedMetadata(explicit), policy, context);
+}
+function mergeResolvedMetadata(baseMetadata, overlayMetadata) {
+  const apiName = pickResolvedMetadataValue(baseMetadata?.apiName, overlayMetadata?.apiName);
+  const displayName = pickResolvedMetadataValue(
+    baseMetadata?.displayName,
+    overlayMetadata?.displayName
+  );
+  const apiNamePlural = pickResolvedMetadataValue(
+    baseMetadata?.apiNamePlural,
+    overlayMetadata?.apiNamePlural
+  );
+  const displayNamePlural = pickResolvedMetadataValue(
+    baseMetadata?.displayNamePlural,
+    overlayMetadata?.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 getSerializedName(logicalName, metadata) {
+  return metadata?.apiName?.value ?? logicalName;
+}
+function getDisplayName(metadata) {
+  return metadata?.displayName?.value;
+}
+function resolveFormIRMetadata(ir, options) {
+  const rootLogicalName = options.rootLogicalName ?? ir.name ?? "FormSpec";
+  const metadata = resolveResolvedMetadata(ir.metadata, options.policy.type, {
+    surface: options.surface,
+    declarationKind: "type",
+    logicalName: rootLogicalName,
+    ...options.buildContext !== void 0 && { buildContext: options.buildContext }
+  });
+  return {
+    ...ir,
+    ...metadata !== void 0 && { metadata },
+    elements: ir.elements.map((element) => resolveFormElementMetadata(element, options)),
+    typeRegistry: Object.fromEntries(
+      Object.entries(ir.typeRegistry).map(([name, definition]) => [
+        name,
+        resolveTypeDefinitionMetadata(definition, options)
+      ])
+    )
+  };
+}
+
+// src/canonicalize/chain-dsl-canonicalizer.ts
 var CHAIN_DSL_PROVENANCE = {
   surface: "chain-dsl",
   file: "",
@@ -61,57 +370,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) {
@@ -143,13 +455,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) {
@@ -181,17 +494,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 };
@@ -199,28 +519,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,
@@ -248,37 +586,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
   };
 }
@@ -298,10 +643,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,
@@ -331,13 +677,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
@@ -348,17 +695,34 @@ 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");
-function canonicalizeTSDoc(analysis, source) {
+function canonicalizeTSDoc(analysis, source, options) {
   const file = source?.file ?? "";
   const provenance = {
     surface: "tsdoc",
@@ -367,15 +731,21 @@ function canonicalizeTSDoc(analysis, source) {
     column: 0
   };
   const elements = assembleElements(analysis.fields, analysis.fieldLayouts, provenance);
-  return {
+  const ir = {
     kind: "form-ir",
+    name: analysis.name,
     irVersion: import_internals2.IR_VERSION,
     elements,
+    ...analysis.metadata !== void 0 && { metadata: analysis.metadata },
     typeRegistry: analysis.typeRegistry,
     ...analysis.annotations !== void 0 && analysis.annotations.length > 0 && { rootAnnotations: analysis.annotations },
     ...analysis.annotations !== void 0 && analysis.annotations.length > 0 && { annotations: analysis.annotations },
     provenance
   };
+  return resolveFormIRMetadata(ir, {
+    policy: normalizeMetadataPolicy(options?.metadata),
+    surface: "tsdoc"
+  });
 }
 function assembleElements(fields, layouts, provenance) {
   const elements = [];
@@ -432,6 +802,120 @@ function wrapInConditional(field, layout, provenance) {
   return conditional;
 }
 
+// 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";
@@ -442,19 +926,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 = {};
@@ -467,6 +965,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);
   }
@@ -479,9 +978,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":
@@ -525,6 +1024,7 @@ function generateFieldSchema(field, ctx) {
       rootAnnotations.push(annotation);
     }
   }
+  applyResolvedMetadata(schema, field.metadata);
   applyAnnotations(schema, rootAnnotations, ctx);
   if (itemStringSchema !== void 0) {
     applyAnnotations(itemStringSchema, itemAnnotations, ctx);
@@ -532,7 +1032,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) {
@@ -544,9 +1044,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();
@@ -561,7 +1063,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;
@@ -609,7 +1111,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":
@@ -650,9 +1152,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 };
@@ -673,6 +1176,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;
 }
@@ -701,8 +1205,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") {
@@ -782,7 +1306,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;
@@ -869,7 +1393,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);
 }
@@ -1039,13 +1566,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 }
     },
@@ -1053,30 +1588,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;
       }
@@ -1090,16 +1625,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);
 }
 
@@ -2136,7 +2697,76 @@ function makeParseOptions(extensionRegistry, fieldType, checker, subjectType, ho
     ...hostType !== void 0 && { hostType }
   };
 }
-function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
+function makeExplicitScalarMetadata(value) {
+  return value === void 0 || value === "" ? void 0 : { value, source: "explicit" };
+}
+function extractExplicitMetadata(node) {
+  let apiName;
+  let displayName;
+  let apiNamePlural;
+  let displayNamePlural;
+  for (const tag of getLeadingParsedTags(node)) {
+    const value = tag.argumentText.trim();
+    if (value === "") {
+      continue;
+    }
+    if (tag.normalizedTagName === "apiName") {
+      if (tag.target === null) {
+        apiName ??= value;
+      } else if (tag.target.kind === "variant") {
+        if (tag.target.rawText === "singular") {
+          apiName ??= value;
+        } else if (tag.target.rawText === "plural") {
+          apiNamePlural ??= value;
+        }
+      }
+      continue;
+    }
+    if (tag.normalizedTagName === "displayName") {
+      if (tag.target === null) {
+        displayName ??= value;
+      } else if (tag.target.kind === "variant") {
+        if (tag.target.rawText === "singular") {
+          displayName ??= value;
+        } else if (tag.target.rawText === "plural") {
+          displayNamePlural ??= value;
+        }
+      }
+    }
+  }
+  const resolvedApiName = makeExplicitScalarMetadata(apiName);
+  const resolvedDisplayName = makeExplicitScalarMetadata(displayName);
+  const resolvedApiNamePlural = makeExplicitScalarMetadata(apiNamePlural);
+  const resolvedDisplayNamePlural = makeExplicitScalarMetadata(displayNamePlural);
+  const metadata = {
+    ...resolvedApiName !== void 0 && { apiName: resolvedApiName },
+    ...resolvedDisplayName !== void 0 && { displayName: resolvedDisplayName },
+    ...resolvedApiNamePlural !== void 0 && { apiNamePlural: resolvedApiNamePlural },
+    ...resolvedDisplayNamePlural !== void 0 && {
+      displayNamePlural: resolvedDisplayNamePlural
+    }
+  };
+  return Object.keys(metadata).length === 0 ? void 0 : metadata;
+}
+function resolveNodeMetadata(metadataPolicy, declarationKind, logicalName, node, buildContext) {
+  const explicit = extractExplicitMetadata(node);
+  return resolveMetadata(
+    {
+      ...explicit?.apiName !== void 0 && { apiName: explicit.apiName.value },
+      ...explicit?.displayName !== void 0 && { displayName: explicit.displayName.value },
+      ...explicit?.apiNamePlural !== void 0 && {
+        apiNamePlural: explicit.apiNamePlural.value
+      },
+      ...explicit?.displayNamePlural !== void 0 && {
+        displayNamePlural: explicit.displayNamePlural.value
+      }
+    },
+    getDeclarationMetadataPolicy(metadataPolicy, declarationKind),
+    makeMetadataContext("tsdoc", declarationKind, logicalName, buildContext)
+  );
+}
+function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry, metadataPolicy) {
+  const normalizedMetadataPolicy = normalizeMetadataPolicy(metadataPolicy);
   const name = classDecl.name?.text ?? "AnonymousClass";
   const fields = [];
   const fieldLayouts = [];
@@ -2163,6 +2793,7 @@ function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
         visiting,
         diagnostics,
         classType,
+        normalizedMetadataPolicy,
         extensionRegistry
       );
       if (fieldNode) {
@@ -2187,10 +2818,18 @@ function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
     classType,
     checker,
     file,
-    diagnostics
+    diagnostics,
+    normalizedMetadataPolicy
   );
+  const metadata = resolveNodeMetadata(normalizedMetadataPolicy, "type", name, classDecl, {
+    checker,
+    declaration: classDecl,
+    subjectType: classType,
+    hostType: classType
+  });
   return {
     name,
+    ...metadata !== void 0 && { metadata },
     fields: specializedFields,
     fieldLayouts,
     typeRegistry,
@@ -2200,7 +2839,8 @@ function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
     staticMethods
   };
 }
-function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegistry) {
+function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegistry, metadataPolicy) {
+  const normalizedMetadataPolicy = normalizeMetadataPolicy(metadataPolicy);
   const name = interfaceDecl.name.text;
   const fields = [];
   const typeRegistry = {};
@@ -2224,6 +2864,7 @@ function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegist
         visiting,
         diagnostics,
         interfaceType,
+        normalizedMetadataPolicy,
         extensionRegistry
       );
       if (fieldNode) {
@@ -2237,11 +2878,19 @@ function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegist
     interfaceType,
     checker,
     file,
-    diagnostics
+    diagnostics,
+    normalizedMetadataPolicy
   );
   const fieldLayouts = specializedFields.map(() => ({}));
+  const metadata = resolveNodeMetadata(normalizedMetadataPolicy, "type", name, interfaceDecl, {
+    checker,
+    declaration: interfaceDecl,
+    subjectType: interfaceType,
+    hostType: interfaceType
+  });
   return {
     name,
+    ...metadata !== void 0 && { metadata },
     fields: specializedFields,
     fieldLayouts,
     typeRegistry,
@@ -2251,7 +2900,7 @@ function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegist
     staticMethods: []
   };
 }
-function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry) {
+function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry, metadataPolicy) {
   if (!ts3.isTypeLiteralNode(typeAlias.type)) {
     const sourceFile = typeAlias.getSourceFile();
     const { line } = sourceFile.getLineAndCharacterOfPosition(typeAlias.getStart());
@@ -2261,6 +2910,8 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
       error: `Type alias "${typeAlias.name.text}" at line ${String(line + 1)} is not an object type literal (found ${kindDesc})`
     };
   }
+  const typeLiteral = typeAlias.type;
+  const normalizedMetadataPolicy = normalizeMetadataPolicy(metadataPolicy);
   const name = typeAlias.name.text;
   const fields = [];
   const typeRegistry = {};
@@ -2274,7 +2925,7 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
   const annotations = [...typeAliasDoc.annotations];
   diagnostics.push(...typeAliasDoc.diagnostics);
   const visiting = /* @__PURE__ */ new Set();
-  for (const member of typeAlias.type.members) {
+  for (const member of typeLiteral.members) {
     if (ts3.isPropertySignature(member)) {
       const fieldNode = analyzeInterfacePropertyToIR(
         member,
@@ -2284,6 +2935,7 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
         visiting,
         diagnostics,
         aliasType,
+        normalizedMetadataPolicy,
         extensionRegistry
       );
       if (fieldNode) {
@@ -2297,12 +2949,20 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
     aliasType,
     checker,
     file,
-    diagnostics
+    diagnostics,
+    normalizedMetadataPolicy
   );
+  const metadata = resolveNodeMetadata(normalizedMetadataPolicy, "type", name, typeAlias, {
+    checker,
+    declaration: typeAlias,
+    subjectType: aliasType,
+    hostType: aliasType
+  });
   return {
     ok: true,
     analysis: {
       name,
+      ...metadata !== void 0 && { metadata },
       fields: specializedFields,
       fieldLayouts: specializedFields.map(() => ({})),
       typeRegistry,
@@ -2342,31 +3002,20 @@ function getLeadingParsedTags(node) {
   }
   return parsedTags;
 }
-function findDiscriminatorProperty(node, fieldName) {
-  if (ts3.isClassDeclaration(node)) {
-    for (const member of node.members) {
-      if (ts3.isPropertyDeclaration(member) && ts3.isIdentifier(member.name) && member.name.text === fieldName) {
-        return member;
-      }
-    }
-    return null;
-  }
-  if (ts3.isInterfaceDeclaration(node)) {
-    for (const member of node.members) {
-      if (ts3.isPropertySignature(member) && ts3.isIdentifier(member.name) && member.name.text === fieldName) {
-        return member;
-      }
-    }
+function resolveDiscriminatorProperty(node, checker, fieldName) {
+  const subjectType = checker.getTypeAtLocation(node);
+  const propertySymbol = subjectType.getProperty(fieldName);
+  if (propertySymbol === void 0) {
     return null;
   }
-  if (ts3.isTypeLiteralNode(node.type)) {
-    for (const member of node.type.members) {
-      if (ts3.isPropertySignature(member) && ts3.isIdentifier(member.name) && member.name.text === fieldName) {
-        return member;
-      }
-    }
-  }
-  return null;
+  const declaration = propertySymbol.valueDeclaration ?? propertySymbol.declarations?.find(
+    (candidate) => ts3.isPropertyDeclaration(candidate) || ts3.isPropertySignature(candidate)
+  ) ?? propertySymbol.declarations?.[0];
+  return {
+    declaration,
+    type: checker.getTypeOfSymbolAtLocation(propertySymbol, declaration ?? node),
+    optional: !!(propertySymbol.flags & ts3.SymbolFlags.Optional) || declaration !== void 0 && "questionToken" in declaration && declaration.questionToken !== void 0
+  };
 }
 function isLocalTypeParameterName(node, typeParameterName) {
   return node.typeParameters?.some((typeParameter) => typeParameter.name.text === typeParameterName) ?? false;
@@ -2459,8 +3108,8 @@ function validateDiscriminatorDirective(node, checker, file, diagnostics) {
     );
     return null;
   }
-  const propertyDecl = findDiscriminatorProperty(node, directive.fieldName);
-  if (propertyDecl === null) {
+  const property = resolveDiscriminatorProperty(node, checker, directive.fieldName);
+  if (property === null) {
     diagnostics.push(
       makeAnalysisDiagnostic(
         "UNKNOWN_PATH_TARGET",
@@ -2470,36 +3119,35 @@ function validateDiscriminatorDirective(node, checker, file, diagnostics) {
     );
     return null;
   }
-  if (propertyDecl.questionToken !== void 0) {
+  if (property.optional) {
     diagnostics.push(
       makeAnalysisDiagnostic(
         "TYPE_MISMATCH",
         `Discriminator field "${directive.fieldName}" must be required; optional discriminator fields are not supported.`,
         directive.provenance,
-        [provenanceForNode(propertyDecl, file)]
+        property.declaration !== void 0 ? [provenanceForNode(property.declaration, file)] : []
       )
     );
     return null;
   }
-  const propertyType = checker.getTypeAtLocation(propertyDecl);
-  if (isNullishSemanticType(propertyType)) {
+  if (isNullishSemanticType(property.type)) {
     diagnostics.push(
       makeAnalysisDiagnostic(
         "TYPE_MISMATCH",
         `Discriminator field "${directive.fieldName}" must not be nullable.`,
         directive.provenance,
-        [provenanceForNode(propertyDecl, file)]
+        property.declaration !== void 0 ? [provenanceForNode(property.declaration, file)] : []
       )
     );
     return null;
   }
-  if (!isStringLikeSemanticType(propertyType)) {
+  if (!isStringLikeSemanticType(property.type)) {
     diagnostics.push(
       makeAnalysisDiagnostic(
         "TYPE_MISMATCH",
         `Discriminator field "${directive.fieldName}" must be string-like.`,
         directive.provenance,
-        [provenanceForNode(propertyDecl, file)]
+        property.declaration !== void 0 ? [provenanceForNode(property.declaration, file)] : []
       )
     );
     return null;
@@ -2520,25 +3168,58 @@ function getConcreteTypeArgumentForDiscriminator(node, subjectType, checker, typ
   const localTypeParameter = node.typeParameters?.[typeParameterIndex];
   return localTypeParameter === void 0 ? null : checker.getTypeAtLocation(localTypeParameter);
 }
-function extractDeclarationApiName(node) {
-  for (const tag of getLeadingParsedTags(node)) {
-    if (tag.normalizedTagName !== "apiName") {
-      continue;
-    }
-    if (tag.target === null && tag.argumentText.trim() !== "") {
-      return tag.argumentText.trim();
-    }
-    if (tag.target?.kind === "variant" && tag.target.rawText === "singular") {
-      const value = tag.argumentText.trim();
-      if (value !== "") {
-        return value;
-      }
+function resolveLiteralDiscriminatorPropertyValue(boundType, fieldName, checker, provenance, diagnostics) {
+  const propertySymbol = boundType.getProperty(fieldName);
+  if (propertySymbol === void 0) {
+    return void 0;
+  }
+  const declaration = propertySymbol.valueDeclaration ?? propertySymbol.declarations?.[0];
+  const anchorNode = declaration ?? boundType.symbol.declarations?.[0] ?? null;
+  const resolvedAnchorNode = anchorNode ?? resolveNamedDiscriminatorDeclaration(boundType, checker);
+  if (resolvedAnchorNode === null) {
+    return void 0;
+  }
+  const propertyType = checker.getTypeOfSymbolAtLocation(
+    propertySymbol,
+    resolvedAnchorNode
+  );
+  if (propertyType.isStringLiteral()) {
+    return propertyType.value;
+  }
+  if (propertyType.isUnion()) {
+    const nonNullMembers = propertyType.types.filter(
+      (member) => !(member.flags & (ts3.TypeFlags.Null | ts3.TypeFlags.Undefined))
+    );
+    if (nonNullMembers.length > 0 && nonNullMembers.every((member) => member.isStringLiteral())) {
+      diagnostics.push(
+        makeAnalysisDiagnostic(
+          "INVALID_TAG_ARGUMENT",
+          "Discriminator resolution for union-valued identity properties is out of scope for v1.",
+          provenance
+        )
+      );
+      return null;
     }
   }
-  return null;
+  return void 0;
 }
-function inferJsonFacingName(name) {
-  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
+function resolveDiscriminatorApiName(boundType, checker, metadataPolicy) {
+  const declaration = resolveNamedDiscriminatorDeclaration(boundType, checker);
+  if (declaration === null) {
+    return void 0;
+  }
+  const metadata = resolveNodeMetadata(
+    metadataPolicy,
+    "type",
+    getDiscriminatorLogicalName(boundType, declaration, checker),
+    declaration,
+    {
+      checker,
+      declaration,
+      subjectType: boundType
+    }
+  );
+  return metadata?.apiName;
 }
 function resolveNamedDiscriminatorDeclaration(type, checker, seen = /* @__PURE__ */ new Set()) {
   if (seen.has(type)) {
@@ -2565,7 +3246,7 @@ function resolveNamedDiscriminatorDeclaration(type, checker, seen = /* @__PURE__
   }
   return null;
 }
-function resolveDiscriminatorValue(boundType, checker, provenance, diagnostics) {
+function resolveDiscriminatorValue(boundType, fieldName, checker, provenance, diagnostics, metadataPolicy) {
   if (boundType === null) {
     diagnostics.push(
       makeAnalysisDiagnostic(
@@ -2594,9 +3275,22 @@ function resolveDiscriminatorValue(boundType, checker, provenance, diagnostics)
       return null;
     }
   }
-  const declaration = resolveNamedDiscriminatorDeclaration(boundType, checker);
-  if (declaration !== null) {
-    return extractDeclarationApiName(declaration) ?? inferJsonFacingName(getDeclarationName(declaration));
+  const literalIdentityValue = resolveLiteralDiscriminatorPropertyValue(
+    boundType,
+    fieldName,
+    checker,
+    provenance,
+    diagnostics
+  );
+  if (literalIdentityValue !== void 0) {
+    return literalIdentityValue;
+  }
+  const apiName = resolveDiscriminatorApiName(boundType, checker, metadataPolicy);
+  if (apiName?.source === "explicit") {
+    return apiName.value;
+  }
+  if (apiName?.source === "inferred") {
+    return apiName.value;
   }
   diagnostics.push(
     makeAnalysisDiagnostic(
@@ -2613,7 +3307,15 @@ function getDeclarationName(node) {
   }
   return "anonymous";
 }
-function applyDeclarationDiscriminatorToFields(fields, node, subjectType, checker, file, diagnostics) {
+function getResolvedTypeArguments(type) {
+  return (isTypeReference(type) ? type.typeArguments : void 0) ?? type.aliasTypeArguments ?? [];
+}
+function getDiscriminatorLogicalName(type, declaration, checker) {
+  const baseName = getDeclarationName(declaration);
+  const typeArguments = getResolvedTypeArguments(type);
+  return typeArguments.length === 0 ? baseName : buildInstantiatedReferenceName(baseName, typeArguments, checker);
+}
+function applyDeclarationDiscriminatorToFields(fields, node, subjectType, checker, file, diagnostics, metadataPolicy) {
   const directive = validateDiscriminatorDirective(node, checker, file, diagnostics);
   if (directive === null) {
     return [...fields];
@@ -2625,9 +3327,11 @@ function applyDeclarationDiscriminatorToFields(fields, node, subjectType, checke
       checker,
       directive.typeParameterName
     ),
+    directive.fieldName,
     checker,
     directive.provenance,
-    diagnostics
+    diagnostics,
+    metadataPolicy
   );
   if (discriminatorValue === null) {
     return [...fields];
@@ -2648,7 +3352,7 @@ function buildInstantiatedReferenceName(baseName, typeArguments, checker) {
   ).filter((value) => value !== "");
   return renderedArguments.length === 0 ? baseName : `${baseName}__${renderedArguments.join("__")}`;
 }
-function extractReferenceTypeArguments(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+function extractReferenceTypeArguments(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy, extensionRegistry, diagnostics) {
   const typeNode = sourceNode === void 0 ? void 0 : extractTypeNodeFromSource(sourceNode);
   if (typeNode === void 0) {
     return [];
@@ -2668,13 +3372,14 @@ function extractReferenceTypeArguments(type, checker, file, typeRegistry, visiti
         typeRegistry,
         visiting,
         argumentNode,
+        metadataPolicy,
         extensionRegistry,
         diagnostics
       )
     };
   });
 }
-function applyDiscriminatorToObjectProperties(properties, node, subjectType, checker, file, diagnostics) {
+function applyDiscriminatorToObjectProperties(properties, node, subjectType, checker, file, diagnostics, metadataPolicy) {
   const directive = validateDiscriminatorDirective(node, checker, file, diagnostics);
   if (directive === null) {
     return properties;
@@ -2686,9 +3391,11 @@ function applyDiscriminatorToObjectProperties(properties, node, subjectType, che
       checker,
       directive.typeParameterName
     ),
+    directive.fieldName,
     checker,
     directive.provenance,
-    diagnostics
+    diagnostics,
+    metadataPolicy
   );
   if (discriminatorValue === null) {
     return properties;
@@ -2703,7 +3410,7 @@ function applyDiscriminatorToObjectProperties(properties, node, subjectType, che
     } : property
   );
 }
-function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnostics, hostType, extensionRegistry) {
+function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnostics, hostType, metadataPolicy, extensionRegistry) {
   if (!ts3.isIdentifier(prop.name)) {
     return null;
   }
@@ -2718,6 +3425,7 @@ function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnosti
     typeRegistry,
     visiting,
     prop,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   );
@@ -2741,9 +3449,16 @@ function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnosti
     annotations.push(defaultAnnotation);
   }
   ({ type, annotations } = applyEnumMemberDisplayNames(type, annotations));
+  const metadata = resolveNodeMetadata(metadataPolicy, "field", name, prop, {
+    checker,
+    declaration: prop,
+    subjectType: tsType,
+    hostType
+  });
   return {
     kind: "field",
     name,
+    ...metadata !== void 0 && { metadata },
     type,
     required: !optional,
     constraints,
@@ -2751,7 +3466,7 @@ function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnosti
     provenance
   };
 }
-function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visiting, diagnostics, hostType, extensionRegistry) {
+function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visiting, diagnostics, hostType, metadataPolicy, extensionRegistry) {
   if (!ts3.isIdentifier(prop.name)) {
     return null;
   }
@@ -2766,6 +3481,7 @@ function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visitin
     typeRegistry,
     visiting,
     prop,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   );
@@ -2785,9 +3501,16 @@ function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visitin
   let annotations = [];
   annotations.push(...docResult.annotations);
   ({ type, annotations } = applyEnumMemberDisplayNames(type, annotations));
+  const metadata = resolveNodeMetadata(metadataPolicy, "field", name, prop, {
+    checker,
+    declaration: prop,
+    subjectType: tsType,
+    hostType
+  });
   return {
     kind: "field",
     name,
+    ...metadata !== void 0 && { metadata },
     type,
     required: !optional,
     constraints,
@@ -2912,7 +3635,7 @@ function getTypeNodeRegistrationName(typeNode) {
   }
   return null;
 }
-function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   const customType = resolveRegisteredCustomType(sourceNode, extensionRegistry, checker);
   if (customType) {
     return customType;
@@ -2924,6 +3647,7 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
     typeRegistry,
     visiting,
     sourceNode,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   );
@@ -2968,6 +3692,7 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
       typeRegistry,
       visiting,
       sourceNode,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     );
@@ -2980,6 +3705,7 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
       typeRegistry,
       visiting,
       sourceNode,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     );
@@ -2992,13 +3718,14 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
       typeRegistry,
       visiting,
       sourceNode,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     );
   }
   return { kind: "primitive", primitiveKind: "string" };
 }
-function tryResolveNamedPrimitiveAlias(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+function tryResolveNamedPrimitiveAlias(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   if (!(type.flags & (ts3.TypeFlags.String | ts3.TypeFlags.Number | ts3.TypeFlags.BigInt | ts3.TypeFlags.BigIntLiteral | ts3.TypeFlags.Boolean | ts3.TypeFlags.Null))) {
     return null;
   }
@@ -3018,14 +3745,21 @@ function tryResolveNamedPrimitiveAlias(type, checker, file, typeRegistry, visiti
       file,
       makeParseOptions(extensionRegistry)
     );
+    const metadata = resolveNodeMetadata(metadataPolicy, "type", aliasName, aliasDecl, {
+      checker,
+      declaration: aliasDecl,
+      subjectType: aliasType
+    });
     typeRegistry[aliasName] = {
       name: aliasName,
+      ...metadata !== void 0 && { metadata },
       type: resolveAliasedPrimitiveTarget(
         aliasType,
         checker,
         file,
         typeRegistry,
         visiting,
+        metadataPolicy,
         extensionRegistry,
         diagnostics
       ),
@@ -3054,7 +3788,7 @@ function shouldEmitPrimitiveAliasDefinition(typeNode, checker) {
   const resolved = checker.getTypeFromTypeNode(aliasDecl.type);
   return !!(resolved.flags & (ts3.TypeFlags.String | ts3.TypeFlags.Number | ts3.TypeFlags.BigInt | ts3.TypeFlags.BigIntLiteral | ts3.TypeFlags.Boolean | ts3.TypeFlags.Null));
 }
-function resolveAliasedPrimitiveTarget(type, checker, file, typeRegistry, visiting, extensionRegistry, diagnostics) {
+function resolveAliasedPrimitiveTarget(type, checker, file, typeRegistry, visiting, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   const nestedAliasDecl = type.aliasSymbol?.declarations?.find(ts3.isTypeAliasDeclaration);
   if (nestedAliasDecl !== void 0) {
     return resolveAliasedPrimitiveTarget(
@@ -3063,6 +3797,7 @@ function resolveAliasedPrimitiveTarget(type, checker, file, typeRegistry, visiti
       file,
       typeRegistry,
       visiting,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     );
@@ -3074,11 +3809,12 @@ function resolveAliasedPrimitiveTarget(type, checker, file, typeRegistry, visiti
     typeRegistry,
     visiting,
     void 0,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   );
 }
-function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   const typeName = getNamedTypeName(type);
   const namedDecl = getNamedTypeDeclaration(type);
   if (typeName && typeName in typeRegistry) {
@@ -3113,8 +3849,14 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
       return result;
     }
     const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
+    const metadata = namedDecl !== void 0 ? resolveNodeMetadata(metadataPolicy, "type", typeName, namedDecl, {
+      checker,
+      declaration: namedDecl,
+      subjectType: type
+    }) : void 0;
     typeRegistry[typeName] = {
       name: typeName,
+      ...metadata !== void 0 && { metadata },
       type: result,
       ...annotations !== void 0 && annotations.length > 0 && { annotations },
       provenance: provenanceForDeclaration(namedDecl ?? sourceNode, file)
@@ -3168,6 +3910,7 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
       typeRegistry,
       visiting,
       nonNullMembers[0].sourceNode ?? sourceNode,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     );
@@ -3185,6 +3928,7 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
       typeRegistry,
       visiting,
       memberSourceNode ?? sourceNode,
+      metadataPolicy,
       extensionRegistry,
       diagnostics
     )
@@ -3194,7 +3938,7 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
   }
   return registerNamed({ kind: "union", members });
 }
-function resolveArrayType(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+function resolveArrayType(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   const typeArgs = isTypeReference(type) ? type.typeArguments : void 0;
   const elementType = typeArgs?.[0];
   const elementSourceNode = extractArrayElementTypeNode(sourceNode, checker);
@@ -3205,12 +3949,13 @@ function resolveArrayType(type, checker, file, typeRegistry, visiting, sourceNod
     typeRegistry,
     visiting,
     elementSourceNode,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   ) : { kind: "primitive", primitiveKind: "string" };
   return { kind: "array", items };
 }
-function tryResolveRecordType(type, checker, file, typeRegistry, visiting, extensionRegistry, diagnostics) {
+function tryResolveRecordType(type, checker, file, typeRegistry, visiting, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   if (type.getProperties().length > 0) {
     return null;
   }
@@ -3225,6 +3970,7 @@ function tryResolveRecordType(type, checker, file, typeRegistry, visiting, exten
     typeRegistry,
     visiting,
     void 0,
+    metadataPolicy,
     extensionRegistry,
     diagnostics
   );
@@ -3255,7 +4001,22 @@ function typeNodeContainsReference(type, targetName) {
     }
   }
 }
-function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+function shouldEmitResolvedObjectProperty(property, declaration) {
+  if (property.name.startsWith("__@")) {
+    return false;
+  }
+  if (declaration !== void 0 && "name" in declaration && declaration.name !== void 0) {
+    const name = declaration.name;
+    if (ts3.isComputedPropertyName(name) || ts3.isPrivateIdentifier(name)) {
+      return false;
+    }
+    if (!ts3.isIdentifier(name) && !ts3.isStringLiteral(name) && !ts3.isNumericLiteral(name)) {
+      return false;
+    }
+  }
+  return true;
+}
+function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNode, metadataPolicy = normalizeMetadataPolicy(void 0), extensionRegistry, diagnostics) {
   const collectedDiagnostics = diagnostics ?? [];
   const typeName = getNamedTypeName(type);
   const namedTypeName = typeName ?? void 0;
@@ -3267,6 +4028,7 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNo
     typeRegistry,
     visiting,
     sourceNode,
+    metadataPolicy,
     extensionRegistry,
     collectedDiagnostics
   );
@@ -3317,6 +4079,7 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNo
     file,
     typeRegistry,
     visiting,
+    metadataPolicy,
     extensionRegistry,
     collectedDiagnostics
   );
@@ -3329,8 +4092,14 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNo
         return recordNode;
       }
       const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
+      const metadata = namedDecl !== void 0 ? resolveNodeMetadata(metadataPolicy, "type", registryTypeName, namedDecl, {
+        checker,
+        declaration: namedDecl,
+        subjectType: type
+      }) : void 0;
       typeRegistry[registryTypeName] = {
         name: registryTypeName,
+        ...metadata !== void 0 && { metadata },
         type: recordNode,
         ...annotations !== void 0 && annotations.length > 0 && { annotations },
         provenance: provenanceForDeclaration(namedDecl, file)
@@ -3350,12 +4119,14 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNo
     file,
     typeRegistry,
     visiting,
+    metadataPolicy,
     collectedDiagnostics,
     extensionRegistry
   );
   for (const prop of type.getProperties()) {
     const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
     if (!declaration) continue;
+    if (!shouldEmitResolvedObjectProperty(prop, declaration)) continue;
     const propType = checker.getTypeOfSymbolAtLocation(prop, declaration);
     const optional = !!(prop.flags & ts3.SymbolFlags.Optional);
     const propTypeNode = resolveTypeNode(
@@ -3365,12 +4136,14 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNo
       typeRegistry,
       visiting,
       declaration,
+      metadataPolicy,
       extensionRegistry,
       collectedDiagnostics
     );
     const fieldNodeInfo = fieldInfoMap?.get(prop.name);
     properties.push({
       name: prop.name,
+      ...fieldNodeInfo?.metadata !== void 0 && { metadata: fieldNodeInfo.metadata },
       type: propTypeNode,
       optional,
       constraints: fieldNodeInfo?.constraints ?? [],
@@ -3387,14 +4160,21 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNo
       type,
       checker,
       file,
-      collectedDiagnostics
+      collectedDiagnostics,
+      metadataPolicy
     ) : properties,
     additionalProperties: true
   };
   if (registryTypeName !== void 0 && shouldRegisterNamedType) {
     const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
+    const metadata = namedDecl !== void 0 ? resolveNodeMetadata(metadataPolicy, "type", registryTypeName, namedDecl, {
+      checker,
+      declaration: namedDecl,
+      subjectType: type
+    }) : void 0;
     typeRegistry[registryTypeName] = {
       name: registryTypeName,
+      ...metadata !== void 0 && { metadata },
       type: objectNode,
       ...annotations !== void 0 && annotations.length > 0 && { annotations },
       provenance: provenanceForDeclaration(namedDecl, file)
@@ -3407,7 +4187,7 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNo
   }
   return objectNode;
 }
-function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting, diagnostics, extensionRegistry) {
+function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting, metadataPolicy, diagnostics, extensionRegistry) {
   const symbols = [type.getSymbol(), type.aliasSymbol].filter(
     (s) => s?.declarations != null && s.declarations.length > 0
   );
@@ -3428,10 +4208,12 @@ function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visitin
             visiting,
             diagnostics,
             hostType,
+            metadataPolicy,
             extensionRegistry
           );
           if (fieldNode) {
             map.set(fieldNode.name, {
+              ...fieldNode.metadata !== void 0 && { metadata: fieldNode.metadata },
               constraints: [...fieldNode.constraints],
               annotations: [...fieldNode.annotations],
               provenance: fieldNode.provenance
@@ -3449,6 +4231,7 @@ function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visitin
         file,
         typeRegistry,
         visiting,
+        metadataPolicy,
         checker.getTypeAtLocation(interfaceDecl),
         diagnostics,
         extensionRegistry
@@ -3462,6 +4245,7 @@ function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visitin
         file,
         typeRegistry,
         visiting,
+        metadataPolicy,
         checker.getTypeAtLocation(typeAliasDecl),
         diagnostics,
         extensionRegistry
@@ -3513,7 +4297,7 @@ function isNullishTypeNode(typeNode) {
   }
   return ts3.isLiteralTypeNode(typeNode) && (typeNode.literal.kind === ts3.SyntaxKind.NullKeyword || typeNode.literal.kind === ts3.SyntaxKind.UndefinedKeyword);
 }
-function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting, hostType, diagnostics, extensionRegistry) {
+function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting, metadataPolicy, hostType, diagnostics, extensionRegistry) {
   const map = /* @__PURE__ */ new Map();
   for (const member of members) {
     if (ts3.isPropertySignature(member)) {
@@ -3525,10 +4309,12 @@ function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting, h
         visiting,
         diagnostics,
         hostType,
+        metadataPolicy,
         extensionRegistry
       );
       if (fieldNode) {
         map.set(fieldNode.name, {
+          ...fieldNode.metadata !== void 0 && { metadata: fieldNode.metadata },
           constraints: [...fieldNode.constraints],
           annotations: [...fieldNode.annotations],
           provenance: fieldNode.provenance
@@ -3559,6 +4345,7 @@ function extractTypeAliasConstraintNodes(typeNode, checker, file, extensionRegis
     {},
     /* @__PURE__ */ new Set(),
     aliasDecl.type,
+    void 0,
     extensionRegistry
   );
   const constraints = extractJSDocConstraintNodes(
@@ -3744,19 +4531,37 @@ function findInterfaceByName(sourceFile, interfaceName) {
 function findTypeAliasByName(sourceFile, aliasName) {
   return findNodeByName(sourceFile, aliasName, ts4.isTypeAliasDeclaration, (n) => n.name.text);
 }
-function analyzeNamedTypeToIR(filePath, typeName, extensionRegistry) {
+function analyzeNamedTypeToIR(filePath, typeName, extensionRegistry, metadataPolicy) {
   const ctx = createProgramContext(filePath);
-  return analyzeNamedTypeToIRFromProgramContext(ctx, filePath, typeName, extensionRegistry);
+  return analyzeNamedTypeToIRFromProgramContext(
+    ctx,
+    filePath,
+    typeName,
+    extensionRegistry,
+    metadataPolicy
+  );
 }
-function analyzeNamedTypeToIRFromProgramContext(ctx, filePath, typeName, extensionRegistry) {
+function analyzeNamedTypeToIRFromProgramContext(ctx, filePath, typeName, extensionRegistry, metadataPolicy) {
   const analysisFilePath = path.resolve(filePath);
   const classDecl = findClassByName(ctx.sourceFile, typeName);
   if (classDecl !== null) {
-    return analyzeClassToIR(classDecl, ctx.checker, analysisFilePath, extensionRegistry);
+    return analyzeClassToIR(
+      classDecl,
+      ctx.checker,
+      analysisFilePath,
+      extensionRegistry,
+      metadataPolicy
+    );
   }
   const interfaceDecl = findInterfaceByName(ctx.sourceFile, typeName);
   if (interfaceDecl !== null) {
-    return analyzeInterfaceToIR(interfaceDecl, ctx.checker, analysisFilePath, extensionRegistry);
+    return analyzeInterfaceToIR(
+      interfaceDecl,
+      ctx.checker,
+      analysisFilePath,
+      extensionRegistry,
+      metadataPolicy
+    );
   }
   const typeAlias = findTypeAliasByName(ctx.sourceFile, typeName);
   if (typeAlias !== null) {
@@ -3764,7 +4569,8 @@ function analyzeNamedTypeToIRFromProgramContext(ctx, filePath, typeName, extensi
       typeAlias,
       ctx.checker,
       analysisFilePath,
-      extensionRegistry
+      extensionRegistry,
+      metadataPolicy
     );
     if (result.ok) {
       return result.analysis;
@@ -3857,7 +4663,11 @@ function generateClassSchemas(analysis, source, options) {
   if (errorDiagnostics !== void 0 && errorDiagnostics.length > 0) {
     throw new Error(formatValidationError(errorDiagnostics));
   }
-  const ir = canonicalizeTSDoc(analysis, source);
+  const ir = canonicalizeTSDoc(
+    analysis,
+    source,
+    options?.metadata !== void 0 ? { metadata: options.metadata } : void 0
+  );
   const validationResult = validateIR(ir, {
     ...options?.extensionRegistry !== void 0 && {
       extensionRegistry: options.extensionRegistry
@@ -3894,13 +4704,15 @@ function generateSchemasFromClass(options) {
     classDecl,
     ctx.checker,
     options.filePath,
-    options.extensionRegistry
+    options.extensionRegistry,
+    options.metadata
   );
   return generateClassSchemas(
     analysis,
     { file: options.filePath },
     {
       extensionRegistry: options.extensionRegistry,
+      metadata: options.metadata,
       vendorPrefix: options.vendorPrefix
     }
   );
@@ -3918,13 +4730,15 @@ function generateSchemasFromProgram(options) {
     ctx,
     options.filePath,
     options.typeName,
-    options.extensionRegistry
+    options.extensionRegistry,
+    options.metadata
   );
   return generateClassSchemas(
     analysis,
     { file: options.filePath },
     {
       extensionRegistry: options.extensionRegistry,
+      metadata: options.metadata,
       vendorPrefix: options.vendorPrefix
     }
   );
@@ -3933,16 +4747,28 @@ function generateSchemasFromProgram(options) {
 // src/generators/mixed-authoring.ts
 function buildMixedAuthoringSchemas(options) {
   const { filePath, typeName, overlays, ...schemaOptions } = options;
-  const analysis = analyzeNamedTypeToIR(filePath, typeName, schemaOptions.extensionRegistry);
-  const composedAnalysis = composeAnalysisWithOverlays(analysis, overlays);
-  const ir = canonicalizeTSDoc(composedAnalysis, { file: filePath });
+  const analysis = analyzeNamedTypeToIR(
+    filePath,
+    typeName,
+    schemaOptions.extensionRegistry,
+    schemaOptions.metadata
+  );
+  const composedAnalysis = composeAnalysisWithOverlays(analysis, overlays, schemaOptions.metadata);
+  const ir = canonicalizeTSDoc(
+    composedAnalysis,
+    { file: filePath },
+    schemaOptions.metadata !== void 0 ? { metadata: schemaOptions.metadata } : void 0
+  );
   return {
     jsonSchema: generateJsonSchemaFromIR(ir, schemaOptions),
     uiSchema: generateUiSchemaFromIR(ir)
   };
 }
-function composeAnalysisWithOverlays(analysis, overlays) {
-  const overlayIR = canonicalizeChainDSL(overlays);
+function composeAnalysisWithOverlays(analysis, overlays, metadata) {
+  const overlayIR = canonicalizeChainDSL(
+    overlays,
+    metadata !== void 0 ? { metadata } : void 0
+  );
   const overlayFields = collectOverlayFields(overlayIR.elements);
   if (overlayFields.length === 0) {
     return analysis;
@@ -3998,8 +4824,10 @@ function collectOverlayFields(elements) {
 }
 function mergeFieldOverlay(baseField, overlayField, typeRegistry) {
   assertSupportedOverlayField(baseField, overlayField);
+  const metadata = mergeResolvedMetadata(baseField.metadata, overlayField.metadata);
   return {
     ...baseField,
+    ...metadata !== void 0 && { metadata },
     type: mergeFieldType(baseField, overlayField, typeRegistry),
     annotations: mergeAnnotations(baseField.annotations, overlayField.annotations)
   };
@@ -4110,12 +4938,12 @@ function annotationKey(annotation) {
 function buildFormSchemas(form, options) {
   return {
     jsonSchema: generateJsonSchema(form, options),
-    uiSchema: generateUiSchema(form)
+    uiSchema: generateUiSchema(form, options)
   };
 }
 function writeSchemas(form, options) {
-  const { outDir, name = "schema", indent = 2, vendorPrefix } = options;
-  const buildOptions = vendorPrefix === void 0 ? void 0 : { vendorPrefix };
+  const { outDir, name = "schema", indent = 2, vendorPrefix, metadata } = options;
+  const buildOptions = vendorPrefix === void 0 && metadata === void 0 ? void 0 : { vendorPrefix, metadata };
   const { jsonSchema, uiSchema: uiSchema2 } = buildFormSchemas(form, buildOptions);
   if (!fs.existsSync(outDir)) {
     fs.mkdirSync(outDir, { recursive: true });