feat: content-type support for validateResponse/validateRequest (#1)

* feat(types): add optional contentType to ValidatorOptions

Narrow stored options type to { strict: boolean } since contentType
is resolved per-call, not at construction time.

* feat(schemas): add isBinaryContentType helper

* feat(schemas): add resolveMediaType helper for content-type lookup

* feat(schemas): content-type aware response schema extraction

Extend extractResponseSchema with an optional contentType parameter (defaulting
to application/json) that uses isBinaryContentType and resolveMediaType to
support exact, family-wildcard, and */* media-type matching; silently bypasses
unmatched binary types and emits MISSING_SCHEMA for unmatched non-binary types.

* feat(schemas): content-type aware request schema extraction

Extend extractRequestSchema with an optional contentType parameter (defaulting
to application/json), using resolveMediaType for wildcard matching and
isBinaryContentType for silent bypass of binary payloads.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(validator): forward contentType option through validateResponse

Plumbs options.contentType (defaulting to 'application/json') from
validateResponse into extractResponseSchema, enabling content-type-aware
schema lookup for binary and wildcard media types.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(validator): forward contentType option through validateRequest

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(validator): normalize schemas under all content-type entries

Update normalizeAllSchemas to iterate over every media-type object in
both response content and requestBody content, rather than only
handling application/json, so non-JSON schemas (multipart/form-data,
text/plain, etc.) are also converted to OpenAPI 3.1 shape during init.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(validator): use discriminating exclusiveMinimum transform

Replace nullable-based assertions (which Ajv silently accepts even
without normalization due to strict:false) with exclusiveMinimum
boolean-form tests that only pass when normalizeAllSchemas actually
rewrites 3.0 schemas under non-JSON content types.

* chore: bump version to 0.2.0 for content-type support

* docs: changelog entry for 0.2.0 content-type support

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kevinccbsg

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.0 (2026-04-20)
+
+### Features
+
+- **content-type:** Add optional `contentType` to `ValidatorOptions` for `validateResponse` and `validateRequest`. Defaults to `application/json` (backwards compatible). Media-type resolution order is exact match → family wildcard (`image/*`) → `*/*`. Unmatched binary content types (`image/*`, `video/*`, `audio/*`, `application/octet-stream`, `application/pdf`, `application/zip`) are silently bypassed — no more false-positive `MISSING_SCHEMA` warnings when a mock returns binary data like a QR code.
+
+### Internal
+
+- **normalize:** `normalizeAllSchemas` now rewrites OpenAPI 3.0 → 3.1 schemas under every media-type entry in `content`, not only `application/json`. Previously, schemas declared under e.g. `multipart/form-data` or `image/jpeg` missed the rewrite and could throw at validation time.
+
 ## 0.1.4 (2026-04-08)
 
 ### Bug Fixes

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-mock-validator",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Validate JSON payloads against OpenAPI 3.0/3.1 specs — catch mock drift before it hits production",
   "type": "module",
   "main": "./dist/index.js",

package.json

@@ -1,5 +1,34 @@
 import type { OpenAPISpec, ValidationWarning } from './types.js';
 
+const BINARY_PREFIXES = ['image/', 'video/', 'audio/'] as const;
+const BINARY_EXACT = new Set([
+  'application/octet-stream',
+  'application/pdf',
+  'application/zip',
+]);
+
+export function isBinaryContentType(contentType: string): boolean {
+  return BINARY_PREFIXES.some((prefix) => contentType.startsWith(prefix))
+    || BINARY_EXACT.has(contentType);
+}
+
+export function resolveMediaType(
+  content: Record<string, Record<string, unknown>>,
+  contentType: string,
+): Record<string, unknown> | null {
+  if (content[contentType]) return content[contentType];
+
+  const slashIndex = contentType.indexOf('/');
+  if (slashIndex > 0) {
+    const family = `${contentType.slice(0, slashIndex)}/*`;
+    if (content[family]) return content[family];
+  }
+
+  if (content['*/*']) return content['*/*'];
+
+  return null;
+}
+
 interface SchemaExtractionResult {
   schema: Record<string, unknown> | null;
   warnings: ValidationWarning[];
@@ -10,6 +39,7 @@ export function extractResponseSchema(
   path: string,
   method: string,
   status: number,
+  contentType: string = 'application/json',
 ): SchemaExtractionResult {
   const warnings: ValidationWarning[] = [];
   const normalizedMethod = method.toLowerCase();
@@ -48,11 +78,14 @@ export function extractResponseSchema(
     return { schema: null, warnings };
   }
 
-  const mediaType = content['application/json'];
+  const mediaType = resolveMediaType(content, contentType);
   if (!mediaType) {
+    if (isBinaryContentType(contentType)) {
+      return { schema: null, warnings: [] };
+    }
     warnings.push({
       type: 'MISSING_SCHEMA',
-      message: `No application/json content for ${method.toUpperCase()} ${path} (${status})`,
+      message: `No ${contentType} content for ${method.toUpperCase()} ${path} (${status})`,
     });
     return { schema: null, warnings };
   }
@@ -73,6 +106,7 @@ export function extractRequestSchema(
   spec: OpenAPISpec,
   path: string,
   method: string,
+  contentType: string = 'application/json',
 ): SchemaExtractionResult {
   const warnings: ValidationWarning[] = [];
   const normalizedMethod = method.toLowerCase();
@@ -105,11 +139,14 @@ export function extractRequestSchema(
     return { schema: null, warnings };
   }
 
-  const mediaType = content['application/json'];
+  const mediaType = resolveMediaType(content, contentType);
   if (!mediaType) {
+    if (isBinaryContentType(contentType)) {
+      return { schema: null, warnings: [] };
+    }
     warnings.push({
       type: 'MISSING_SCHEMA',
-      message: `No application/json content in requestBody for ${method.toUpperCase()} ${path}`,
+      message: `No ${contentType} content in requestBody for ${method.toUpperCase()} ${path}`,
     });
     return { schema: null, warnings };
   }

src/schemas.ts

@@ -1,5 +1,12 @@
 export interface ValidatorOptions {
   strict?: boolean;
+  /**
+   * Content-Type of the response or request being validated.
+   * Default: `"application/json"`.
+   * Accepts exact types (`"image/jpeg"`) or is matched against wildcard
+   * content-type entries in the spec (`"image/*"`, `"*\/*"`).
+   */
+  contentType?: string;
 }
 
 export interface PathMatch {

src/types.ts

@@ -21,7 +21,7 @@ interface InternalError extends ValidationError {
 
 export class OpenAPIMockValidator {
   private spec: OpenAPISpec;
-  private options: Required<ValidatorOptions>;
+  private options: { strict: boolean };
   private compiledPaths: CompiledPath[] | null = null;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Ajv2020 lacks proper type exports
   private ajv: any = null;
@@ -86,7 +86,8 @@ export class OpenAPIMockValidator {
   ): ValidationResult {
     this.ensureInitialized();
 
-    const { schema, warnings } = extractResponseSchema(this.spec, path, method, status);
+    const contentType = options?.contentType ?? 'application/json';
+    const { schema, warnings } = extractResponseSchema(this.spec, path, method, status, contentType);
     if (!schema) {
       return { valid: true, errors: [], warnings };
     }
@@ -103,7 +104,8 @@ export class OpenAPIMockValidator {
   ): ValidationResult {
     this.ensureInitialized();
 
-    const { schema, warnings } = extractRequestSchema(this.spec, path, method);
+    const contentType = options?.contentType ?? 'application/json';
+    const { schema, warnings } = extractRequestSchema(this.spec, path, method, contentType);
     if (!schema) {
       return { valid: true, errors: [], warnings };
     }
@@ -260,29 +262,37 @@ export class OpenAPIMockValidator {
         if (key.startsWith('x-') || typeof value !== 'object' || value === null) continue;
         const operation = value as Record<string, unknown>;
 
-        // Normalize response schemas
+        // Normalize response schemas across all content types
         const responses = operation.responses as Record<string, Record<string, unknown>> | undefined;
         if (responses) {
           for (const response of Object.values(responses)) {
             const content = response?.content as Record<string, Record<string, unknown>> | undefined;
-            if (content?.['application/json']?.schema) {
-              content['application/json'].schema = normalizeSpec(
-                content['application/json'].schema as Record<string, unknown>,
-                spec.openapi,
-              );
+            if (content) {
+              for (const mediaTypeObj of Object.values(content)) {
+                if (mediaTypeObj?.schema) {
+                  mediaTypeObj.schema = normalizeSpec(
+                    mediaTypeObj.schema as Record<string, unknown>,
+                    spec.openapi,
+                  );
+                }
+              }
             }
           }
         }
 
-        // Normalize request body schemas
+        // Normalize request body schemas across all content types
         const requestBody = operation.requestBody as Record<string, unknown> | undefined;
         if (requestBody) {
           const content = requestBody.content as Record<string, Record<string, unknown>> | undefined;
-          if (content?.['application/json']?.schema) {
-            content['application/json'].schema = normalizeSpec(
-              content['application/json'].schema as Record<string, unknown>,
-              spec.openapi,
-            );
+          if (content) {
+            for (const mediaTypeObj of Object.values(content)) {
+              if (mediaTypeObj?.schema) {
+                mediaTypeObj.schema = normalizeSpec(
+                  mediaTypeObj.schema as Record<string, unknown>,
+                  spec.openapi,
+                );
+              }
+            }
           }
         }
       }