Function normalizeSchema

normalizeSchema<T = any>(
schema: JSONSchema7,
filterOptions?: GraphTraversalFilterOptions<T>,
): NormalizedSchema

Normalizes a JSON Schema by resolving all $refs and applying filter options

This is a two-phase process:

Resolve all $ref references to create a flat schema structure
Apply include/exclude/omit filters to determine which properties to traverse

Type Parameters

T = any
The type to derive filter patterns from (typically z.infer)

Parameters

schema: JSONSchema7
The JSON Schema to normalize
filterOptions: GraphTraversalFilterOptions<T> = ...
Filter options for selecting/including/omitting properties

Returns NormalizedSchema

A normalized schema with all refs resolved and filters applied

Example

// Without type parameter (backward compatible)
const schema = {
  type: "object",
  properties: {
    name: { type: "string" },
    tags: {
      type: "array",
      items: { $ref: "#/$defs/Tag" }
    }
  },
  $defs: {
    Tag: {
      type: "object",
      properties: {
        label: { type: "string" },
        "@id": { type: "string" }
      }
    }
  }
};

const normalized = normalizeSchema(schema, {
  include: { tags: { take: 10 } },
  includeRelationsByDefault: false
});

// With Zod type inference for type safety
import { z } from 'zod';
const zodSchema = z.object({
  name: z.string(),
  tags: z.array(z.object({ label: z.string() }))
});
type MyType = z.infer<typeof zodSchema>;

const normalized2 = normalizeSchema<MyType>(schema, {
  include: { tags: { take: 10 } } // Type-safe: only valid keys allowed
});