feat(generator): add special handling for discriminator cases

maxdev1 · maxdev1 · commit 42b428d95053 · 2026-03-17T21:18:02.000+01:00
diff --git a/README.md b/README.md
@@ -1,7 +1,9 @@
 # openapi-request-validation
 
-Build-time OpenAPI request validation for serverless and lightweight Node runtimes. Performs request validation based on
-OpenAPI specifications. Supports AWS Lambda API Gateway events, lambda-api requests and Express.
+Provides request validation based on OpenAPI specifications for serverless and lightweight Node runtimes.
+
+Used to generate validator code based on an OpenAPI spec and offers runtime validation helpers to validate requests objects.
+Supports AWS Lambda API Gateway events, lambda-api requests and Express.
 
 Uses AJV to generate standalone request validators and ships runtime helpers for easy validation.
 
diff --git a/src/generator/rewrite-open-api-discriminators.ts b/src/generator/rewrite-open-api-discriminators.ts
@@ -0,0 +1,191 @@
+import type {OpenAPIV3} from "openapi-types"
+import {resolveLocalRef} from "./validator-artifacts.js"
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function isReferenceObject(value: unknown): value is OpenAPIV3.ReferenceObject {
+  return isObjectRecord(value) && typeof value.$ref === "string"
+}
+
+function extractStringLiteralValues(
+  doc: OpenAPIV3.Document,
+  schema: unknown,
+): string[] {
+  if (!isObjectRecord(schema)) {
+    return []
+  }
+
+  const resolved = isReferenceObject(schema)
+    ? resolveLocalRef<Record<string, unknown>>(doc, schema.$ref)
+    : schema
+
+  if (typeof resolved.const === "string") {
+    return [resolved.const]
+  }
+
+  if (Array.isArray(resolved.enum) && resolved.enum.every((value) => typeof value === "string")) {
+    return [...resolved.enum]
+  }
+
+  return []
+}
+
+function inferDiscriminatorValues(
+  doc: OpenAPIV3.Document,
+  schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+  propertyName: string,
+): string[] {
+  const resolved = isReferenceObject(schema)
+    ? resolveLocalRef<Record<string, unknown>>(doc, schema.$ref)
+    : schema as Record<string, unknown>
+
+  const properties = isObjectRecord(resolved.properties) ? resolved.properties : null
+  const directValues = extractStringLiteralValues(doc, properties?.[propertyName])
+  if (directValues.length > 0) {
+    return directValues
+  }
+
+  if (!isReferenceObject(schema)) {
+    return []
+  }
+
+  const segments = schema.$ref.split("/")
+  const schemaName = segments.at(-1)
+  return schemaName ? [schemaName] : []
+}
+
+type DiscriminatorBranch = {
+  tagValues: string[]
+  schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject
+}
+
+function getDiscriminatorBranches(
+  doc: OpenAPIV3.Document,
+  unionMembers: Array<OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject>,
+  discriminator: OpenAPIV3.DiscriminatorObject,
+): DiscriminatorBranch[] {
+  const mappingEntries = Object.entries(discriminator.mapping ?? {})
+  const branches: DiscriminatorBranch[] = []
+  const seenTagValues = new Set<string>()
+
+  for (const member of unionMembers) {
+    const tagValues = new Set<string>()
+
+    if (isReferenceObject(member)) {
+      for (const [tagValue, mappedRef] of mappingEntries) {
+        if (mappedRef === member.$ref) {
+          tagValues.add(tagValue)
+        }
+      }
+    }
+
+    if (tagValues.size === 0) {
+      for (const tagValue of inferDiscriminatorValues(doc, member, discriminator.propertyName)) {
+        tagValues.add(tagValue)
+      }
+    }
+
+    if (tagValues.size === 0) {
+      return []
+    }
+
+    for (const tagValue of tagValues) {
+      if (seenTagValues.has(tagValue)) {
+        return []
+      }
+
+      seenTagValues.add(tagValue)
+    }
+
+    branches.push({
+      tagValues: [...tagValues],
+      schema: member,
+    })
+  }
+
+  return branches
+}
+
+function createDiscriminatorMatcher(
+  propertyName: string,
+  tagValues: string[],
+): Record<string, unknown> {
+  return {
+    type: "object",
+    required: [propertyName],
+    properties: {
+      [propertyName]: tagValues.length === 1 ? {const: tagValues[0]} : {enum: tagValues},
+    },
+  }
+}
+
+function rewriteDiscriminatorSchema(
+  doc: OpenAPIV3.Document,
+  schema: Record<string, unknown>,
+): void {
+  const discriminator = schema.discriminator
+  if (!isObjectRecord(discriminator) || typeof discriminator.propertyName !== "string") {
+    return
+  }
+
+  const propertyName = discriminator.propertyName
+
+  const oneOf = Array.isArray(schema.oneOf) ? schema.oneOf : null
+  const anyOf = Array.isArray(schema.anyOf) ? schema.anyOf : null
+  const unionMembers = oneOf ?? anyOf
+
+  if (!unionMembers) {
+    return
+  }
+
+  const branches = getDiscriminatorBranches(
+    doc,
+    unionMembers as Array<OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject>,
+    discriminator as unknown as OpenAPIV3.DiscriminatorObject,
+  )
+
+  if (branches.length === 0) {
+    return
+  }
+
+  const existingAllOf = Array.isArray(schema.allOf) ? [...schema.allOf] : []
+  const allowedTagValues = branches.flatMap((branch) => branch.tagValues)
+
+  schema.allOf = [
+    ...existingAllOf,
+    createDiscriminatorMatcher(propertyName, allowedTagValues),
+    ...branches.map((branch) => ({
+      if: createDiscriminatorMatcher(propertyName, branch.tagValues),
+      then: branch.schema,
+    })),
+  ] as Array<OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject>
+
+  delete schema.discriminator
+  delete schema.oneOf
+  delete schema.anyOf
+}
+
+export function rewriteOpenApiDiscriminators(doc: OpenAPIV3.Document): void {
+  const visit = (value: unknown) => {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        visit(item)
+      }
+      return
+    }
+
+    if (!isObjectRecord(value)) {
+      return
+    }
+
+    for (const child of Object.values(value)) {
+      visit(child)
+    }
+
+    rewriteDiscriminatorSchema(doc, value)
+  }
+
+  visit(doc)
+}
diff --git a/src/generator/validator-artifacts.ts b/src/generator/validator-artifacts.ts
@@ -1,6 +1,7 @@
 import type {OpenAPIV3} from "openapi-types"
 import {HTTP_METHODS} from "../common/http-methods.js"
 import {toPascalIdentifier} from "./pascal-identifier.js"
+import {rewriteOpenApiDiscriminators} from "./rewrite-open-api-discriminators.js"
 
 type ParameterLocation = "query" | "path" | "header"
 
@@ -399,6 +400,7 @@ export function prepareValidatorArtifacts(
   validators: ValidatorExports
 } {
   const specForValidation = structuredClone(spec)
+  rewriteOpenApiDiscriminators(specForValidation)
   const validators = registerRequestSchemasAndCollectValidators(specForValidation)
 
   return {
diff --git a/test/discriminator-mapping.test.ts b/test/discriminator-mapping.test.ts
@@ -0,0 +1,59 @@
+import {RequestValidationError, validateApiGatewayEvent} from "../src"
+import {loadGeneratedValidators} from "./helpers/load-generated-validator"
+
+describe("discriminator mappings", () => {
+  let cleanup: () => void = () => {
+  }
+  let validateCreateItemRequest: (value: unknown) => boolean
+
+  beforeAll(async () => {
+    const loaded = await loadGeneratedValidators({fixtureName: "discriminator-mapping-api.yaml"})
+    cleanup = loaded.cleanup
+    validateCreateItemRequest = loaded.getValidator("validateCreateItemRequest")
+  })
+
+  afterAll(() => {
+    cleanup()
+  })
+
+  test("accepts the mapped embedded branch even when the branch inherits the discriminator property", () => {
+    expect(() =>
+      validateApiGatewayEvent(validateCreateItemRequest, {
+        body: JSON.stringify({
+          item: {
+            type: "EMBEDDED",
+            code: "embedded-item",
+            value: 25
+          },
+        }),
+      }),
+    ).not.toThrow()
+  })
+
+  test("only reports errors from the discriminator-selected branch", () => {
+    let thrownError: unknown
+
+    try {
+      validateApiGatewayEvent(validateCreateItemRequest, {
+        body: JSON.stringify({
+          item: {
+            type: "EMBEDDED",
+          },
+        }),
+      })
+    } catch (error) {
+      thrownError = error
+    }
+
+    expect(thrownError).toBeInstanceOf(RequestValidationError)
+
+    const validationError = thrownError as RequestValidationError
+    const missingProperties = validationError.errors
+      .map((error) => error.params)
+      .filter((params): params is {missingProperty: string} => typeof params === "object" && params !== null && "missingProperty" in params)
+      .map((params) => params.missingProperty)
+      .sort()
+
+    expect(missingProperties).toEqual(["code"])
+  })
+})
diff --git a/test/fixtures/discriminator-mapping-api.yaml b/test/fixtures/discriminator-mapping-api.yaml
@@ -0,0 +1,65 @@
+openapi: 3.0.3
+info:
+  title: Discriminator Mapping API
+  version: 1.0.0
+paths:
+  /items:
+    post:
+      operationId: createItem
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - item
+              properties:
+                item:
+                  $ref: "#/components/schemas/ItemResource"
+      responses:
+        "201":
+          description: Created
+components:
+  schemas:
+    ItemResource:
+      oneOf:
+        - $ref: "#/components/schemas/ItemReference"
+        - $ref: "#/components/schemas/ItemEmbedded"
+      discriminator:
+        propertyName: type
+        mapping:
+          REFERENCE: "#/components/schemas/ItemReference"
+          EMBEDDED: "#/components/schemas/ItemEmbedded"
+    ItemResourceType:
+      type: string
+      enum:
+        - REFERENCE
+        - EMBEDDED
+    ItemResourceBase:
+      type: object
+      required:
+        - type
+      properties:
+        type:
+          $ref: "#/components/schemas/ItemResourceType"
+    ItemReference:
+      allOf:
+        - $ref: "#/components/schemas/ItemResourceBase"
+        - type: object
+          required:
+            - id
+          properties:
+            id:
+              type: string
+    ItemEmbedded:
+      allOf:
+        - $ref: "#/components/schemas/ItemResourceBase"
+        - type: object
+          required:
+            - code
+          properties:
+            code:
+              type: string
+            value:
+              type: number
diff --git a/test/package-exports.test.ts b/test/package-exports.test.ts
@@ -27,14 +27,14 @@ describe("package exports", () => {
     const esmOutput = runNode([
       "--input-type=module",
       "-e",
-      "Promise.all([import('openapi-request-validation/generator'), import('openapi-request-validation/runtime')]).then(([g,r])=>console.log(typeof g.generateApiValidatorsFromDocument + ' ' + typeof g.generateApiValidatorsFromPath + ' ' + typeof r.validateExpressRequest + ' ' + typeof r.validateApiGatewayProxyEvent))",
+      "Promise.all([import('openapi-request-validation/generator'), import('openapi-request-validation/runtime')]).then(async ([g,r])=>{const generated=await g.generateApiValidatorsFromPath('./test/fixtures/order-api.yaml'); console.log(typeof g.generateApiValidatorsFromDocument + ' ' + typeof g.generateApiValidatorsFromPath + ' ' + typeof r.validateExpressRequest + ' ' + typeof r.validateApiGatewayProxyEvent + ' ' + generated.validatorCount)})",
     ])
     const cjsOutput = runNode([
       "-e",
-      "const g=require('openapi-request-validation/generator'); const r=require('openapi-request-validation/runtime'); console.log(typeof g.generateApiValidatorsFromDocument + ' ' + typeof g.generateApiValidatorsFromPath + ' ' + typeof r.validateExpressRequest + ' ' + typeof r.validateApiGatewayProxyEvent)",
+      "const g=require('openapi-request-validation/generator'); const r=require('openapi-request-validation/runtime'); g.generateApiValidatorsFromPath('./test/fixtures/order-api.yaml').then((generated)=>console.log(typeof g.generateApiValidatorsFromDocument + ' ' + typeof g.generateApiValidatorsFromPath + ' ' + typeof r.validateExpressRequest + ' ' + typeof r.validateApiGatewayProxyEvent + ' ' + generated.validatorCount))",
     ])
 
-    expect(esmOutput).toBe("function function function function")
-    expect(cjsOutput).toBe("function function function function")
+    expect(esmOutput).toBe("function function function function 1")
+    expect(cjsOutput).toBe("function function function function 1")
   })
 })
diff --git a/test/validate-composition-schemas.test.ts b/test/validate-composition-schemas.test.ts
@@ -141,6 +141,6 @@ describe("OpenAPI composition schemas", () => {
           pushToken: "device-token",
         }),
       }),
-    ).toThrow("must match exactly one schema in oneOf")
+    ).toThrow("must be equal to one of the allowed values")
   })
 })
