@workos/oagen-emitters 0.18.2 → 0.18.4

package/src/php/index.ts

@@ -19,6 +19,7 @@ import { generateTests } from './tests.js';
 import { buildOperationsMap } from './manifest.js';
 import { initializeEnumDedup } from './naming.js';
 import { enrichModelsFromSpec, getSyntheticEnums } from '../shared/model-utils.js';
+import { AUTOGEN_NOTICE } from '../shared/file-header.js';
 
 /** Initialize enum deduplication from spec data. */
 function ensureNamingInitialized(ctx: EmitterContext): void {
@@ -100,7 +101,7 @@ export const phpEmitter: Emitter = {
   },
 
   fileHeader(): string {
-    return '<?php\n\ndeclare(strict_types=1);\n\n// This file is auto-generated by oagen. Do not edit.';
+    return `<?php\n\ndeclare(strict_types=1);\n\n// ${AUTOGEN_NOTICE}`;
   },
 
   formatCommand(targetDir: string): FormatCommand | null {

package/src/php/models.ts

@@ -1,6 +1,6 @@
 import type { Model, TypeRef, EmitterContext, GeneratedFile } from '@workos/oagen';
 import { mapTypeRef, mapTypeRefForPHPDoc } from './type-map.js';
-import { className, enumClassName, fieldName } from './naming.js';
+import { className, enumClassName, domainFieldName } from './naming.js';
 import { phpDocComment } from './utils.js';
 
 // Import and re-export shared model detection utilities
@@ -67,7 +67,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     // Deduplicate fields that map to the same PHP name
     const seenNames = new Set<string>();
     const allFields = [...requiredFields, ...optionalFields].filter((f) => {
-      const phpName = fieldName(f.name);
+      // DOMAIN identifier: the PHP property name (honors a `domainName` override).
+      const phpName = domainFieldName(f);
       if (seenNames.has(phpName)) return false;
       seenNames.add(phpName);
       return true;
@@ -75,7 +76,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
 
     for (let i = 0; i < allFields.length; i++) {
       const field = allFields[i];
-      const phpName = fieldName(field.name);
+      // DOMAIN identifier: the promoted constructor property name.
+      const phpName = domainFieldName(field);
       const phpType = mapTypeRef(field.type);
       const isOptional = !field.required;
       const comma = i < allFields.length - 1 ? ',' : ',';
@@ -108,7 +110,9 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     lines.push(`        return new self(`);
     for (let i = 0; i < allFields.length; i++) {
       const field = allFields[i];
-      const phpName = fieldName(field.name);
+      // DOMAIN identifier: the named constructor argument (PHP property).
+      const phpName = domainFieldName(field);
+      // WIRE key: the JSON key read from `$data[...]` (stays `field.name`).
       const wireName = field.name;
       const comma = i < allFields.length - 1 ? ',' : ',';
       const accessor = generateFromArrayAccessor(field.type, wireName, field.required);
@@ -124,7 +128,9 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     lines.push('    {');
     lines.push('        return [');
     for (const field of allFields) {
-      const phpName = fieldName(field.name);
+      // DOMAIN identifier: the `$this->...` property being serialized.
+      const phpName = domainFieldName(field);
+      // WIRE key: the JSON key emitted into the array (stays `field.name`).
       const wireName = field.name;
       const serialized = generateToArrayValue(field.type, `$this->${phpName}`, !field.required);
       lines.push(`            '${wireName}' => ${serialized},`);

package/src/php/naming.ts

@@ -138,6 +138,16 @@ export function fieldName(name: string): string {
   return toCamelCase(name);
 }
 
+/**
+ * camelCase DOMAIN property name for a model field, honoring a `domainName`
+ * override (set via the `fieldHints` config) so a wire field can surface under
+ * a friendlier PHP property name. The wire key (see {@link wireName}) still
+ * derives from `field.name`. No-op when `domainName` is unset.
+ */
+export function domainFieldName(field: { name: string; domainName?: string }): string {
+  return fieldName(field.domainName ?? field.name);
+}
+
 /** snake_case name for fixtures and other snake_case contexts. */
 export function snakeName(name: string): string {
   return toSnakeCase(stripUrnPrefix(name));

package/src/php/tests.ts

@@ -8,7 +8,14 @@ import type {
   ResolvedOperation,
 } from '@workos/oagen';
 import { planOperation, toCamelCase, toPascalCase } from '@workos/oagen';
-import { className, enumClassName, resolveMethodName, snakeName, servicePropertyName } from './naming.js';
+import {
+  className,
+  enumClassName,
+  resolveMethodName,
+  snakeName,
+  servicePropertyName,
+  domainFieldName,
+} from './naming.js';
 import { isListWrapperModel } from './models.js';
 import { generateFixtures } from './fixtures.js';
 import {
@@ -503,7 +510,9 @@ function emitFieldHydrationAssertions(
 
   for (const f of assertFields) {
     if (!f) continue;
-    const phpProp = toCamelCase(f.name);
+    // DOMAIN identifier: the deserialized model's PHP property (honors `domainName`).
+    // The fixture key `f.name` is the WIRE key and stays unchanged.
+    const phpProp = domainFieldName(f);
     lines.push(`        $this->assertSame(${fixtureVar}['${f.name}'], ${resultVar}->${phpProp});`);
   }
 }

package/src/python/fixtures.ts

@@ -1,6 +1,6 @@
 import type { Model, TypeRef, Enum } from '@workos/oagen';
 
-import { fileName, fieldName } from './naming.js';
+import { fileName, domainFieldName } from './naming.js';
 import { isListMetadataModel, isListWrapperModel } from './models.js';
 import { collectNonPaginatedResponseModelNames, collectReferencedListMetadataModels } from '../shared/model-utils.js';
 
@@ -104,10 +104,11 @@ export function generateModelFixture(
 ): Record<string, any> {
   const fixture: Record<string, any> = {};
 
-  // Deduplicate fields by snake_case name (matching model generation in models.ts)
+  // Deduplicate fields by DOMAIN identifier (matching model generation in
+  // models.ts, which honors `domainName`); the wire key below stays `field.name`.
   const seenFieldNames = new Set<string>();
   const deduplicatedFields = model.fields.filter((f) => {
-    const pyName = fieldName(f.name);
+    const pyName = domainFieldName(f);
     if (seenFieldNames.has(pyName)) return false;
     seenFieldNames.add(pyName);
     return true;

package/src/python/index.ts

@@ -11,6 +11,7 @@ import type {
 
 import { generateModels } from './models.js';
 import { detectDiscriminators } from '../shared/model-utils.js';
+import { AUTOGEN_NOTICE } from '../shared/file-header.js';
 import { generateEnums } from './enums.js';
 import { generateResources } from './resources.js';
 import { generateClient } from './client.js';
@@ -86,7 +87,7 @@ export const pythonEmitter: Emitter = {
   },
 
   fileHeader(): string {
-    return '# This file is auto-generated by oagen. Do not edit.';
+    return `# ${AUTOGEN_NOTICE}`;
   },
 
   formatCommand(_targetDir: string): FormatCommand | null {

package/src/python/models.ts

@@ -1,7 +1,7 @@
 import type { Model, EmitterContext, GeneratedFile } from '@workos/oagen';
 import { collectFieldDependencies, walkTypeRef } from '@workos/oagen';
 import { mapTypeRef } from './type-map.js';
-import { className, fieldName, fileName, buildMountDirMap, dirToModule } from './naming.js';
+import { className, domainFieldName, fileName, buildMountDirMap, dirToModule } from './naming.js';
 import { collectGeneratedEnumSymbolsByDir } from './enums.js';
 import { computeSchemaPlacement } from './shared-schemas.js';
 
@@ -232,7 +232,9 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     // Deduplicate fields that map to the same snake_case name
     const seenFieldNames = new Set<string>();
     const deduplicatedFields = model.fields.filter((f) => {
-      const pyName = fieldName(f.name);
+      // Dedup on the DOMAIN identifier (the dataclass attribute name), which
+      // honors a `domainName` override; the wire key stays `field.name`.
+      const pyName = domainFieldName(f);
       if (seenFieldNames.has(pyName)) return false;
       seenFieldNames.add(pyName);
       return true;
@@ -343,7 +345,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     };
 
     for (const field of requiredFields) {
-      const pyFieldName = fieldName(field.name);
+      // DOMAIN identifier: the dataclass attribute name (honors `domainName`).
+      const pyFieldName = domainFieldName(field);
       const pyType = rewriteDiscriminatorType(resolveModelFieldType(field.type));
       if (field.description || field.deprecated) {
         const parts: string[] = [];
@@ -357,7 +360,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     }
 
     for (const field of optionalFields) {
-      const pyFieldName = fieldName(field.name);
+      // DOMAIN identifier: the dataclass attribute name (honors `domainName`).
+      const pyFieldName = domainFieldName(field);
       const innerType =
         field.type.kind === 'nullable' ? resolveModelFieldType(field.type.inner) : resolveModelFieldType(field.type);
       const pyType = `Optional[${rewriteDiscriminatorType(innerType)}]`;
@@ -383,7 +387,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     const fieldAssignmentLines: string[] = [];
 
     for (const field of [...requiredFields, ...optionalFields]) {
-      const pyFieldName = fieldName(field.name);
+      // DOMAIN identifier (LHS of `cls(...)`); the wire key below stays `field.name`.
+      const pyFieldName = domainFieldName(field);
       const wireKey = field.name; // Wire keys are snake_case from the spec
       const isRequired = !isOptionalField(model.name, field, ctx);
 
@@ -424,7 +429,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     lines.push('        result: Dict[str, Any] = {}');
 
     for (const field of [...requiredFields, ...optionalFields]) {
-      const pyFieldName = fieldName(field.name);
+      // DOMAIN identifier (`self.<attr>`); the wire key below stays `field.name`.
+      const pyFieldName = domainFieldName(field);
       const wireKey = field.name;
       const isRequired = !isOptionalField(model.name, field, ctx);
 

package/src/python/naming.ts

@@ -50,6 +50,16 @@ export function fieldName(name: string): string {
   return toSnakeCase(name);
 }
 
+/**
+ * snake_case domain field name for a model field, honoring a `domainName`
+ * override (set via the `fieldHints` config) so a wire field can surface under
+ * a friendlier name. The wire name (still derived from `field.name`) is
+ * unaffected, so the API contract is preserved.
+ */
+export function domainFieldName(field: { name: string; domainName?: string }): string {
+  return toSnakeCase(field.domainName ?? field.name);
+}
+
 /**
  * Python builtins that should not be shadowed by parameter names.
  * When a path/query param name collides, suffix with underscore.

package/src/python/tests.ts

@@ -13,6 +13,7 @@ import {
   className,
   fileName,
   fieldName,
+  domainFieldName,
   moduleName,
   resolveMethodName,
   buildMountDirMap,
@@ -1026,12 +1027,13 @@ function pickAssertableFields(
       // Skip strings containing characters that are hard to represent as Python literals
       if (val.includes('"') || val.includes("'") || val.includes('{') || val.includes('\\') || val.includes('\n'))
         continue;
-      results.push({ field: fieldName(f.name), value: `"${val}"` });
+      // DOMAIN identifier: asserted as `result.<attr>` (honors `domainName`).
+      results.push({ field: domainFieldName(f), value: `"${val}"` });
     } else if (typeof val === 'boolean') {
       // Use "is True/False" to satisfy ruff E712
-      results.push({ field: fieldName(f.name), value: val ? 'True' : 'False', isBool: true });
+      results.push({ field: domainFieldName(f), value: val ? 'True' : 'False', isBool: true });
     } else if (typeof val === 'number') {
-      results.push({ field: fieldName(f.name), value: String(val) });
+      results.push({ field: domainFieldName(f), value: String(val) });
     }
   }
   return results;
@@ -1114,7 +1116,9 @@ function buildTestArgs(op: Operation, spec: ApiSpec, hiddenParams?: Set<string>)
       if (plan.hasBody && op.requestBody?.kind === 'model') {
         const rbName = op.requestBody.name;
         const bodyModel = spec.models.find((m) => m.name === rbName);
-        if (bodyModel?.fields.some((f) => fieldName(f.name) === fieldName(param.name))) continue;
+        // Compare the body field's DOMAIN identifier (honors `domainName`)
+        // against the param kwarg name; the param has no domainName override.
+        if (bodyModel?.fields.some((f) => domainFieldName(f) === fieldName(param.name))) continue;
       }
       if (param.required && !pathParamNames.has(fieldName(param.name))) {
         args.push(`${fieldName(param.name)}=${generateTestValue(param.type, param.name)}`);
@@ -1511,10 +1515,11 @@ function generateModelRoundTripTests(spec: ApiSpec, ctx: EmitterContext): Genera
     // don't have a to_dict() and their round-trip semantics differ.
     if (model.fields.length === 0) continue;
     if ((model as any).discriminator) continue;
-    // Deduplicate fields that map to the same snake_case name (mirrors models.ts)
+    // Deduplicate fields by DOMAIN identifier (mirrors models.ts, which honors
+    // `domainName`); the wire key stays `field.name`.
     const seenFieldNames = new Set<string>();
     const dedupFields = model.fields.filter((f) => {
-      const pyName = fieldName(f.name);
+      const pyName = domainFieldName(f);
       if (seenFieldNames.has(pyName)) return false;
       seenFieldNames.add(pyName);
       return true;

package/src/ruby/index.ts

@@ -16,6 +16,7 @@ import { generateTests } from './tests.js';
 import { buildOperationsMap } from './manifest.js';
 import { generateRbiFiles } from './rbi.js';
 import { enrichModelsFromSpec, getSyntheticEnums } from '../shared/model-utils.js';
+import { AUTOGEN_NOTICE } from '../shared/file-header.js';
 
 /** Ensure every generated file's content ends with a trailing newline. */
 function ensureTrailingNewlines(files: GeneratedFile[]): GeneratedFile[] {
@@ -93,7 +94,7 @@ export const rubyEmitter: Emitter = {
   },
 
   fileHeader(): string {
-    return `# frozen_string_literal: true\n\n# This file is auto-generated by oagen. Do not edit.`;
+    return `# frozen_string_literal: true\n\n# ${AUTOGEN_NOTICE}`;
   },
 
   formatCommand(targetDir: string): FormatCommand | null {

package/src/ruby/models.ts

@@ -1,6 +1,6 @@
 import type { Model, EmitterContext, GeneratedFile, TypeRef, Field } from '@workos/oagen';
 import { walkTypeRef, assignModelsToServices } from '@workos/oagen';
-import { className, fieldName, fileName, buildMountDirMap } from './naming.js';
+import { className, domainFieldName, fileName, buildMountDirMap } from './naming.js';
 import {
   isListWrapperModel,
   isListMetadataModel,
@@ -131,7 +131,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     // Deduplicate field names that collide after snake_case.
     const seenFieldNames = new Set<string>();
     const fields = model.fields.filter((f) => {
-      const n = fieldName(f.name);
+      // Dedup on the DOMAIN accessor name (honors fieldHints override).
+      const n = domainFieldName(f);
       if (seenFieldNames.has(n)) return false;
       seenFieldNames.add(n);
       return true;
@@ -151,7 +152,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     lines.push('    HASH_ATTRS = {');
     for (let i = 0; i < fields.length; i++) {
       const field = fields[i];
-      const fname = fieldName(field.name);
+      // DOMAIN attr symbol (honors fieldHints); the key below is the WIRE name.
+      const fname = domainFieldName(field);
       const sep = i === fields.length - 1 ? '' : ',';
       lines.push(`      ${rubyHashLiteralKey(field.name)} :${fname}${sep}`);
     }
@@ -162,14 +164,14 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     if (deprecatedFields.length > 0) {
       for (const f of deprecatedFields) {
         const desc = f.description ? ` ${f.description.split('\n')[0].trim()}` : '';
-        lines.push(`    # @!attribute ${fieldName(f.name)}`);
+        lines.push(`    # @!attribute ${domainFieldName(f)}`);
         lines.push(`    #   @deprecated${desc}`);
       }
       lines.push('');
     }
 
     if (accessorFields.length > 0) {
-      const attrs = accessorFields.map((f) => `:${fieldName(f.name)}`);
+      const attrs = accessorFields.map((f) => `:${domainFieldName(f)}`);
       if (attrs.length === 1) {
         lines.push(`    attr_accessor ${attrs[0]}`);
       } else {
@@ -184,7 +186,7 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
 
     // Emit deprecated field accessors with runtime warnings.
     for (const f of deprecatedFields) {
-      const fname = fieldName(f.name);
+      const fname = domainFieldName(f);
       lines.push(`    def ${fname}`);
       lines.push(
         `      warn "[DEPRECATION] \\\`${fname}\\\` is deprecated and will be removed in a future version.", uplevel: 1`,
@@ -202,7 +204,8 @@ export function generateModels(models: Model[], ctx: EmitterContext): GeneratedF
     lines.push('    def initialize(json)');
     lines.push('      hash = self.class.normalize(json)');
     for (const field of fields) {
-      const fname = fieldName(field.name);
+      // DOMAIN ivar name (honors fieldHints); rawKey is the WIRE key read from the hash.
+      const fname = domainFieldName(field);
       const rawKey = field.name;
       lines.push(`      ${deserializeAssignment(fname, rawKey, field.type, field.required, enumNames, modelNames)}`);
     }

package/src/ruby/naming.ts

@@ -57,6 +57,16 @@ export function fieldName(name: string): string {
   return toSnakeCase(name);
 }
 
+/**
+ * snake_case domain field name for a model field, honoring a `domainName`
+ * override (set via the `fieldHints` config) so a wire field can surface under
+ * a friendlier name. The wire key (still derived from `field.name`) is what
+ * gets sent/received over the wire — only the domain attr/accessor name changes.
+ */
+export function domainFieldName(field: { name: string; domainName?: string }): string {
+  return toSnakeCase(field.domainName ?? field.name);
+}
+
 /**
  * Ruby reserved words that cannot be used as parameter names.
  * When a path/query param name collides, suffix with underscore.

package/src/ruby/rbi.ts

@@ -3,6 +3,7 @@ import { mapTypeRef as irMapTypeRef } from '@workos/oagen';
 import {
   className,
   fieldName,
+  domainFieldName,
   fileName,
   safeParamName,
   scopedGroupVariantClassName,
@@ -92,7 +93,8 @@ export function generateRbiFiles(spec: ApiSpec, ctx: EmitterContext): GeneratedF
     // Field accessors
     const seenFieldNames = new Set<string>();
     for (const f of model.fields) {
-      const fname = fieldName(f.name);
+      // DOMAIN accessor name in the .rbi (honors fieldHints override).
+      const fname = domainFieldName(f);
       if (seenFieldNames.has(fname)) continue;
       seenFieldNames.add(fname);
       const sorbetType = f.required ? mapSorbetType(f.type) : wrapNilable(mapSorbetType(f.type));

package/src/ruby/tests.ts

@@ -3,6 +3,7 @@ import {
   className,
   fileName,
   fieldName,
+  domainFieldName,
   safeParamName,
   scopedGroupVariantClassName,
   servicePropertyName,
@@ -235,7 +236,9 @@ function generateModelRoundTripTest(spec: ApiSpec): GeneratedFile {
     const dedupFields = new Set<string>();
     for (const f of model.fields) {
       const wireName = f.name;
-      const rubyFieldName = fieldName(f.name);
+      // Dedup on the DOMAIN accessor name to mirror the model's field dedup
+      // (models.ts). The fixture/assertion keys below still use the WIRE name.
+      const rubyFieldName = domainFieldName(f);
       if (dedupFields.has(rubyFieldName)) continue;
       dedupFields.add(rubyFieldName);
       const stub = roundTripStub(f.type, enumNames);

package/src/rust/index.ts

@@ -17,6 +17,7 @@ import { generateTests } from './tests.js';
 import { buildOperationsMap } from './manifest.js';
 import { UnionRegistry } from './type-map.js';
 import { enrichModelsFromSpec, getSyntheticEnums } from '../shared/model-utils.js';
+import { AUTOGEN_NOTICE } from '../shared/file-header.js';
 
 /**
  * Shared per-emit registry that collects synthesised oneOf-style unions
@@ -98,7 +99,7 @@ export const rustEmitter: Emitter = {
   },
 
   fileHeader(): string {
-    return '// Code generated by oagen. DO NOT EDIT.';
+    return `// ${AUTOGEN_NOTICE}`;
   },
 
   formatCommand(_targetDir: string): FormatCommand | null {

package/src/rust/models.ts

@@ -1,5 +1,5 @@
-import type { Model, EmitterContext, GeneratedFile, Field } from '@workos/oagen';
-import { typeName, fieldName, moduleName } from './naming.js';
+import type { Model, EmitterContext, GeneratedFile, Field, TypeRef } from '@workos/oagen';
+import { typeName, domainFieldName, moduleName } from './naming.js';
 import { mapTypeRef, makeOptional, UnionRegistry } from './type-map.js';
 import { applySecretRedaction } from './secret.js';
 
@@ -18,6 +18,13 @@ export function generateModels(models: Model[], ctx: EmitterContext, registry: U
   const moduleNames: string[] = [];
   const seen = new Set<string>();
 
+  // Map of variant-model name -> discriminator wire-property for every model
+  // that appears as an arm of an internally-tagged (`#[serde(tag = ...)]`)
+  // union. serde consumes that property as the enum tag and strips it from the
+  // variant body during deserialization, so a *required* field of the same
+  // name can never be satisfied ("missing field `type`"). See renderField.
+  const taggedVariantFields = collectTaggedVariantFields(models);
+
   for (const model of models) {
     // Empty-field, non-discriminator models still need to be emitted as an
     // empty struct so request bodies that reference them (e.g. an empty
@@ -29,7 +36,11 @@ export function generateModels(models: Model[], ctx: EmitterContext, registry: U
 
     const hintPath = ctx.overlayLookup?.fileBySymbol?.get(model.name);
     const path = hintPath ?? `src/models/${mod}.rs`;
-    files.push({ path, content: renderModel(model, registry), overwriteExisting: true });
+    files.push({
+      path,
+      content: renderModel(model, registry, taggedVariantFields.get(model.name)),
+      overwriteExisting: true,
+    });
   }
 
   // Always include the unions module in the barrel so downstream stages
@@ -47,7 +58,48 @@ export function generateModels(models: Model[], ctx: EmitterContext, registry: U
   return files;
 }
 
-function renderModel(model: Model, registry: UnionRegistry): string {
+/**
+ * Walk every model field and record which models are arms of an
+ * internally-tagged union, mapped to that union's discriminator property.
+ */
+function collectTaggedVariantFields(models: Model[]): Map<string, string> {
+  const out = new Map<string, string>();
+  const visit = (ref: TypeRef): void => {
+    switch (ref.kind) {
+      case 'union':
+        if (ref.discriminator?.property) {
+          for (const variant of ref.variants) {
+            const name = variantModelName(variant);
+            if (name) out.set(name, ref.discriminator.property);
+          }
+        }
+        ref.variants.forEach(visit);
+        break;
+      case 'array':
+        visit(ref.items);
+        break;
+      case 'nullable':
+        visit(ref.inner);
+        break;
+      case 'map':
+        visit(ref.valueType);
+        break;
+      default:
+        break;
+    }
+  };
+  for (const model of models) for (const field of model.fields) visit(field.type);
+  return out;
+}
+
+/** Resolve the underlying model name of a union arm, unwrapping a nullable. */
+function variantModelName(ref: TypeRef): string | null {
+  if (ref.kind === 'model') return ref.name;
+  if (ref.kind === 'nullable') return variantModelName(ref.inner);
+  return null;
+}
+
+function renderModel(model: Model, registry: UnionRegistry, tagField?: string): string {
   const lines: string[] = [];
   lines.push(HEADER_PLACEHOLDER);
   // Match rustfmt's canonical grouping: keyword-rooted paths (`super`,
@@ -65,7 +117,7 @@ function renderModel(model: Model, registry: UnionRegistry): string {
   lines.push('#[derive(Debug, Clone, Serialize, Deserialize)]');
 
   const resolvedNames = resolveFieldNames(model.fields);
-  const fieldLines = model.fields.map((f, i) => renderField(f, resolvedNames[i]!, model.name, registry));
+  const fieldLines = model.fields.map((f, i) => renderField(f, resolvedNames[i]!, model.name, registry, tagField));
 
   // rustfmt collapses zero-field structs to `pub struct Foo {}` on a single
   // line. Match that shape so `cargo fmt --check` passes.
@@ -80,17 +132,20 @@ function renderModel(model: Model, registry: UnionRegistry): string {
 }
 
 /**
- * Resolve unique Rust identifiers for struct fields. Multiple wire names can
- * collide after `fieldName()` snake-cases them (e.g. `integration_type` and
- * `integrationType` both become `integration_type`). Subsequent collisions get
- * a numeric suffix so the struct compiles; serde `rename` preserves the
- * original wire name in every case.
+ * Resolve unique Rust identifiers for struct fields. The domain identifier
+ * honors a `fieldHints` override (`domainName`, e.g. wire `connection_type` →
+ * domain `type`); the wire name (and the `#[serde(rename = ...)]` key emitted
+ * in `renderField`) still derives from `f.name`. Multiple names can collide
+ * after snake-casing (e.g. `integration_type` and `integrationType` both
+ * become `integration_type`). Subsequent collisions get a numeric suffix so
+ * the struct compiles; serde `rename` preserves the original wire name in every
+ * case.
  */
 function resolveFieldNames(fields: Field[]): string[] {
   const used = new Set<string>();
   const out: string[] = [];
   for (const f of fields) {
-    const base = fieldName(f.name);
+    const base = domainFieldName(f);
     let candidate = base;
     let suffix = 2;
     while (used.has(candidate)) {
@@ -103,7 +158,13 @@ function resolveFieldNames(fields: Field[]): string[] {
   return out;
 }
 
-function renderField(field: Field, rustField: string, modelName: string, registry: UnionRegistry): string {
+function renderField(
+  field: Field,
+  rustField: string,
+  modelName: string,
+  registry: UnionRegistry,
+  tagField?: string,
+): string {
   const lines: string[] = [];
   const hasDescription = !!field.description;
   if (hasDescription) {
@@ -128,9 +189,20 @@ function renderField(field: Field, rustField: string, modelName: string, registr
   // the value is a credential or token. Wire format is unchanged.
   baseType = applySecretRedaction(baseType, field.name);
 
-  if (rename) lines.push(`    #[serde(rename = "${rename}")]`);
-  if (baseType.startsWith('Option<')) {
-    lines.push('    #[serde(skip_serializing_if = "Option::is_none", default)]');
+  if (tagField === field.name) {
+    // This field is the discriminator of an internally-tagged union it belongs
+    // to. serde reads it as the enum tag and strips it from the variant body,
+    // so `default` lets the struct deserialize without it; `skip_serializing`
+    // stops the struct from re-emitting it (serde injects the tag itself,
+    // which would otherwise produce a duplicate key). Standalone uses of the
+    // struct still deserialize the value normally because the key is present.
+    const args = rename ? `rename = "${rename}", default, skip_serializing` : 'default, skip_serializing';
+    lines.push(`    #[serde(${args})]`);
+  } else {
+    if (rename) lines.push(`    #[serde(rename = "${rename}")]`);
+    if (baseType.startsWith('Option<')) {
+      lines.push('    #[serde(skip_serializing_if = "Option::is_none", default)]');
+    }
   }
   if (field.deprecated) lines.push('    #[deprecated]');
   lines.push(`    pub ${rustField}: ${baseType},`);

package/src/rust/naming.ts

@@ -77,6 +77,16 @@ export function fieldName(name: string): string {
   return escapeKeyword(toSnakeCase(name));
 }
 
+/**
+ * snake_case domain field name for a model field, honoring a `domainName`
+ * override (set via the `fieldHints` config) so a wire field can surface under
+ * a friendlier identifier. The wire name (and thus the `#[serde(rename = ...)]`
+ * key) still derives from `field.name`.
+ */
+export function domainFieldName(field: { name: string; domainName?: string }): string {
+  return escapeKeyword(toSnakeCase(field.domainName ?? field.name));
+}
+
 /** PascalCase enum variant. */
 export function variantName(value: string | number): string {
   const s = String(value);

package/src/rust/resources.ts

@@ -10,7 +10,7 @@ import type {
   TypeRef,
 } from '@workos/oagen';
 import { planOperation } from '@workos/oagen';
-import { fieldName, methodName, typeName, moduleName, variantName } from './naming.js';
+import { fieldName, domainFieldName, methodName, typeName, moduleName, variantName } from './naming.js';
 import { mapTypeRef, makeOptional, UnionRegistry } from './type-map.js';
 import { applySecretRedaction } from './secret.js';
 import { parsePathTemplate } from '../shared/path-template.js';
@@ -617,7 +617,11 @@ function registerSyntheticBody(
       if (!f.required && !rust.startsWith('Option<')) rust = makeOptional(rust);
       rust = applySecretRedaction(rust, f.name);
       return {
-        rustName: fieldName(f.name),
+        // Domain identifier honors a `fieldHints` override (e.g. wire
+        // `connection_type` → domain `type`); `wireName` keeps `f.name`, and
+        // the `#[serde(rename = wireName)]` emitted in GroupEmitter.render
+        // fires whenever the two differ.
+        rustName: domainFieldName(f),
         wireName: f.name,
         rustType: rust,
         required: !!f.required && !rust.startsWith('Option<'),

package/src/shared/file-header.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical "do not edit" banner text shared by every emitter's
+ * `fileHeader()`. The text is comment-syntax agnostic — each emitter prefixes
+ * it with the appropriate comment marker for its language (`//`, `#`, etc.).
+ *
+ * Keeping this in one place prevents the wording from drifting between
+ * languages (Rust previously emitted a different banner).
+ *
+ * Go intentionally does NOT use this constant: its header must match the
+ * standard `^// Code generated .* DO NOT EDIT\.$` marker that Go tooling
+ * relies on to recognize generated files. See `src/go/index.ts`.
+ */
+export const AUTOGEN_NOTICE = 'This file is auto-generated by oagen. Do not edit.';