@f3liz/rescript-autogen-openapi 0.3.1

package/src/core/SchemaIRParser.res

@@ -0,0 +1,454 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// SchemaIRParser.res - Parse JSON Schema to Unified IR
+
+// Helper to convert raw JSON type string to our variant
+// This is needed because Obj.magic from JSON gives us raw strings like "string", "object", etc.
+// but our variant constructors compile to "String", "Object", etc. in JS
+// Also handles OpenAPI 3.1 array form: type: ["string", "null"]
+let parseTypeString = (rawType: Types.jsonSchemaType): Types.jsonSchemaType => {
+  // The rawType might actually be a raw string from JSON, so we need to handle that
+  // We use Obj.magic to get the underlying JS value and check it
+  let rawStr: string = Obj.magic(rawType)
+  switch rawStr {
+  | "string" => Types.String
+  | "number" => Types.Number
+  | "integer" => Types.Integer
+  | "boolean" => Types.Boolean
+  | "object" => Types.Object
+  | "null" => Types.Null
+  | "array" => Types.Array(Types.Unknown)
+  | _ => {
+      // It might already be a proper variant (like when recursively constructed)
+      // In that case, rawStr would be "String", "Number", etc.
+      switch rawStr {
+      | "String" => Types.String
+      | "Number" => Types.Number
+      | "Integer" => Types.Integer
+      | "Boolean" => Types.Boolean
+      | "Object" => Types.Object
+      | "Null" => Types.Null
+      | "Unknown" => Types.Unknown
+      | _ => Types.Unknown
+      }
+    }
+  }
+}
+
+// Check if the type field is an array (OpenAPI 3.1: type: ["string", "null"])
+// Returns Some(array of parsed types) if array, None otherwise
+let parseTypeAsArray = (rawType: Types.jsonSchemaType): option<array<Types.jsonSchemaType>> => {
+  let raw: 'a = Obj.magic(rawType)
+  if Array.isArray(raw) {
+    let arr: array<string> = Obj.magic(raw)
+    Some(arr->Array.map(s => {
+      let t: Types.jsonSchemaType = Obj.magic(s)
+      parseTypeString(t)
+    }))
+  } else {
+    None
+  }
+}
+
+// Parsing context to collect warnings
+type parsingContext = {
+  mutable warnings: array<Types.warning>,
+  path: string,
+}
+
+let addWarning = (ctx: parsingContext, warning: Types.warning): unit => {
+  ctx.warnings->Array.push(warning)
+}
+
+// Convert JSON Schema to IR with depth limit to prevent infinite recursion
+let rec parseJsonSchemaWithContext = (
+  ~ctx: parsingContext,
+  ~depth=0,
+  schema: Types.jsonSchema,
+): SchemaIR.irType => {
+  // Safety: Prevent infinite recursion on circular schemas
+  if depth > 30 {
+    addWarning(
+      ctx,
+      DepthLimitReached({
+        depth: depth,
+        path: ctx.path,
+      }),
+    )
+    SchemaIR.Unknown
+  } else {
+  // Handle $ref first
+  switch schema.ref {
+  | Some(ref) => SchemaIR.Reference(ref)
+  | None => {
+      // Check if nullable
+      let isNullable = schema.nullable->Option.getOr(false)
+      
+      // Handle OpenAPI 3.1 array type: type: ["string", "null"]
+      // But skip if anyOf/oneOf is present — those are more specific
+      let hasComposition = schema.anyOf->Option.isSome || schema.oneOf->Option.isSome
+      let typeAsArray = if hasComposition {
+        None
+      } else {
+        schema.type_->Option.flatMap(parseTypeAsArray)
+      }
+      // When composition is preferred, check if the type_ is actually an array
+      // and clear it so the None branch runs the composition handlers
+      let schema = if hasComposition && schema.type_->Option.flatMap(parseTypeAsArray)->Option.isSome {
+        {...schema, type_: None}
+      } else {
+        schema
+      }
+      
+      switch typeAsArray {
+      | Some(types) if Array.length(types) > 1 => {
+          // Array type form — convert to Union of parsed types
+          let irTypes = types->Array.map(t => {
+            let subSchema = {...schema, type_: Some(t), nullable: None}
+            parseJsonSchemaWithContext(~ctx, ~depth=depth + 1, subSchema)
+          })
+          let baseType = SchemaIR.Union(irTypes)
+          if isNullable {
+            SchemaIR.Option(baseType)
+          } else {
+            baseType
+          }
+        }
+      | Some(types) if Array.length(types) == 1 => {
+          // Single-element array: treat as that type
+          let subSchema = {...schema, type_: Some(types->Array.getUnsafe(0)), nullable: None}
+          let baseType = parseJsonSchemaWithContext(~ctx, ~depth=depth + 1, subSchema)
+          if isNullable { SchemaIR.Option(baseType) } else { baseType }
+        }
+      | _ => {
+      
+      // Normalize the type field (raw JSON strings like "string" -> variant String)
+      let normalizedType = schema.type_->Option.map(parseTypeString)
+      
+      // Parse base type
+      let baseType = switch normalizedType {
+      | Some(Types.String) => {
+          let constraints: SchemaIR.stringConstraints = {
+            minLength: schema.minLength,
+            maxLength: schema.maxLength,
+            pattern: schema.pattern,
+          }
+          SchemaIR.String({constraints: constraints})
+        }
+      | Some(Types.Number) => {
+          let constraints: SchemaIR.numberConstraints = {
+            minimum: schema.minimum,
+            maximum: schema.maximum,
+            multipleOf: None, // Not in jsonSchema type
+          }
+          SchemaIR.Number({constraints: constraints})
+        }
+      | Some(Types.Integer) => {
+          let constraints: SchemaIR.numberConstraints = {
+            minimum: schema.minimum,
+            maximum: schema.maximum,
+            multipleOf: None, // Not in jsonSchema type
+          }
+          SchemaIR.Integer({constraints: constraints})
+        }
+      | Some(Types.Boolean) => SchemaIR.Boolean
+      | Some(Types.Null) => SchemaIR.Null
+       | Some(Types.Array(_)) => {
+          let items = switch schema.items {
+          | None => SchemaIR.Unknown
+          | Some(itemSchema) => 
+              parseJsonSchemaWithContext(~ctx, ~depth=depth + 1, itemSchema)
+          }
+          
+          let constraints: SchemaIR.arrayConstraints = {
+            minItems: None, // Not in current jsonSchema type
+            maxItems: None, // Not in current jsonSchema type
+            uniqueItems: false,
+          }
+          
+          SchemaIR.Array({items, constraints})
+        }
+      | Some(Types.Object) => {
+          // Check if this is an allOf composition (common in OpenAPI)
+          switch schema.allOf {
+          | Some(schemas) => {
+              // allOf with type: "object" - parse as intersection
+              let types = schemas->Array.map(s => parseJsonSchemaWithContext(~ctx, ~depth=depth + 1, s))
+              SchemaIR.Intersection(types)
+            }
+          | None => {
+              // Regular object type - parse properties
+              let properties = switch schema.properties {
+              | None => []
+               | Some(propsDict) => {
+                  let required = schema.required->Option.getOr([])
+                  Dict.toArray(propsDict)->Array.map(((name, propSchema)) => {
+                    let isRequired = required->Array.includes(name)
+                    let propType = parseJsonSchemaWithContext(~ctx, ~depth=depth + 1, propSchema)
+                    (name, propType, isRequired)
+                  })
+                }
+              }
+              
+              // additionalProperties not in current jsonSchema type
+              let additionalProperties = None
+              
+              SchemaIR.Object({
+                properties,
+                additionalProperties,
+              })
+            }
+          }
+        }
+      | Some(Types.Unknown) => SchemaIR.Unknown
+      | None => {
+          // No type specified, check for enum, properties, or combinators
+          switch (schema.enum, schema.properties, schema.allOf, schema.oneOf, schema.anyOf) {
+          | (Some(enumValues), _, _, _, _) => {
+              // Enum - convert to union of literals
+              let literals = enumValues->Array.map(value => {
+                switch value {
+                | String(str) => SchemaIR.Literal(SchemaIR.StringLiteral(str))
+                | Number(num) => SchemaIR.Literal(SchemaIR.NumberLiteral(num))
+                | Boolean(b) => SchemaIR.Literal(SchemaIR.BooleanLiteral(b))
+                | Null => SchemaIR.Literal(SchemaIR.NullLiteral)
+                | _ => SchemaIR.Unknown
+                }
+              })
+              SchemaIR.Union(literals)
+            }
+           | (_, Some(_), _, _, _) => {
+              // Has properties, treat as object (clear nullable to avoid double wrapping)
+              parseJsonSchemaWithContext(~ctx, ~depth=depth + 1, {...schema, type_: Some(Object), nullable: None})
+            }
+          | (_, _, Some(schemas), _, _) => {
+              // allOf - intersection
+              let types = schemas->Array.map(s => parseJsonSchemaWithContext(~ctx, ~depth=depth + 1, s))
+              SchemaIR.Intersection(types)
+            }
+          | (_, _, _, Some(schemas), _) => {
+              // oneOf - union
+              let types = schemas->Array.map(s => parseJsonSchemaWithContext(~ctx, ~depth=depth + 1, s))
+              SchemaIR.Union(types)
+            }
+          | (_, _, _, _, Some(schemas)) => {
+              // anyOf - union
+              let types = schemas->Array.map(s => parseJsonSchemaWithContext(~ctx, ~depth=depth + 1, s))
+              SchemaIR.Union(types)
+            }
+          | _ => SchemaIR.Unknown
+          }
+        }
+      }
+      
+      // Wrap in Option if nullable
+      if isNullable {
+        SchemaIR.Option(baseType)
+      } else {
+        baseType
+      }
+    } // end | _ => (typeAsArray arm)
+    } // end switch typeAsArray
+    }
+  }
+  }
+}
+
+// Convenience wrapper that creates a context and returns warnings
+let parseJsonSchema = (~depth=0, schema: Types.jsonSchema): (SchemaIR.irType, array<Types.warning>) => {
+  let ctx = {warnings: [], path: "root"}
+  let irType = parseJsonSchemaWithContext(~ctx, ~depth, schema)
+  (irType, ctx.warnings)
+}
+
+// Parse a named schema
+let parseNamedSchema = (~name: string, ~schema: Types.jsonSchema): (SchemaIR.namedSchema, array<Types.warning>) => {
+  let ctx = {warnings: [], path: `components.schemas.${name}`}
+  let type_ = parseJsonSchemaWithContext(~ctx, schema)
+  ({
+    name,
+    description: schema.description,
+    type_,
+  }, ctx.warnings)
+}
+
+// Normalize $ref paths in IR: "#/components/schemas/Name" → "Name" (when Name exists in available schemas)
+let rec normalizeReferences = (~availableNames: array<string>, irType: SchemaIR.irType): SchemaIR.irType => {
+  switch irType {
+  | SchemaIR.Reference(ref) => {
+      let parts = ref->String.split("/")
+      let name = parts->Array.get(parts->Array.length - 1)->Option.getOr("")
+      if availableNames->Array.includes(name) {
+        SchemaIR.Reference(name)
+      } else {
+        irType
+      }
+    }
+  | SchemaIR.Array({items, constraints}) =>
+    SchemaIR.Array({items: normalizeReferences(~availableNames, items), constraints})
+  | SchemaIR.Object({properties, additionalProperties}) => {
+      let newProperties = properties->Array.map(((n, t, r)) =>
+        (n, normalizeReferences(~availableNames, t), r)
+      )
+      let newAdditional = additionalProperties->Option.map(t => normalizeReferences(~availableNames, t))
+      SchemaIR.Object({properties: newProperties, additionalProperties: newAdditional})
+    }
+  | SchemaIR.Union(types) =>
+    SchemaIR.Union(types->Array.map(t => normalizeReferences(~availableNames, t)))
+  | SchemaIR.Intersection(types) =>
+    SchemaIR.Intersection(types->Array.map(t => normalizeReferences(~availableNames, t)))
+  | SchemaIR.Option(inner) =>
+    SchemaIR.Option(normalizeReferences(~availableNames, inner))
+  | other => other
+  }
+}
+
+// Parse all component schemas
+let parseComponentSchemas = (schemas: dict<Types.jsonSchema>): (SchemaIR.schemaContext, array<Types.warning>) => {
+  let namedSchemas = Dict.make()
+  let allWarnings = []
+  
+  schemas->Dict.toArray->Array.forEach(((name, schema)) => {
+    let (namedSchema, warnings) = parseNamedSchema(~name, ~schema)
+    Dict.set(namedSchemas, name, namedSchema)
+    allWarnings->Array.pushMany(warnings)
+  })
+  
+  // Resolve $ref paths in the IR: normalize "#/components/schemas/Name" to just "Name"
+  let availableNames = Dict.keysToArray(namedSchemas)
+  namedSchemas->Dict.toArray->Array.forEach(((name, namedSchema)) => {
+    let resolved = normalizeReferences(~availableNames, namedSchema.type_)
+    Dict.set(namedSchemas, name, {...namedSchema, type_: resolved})
+  })
+  
+  ({schemas: namedSchemas}, allWarnings)
+}
+
+// Resolve a reference in the context
+let resolveReference = (
+  ~context: SchemaIR.schemaContext,
+  ~ref: string,
+): option<SchemaIR.namedSchema> => {
+  // Handle #/components/schemas/SchemaName format
+  let parts = ref->String.split("/")
+  switch parts->Array.get(parts->Array.length - 1) {
+  | None => None
+  | Some(schemaName) => Dict.get(context.schemas, schemaName)
+  }
+}
+
+// Inline simple references to reduce indirection
+let rec inlineSimpleReferences = (
+  ~context: SchemaIR.schemaContext,
+  ~irType: SchemaIR.irType,
+  ~depth: int=0,
+  ~maxDepth: int=2,
+): SchemaIR.irType => {
+  if depth >= maxDepth {
+    irType
+  } else {
+    switch irType {
+    | SchemaIR.Reference(ref) => {
+        switch resolveReference(~context, ~ref) {
+        | None => irType
+        | Some(schema) => {
+            // Only inline if it's a simple type
+            if SchemaIR.isSimpleType(schema.type_) {
+              inlineSimpleReferences(~context, ~irType=schema.type_, ~depth=depth + 1, ~maxDepth)
+            } else {
+              irType
+            }
+          }
+        }
+      }
+    | SchemaIR.Option(inner) => 
+        SchemaIR.Option(inlineSimpleReferences(~context, ~irType=inner, ~depth, ~maxDepth))
+    | SchemaIR.Array({items, constraints}) =>
+        SchemaIR.Array({
+          items: inlineSimpleReferences(~context, ~irType=items, ~depth, ~maxDepth),
+          constraints,
+        })
+    | SchemaIR.Object({properties, additionalProperties}) => {
+        let newProperties = properties->Array.map(((name, type_, required)) => {
+          (name, inlineSimpleReferences(~context, ~irType=type_, ~depth, ~maxDepth), required)
+        })
+        let newAdditionalProps = additionalProperties->Option.map(type_ =>
+          inlineSimpleReferences(~context, ~irType=type_, ~depth, ~maxDepth)
+        )
+        SchemaIR.Object({
+          properties: newProperties,
+          additionalProperties: newAdditionalProps,
+        })
+      }
+    | SchemaIR.Union(types) =>
+        SchemaIR.Union(types->Array.map(type_ =>
+          inlineSimpleReferences(~context, ~irType=type_, ~depth, ~maxDepth)
+        ))
+    | SchemaIR.Intersection(types) =>
+        SchemaIR.Intersection(types->Array.map(type_ =>
+          inlineSimpleReferences(~context, ~irType=type_, ~depth, ~maxDepth)
+        ))
+    | other => other
+    }
+  }
+}
+
+// Optimize IR by simplifying unions, intersections, etc.
+let rec optimizeIR = (irType: SchemaIR.irType): SchemaIR.irType => {
+  switch irType {
+  | SchemaIR.Union(types) => {
+      // Flatten nested unions
+      let flattened = types->Array.flatMap(t => {
+        switch optimizeIR(t) {
+        | SchemaIR.Union(inner) => inner
+        | other => [other]
+        }
+      })
+      
+      // Remove duplicates (simple dedup by toString)
+      let unique = []
+      flattened->Array.forEach(type_ => {
+        let typeStr = SchemaIR.toString(type_)
+        let exists = unique->Array.some(t => SchemaIR.toString(t) == typeStr)
+        if !exists { unique->Array.push(type_) }
+      })
+      
+      // Simplify single-element unions
+      switch unique {
+      | [] => SchemaIR.Unknown
+      | [single] => single
+      | multiple => SchemaIR.Union(multiple)
+      }
+    }
+  | SchemaIR.Intersection(types) => {
+      // Flatten nested intersections
+      let flattened = types->Array.flatMap(t => {
+        switch optimizeIR(t) {
+        | SchemaIR.Intersection(inner) => inner
+        | other => [other]
+        }
+      })
+      
+      // Simplify single-element intersections
+      switch flattened {
+      | [] => SchemaIR.Unknown
+      | [single] => single
+      | multiple => SchemaIR.Intersection(multiple)
+      }
+    }
+  | SchemaIR.Option(inner) => SchemaIR.Option(optimizeIR(inner))
+  | SchemaIR.Array({items, constraints}) => 
+      SchemaIR.Array({items: optimizeIR(items), constraints})
+  | SchemaIR.Object({properties, additionalProperties}) => {
+      let newProperties = properties->Array.map(((name, type_, required)) => {
+        (name, optimizeIR(type_), required)
+      })
+      let newAdditionalProps = additionalProperties->Option.map(optimizeIR)
+      SchemaIR.Object({
+        properties: newProperties,
+        additionalProperties: newAdditionalProps,
+      })
+    }
+  | other => other
+  }
+}

package/src/core/SchemaRefResolver.res

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// SchemaRefResolver.res - Bindings to @readme/openapi-parser
+
+// Parser options type
+type parserOptions = {
+  timeoutMs?: int,
+}
+
+// External bindings to @readme/openapi-parser v5.x
+@module("@readme/openapi-parser")
+external parse: (string, ~options: parserOptions=?) => promise<JSON.t> = "parse"
+
+@module("@readme/openapi-parser")
+external bundle: (string, ~options: parserOptions=?) => promise<JSON.t> = "bundle"
+
+@module("@readme/openapi-parser")
+external dereference: (string, ~options: parserOptions=?) => promise<JSON.t> = "dereference"
+
+@module("@readme/openapi-parser")
+external validate: (string, ~options: parserOptions=?) => promise<JSON.t> = "validate"
+
+// Helper to convert JSON to OpenAPISpec
+let jsonToSpec = (json: JSON.t): result<Types.openAPISpec, string> => {
+  switch json->JSON.Decode.object {
+  | Some(obj) => {
+      // Convert to our OpenAPISpec type
+      let pathsDict = obj
+        ->Dict.get("paths")
+        ->Option.flatMap(JSON.Decode.object)
+        ->Option.getOr(Dict.make())
+      
+      let openAPISpec: Types.openAPISpec = {
+        openapi: obj
+          ->Dict.get("openapi")
+          ->Option.flatMap(JSON.Decode.string)
+          ->Option.getOr("3.1.0"),
+        info: {
+          let infoObj = obj
+            ->Dict.get("info")
+            ->Option.flatMap(JSON.Decode.object)
+            ->Option.getOr(Dict.make())
+          {
+            title: infoObj
+              ->Dict.get("title")
+              ->Option.flatMap(JSON.Decode.string)
+              ->Option.getOr("Untitled API"),
+            version: infoObj
+              ->Dict.get("version")
+              ->Option.flatMap(JSON.Decode.string)
+              ->Option.getOr("0.0.0"),
+            description: infoObj
+              ->Dict.get("description")
+              ->Option.flatMap(JSON.Decode.string),
+          }
+        },
+        paths: pathsDict
+          ->Dict.toArray
+          ->Array.map(((key, _value)) => (key, Obj.magic(_value)))
+          ->Dict.fromArray,
+        components: obj
+          ->Dict.get("components")
+          ->Option.map(_comp => ({
+            schemas: _comp
+              ->JSON.Decode.object
+              ->Option.flatMap(c => c->Dict.get("schemas"))
+              ->Option.flatMap(JSON.Decode.object)
+              ->Option.map(schemas => 
+                schemas
+                ->Dict.toArray
+                ->Array.map(((key, value)) => (key, Obj.magic(value)))
+                ->Dict.fromArray
+              ),
+          }: Types.components)),
+      }
+      
+      Ok(openAPISpec)
+    }
+  | None => Error("Invalid OpenAPI spec: root is not an object")
+  }
+}
+
+// Resolve a spec from source
+let resolve = async (source: string, ~timeout: option<int>=?): result<Types.openAPISpec, string> => {
+  try {
+    // Use bundle to combine all external refs while keeping internal $refs intact
+    let options = {timeoutMs: timeout->Option.getOr(60000)}
+    let resolved = await bundle(source, ~options)
+    
+    jsonToSpec(resolved)
+  } catch {
+  | JsExn(err) => {
+      let message = err->JsExn.message->Option.getOr("Unknown error resolving spec")
+      Error(`Failed to resolve spec: ${message}`)
+    }
+  | _ => Error("Unknown error resolving spec")
+  }
+}
+
+// Parse an OpenAPI spec without dereferencing
+let parseOnly = async (source: string, ~timeout: option<int>=?): result<Types.openAPISpec, string> => {
+  try {
+    let options = {timeoutMs: timeout->Option.getOr(60000)}
+    let parsed = await parse(source, ~options)
+    jsonToSpec(parsed)
+  } catch {
+  | JsExn(err) => {
+      let message = err->JsExn.message->Option.getOr("Unknown error parsing spec")
+      Error(`Failed to parse spec: ${message}`)
+    }
+  | _ => Error("Unknown error parsing spec")
+  }
+}
+
+// Bundle an OpenAPI spec (combines all external references into a single file)
+let bundleSpec = async (source: string, ~timeout: option<int>=?): result<JSON.t, string> => {
+  try {
+    let options = {timeoutMs: timeout->Option.getOr(60000)}
+    let bundled = await bundle(source, ~options)
+    Ok(bundled)
+  } catch {
+  | JsExn(err) => {
+      let message = err->JsExn.message->Option.getOr("Unknown error bundling spec")
+      Error(`Failed to bundle spec: ${message}`)
+    }
+  | _ => Error("Unknown error bundling spec")
+  }
+}
+
+// Validate an OpenAPI spec
+let validateSpec = async (source: string, ~timeout: option<int>=?): result<Types.openAPISpec, string> => {
+  try {
+    let options = {timeoutMs: timeout->Option.getOr(60000)}
+    let validated = await validate(source, ~options)
+    jsonToSpec(validated)
+  } catch {
+  | JsExn(err) => {
+      let message = err->JsExn.message->Option.getOr("Unknown error validating spec")
+      Error(`Failed to validate spec: ${message}`)
+    }
+  | _ => Error("Unknown error validating spec")
+  }
+}

package/src/core/SchemaRegistry.res

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// SchemaRegistry.res - Registry for resolving $ref references in OpenAPI specs
+// 
+// This module provides a way to:
+// 1. Store all component schemas from an OpenAPI spec
+// 2. Resolve $ref strings to their underlying jsonSchema
+// 3. Track which schemas are being visited to detect circular references
+
+open Types
+
+// The registry type
+type t = {
+  // All schemas from components.schemas
+  schemas: Dict.t<jsonSchema>,
+  // Track visited schemas during resolution to detect cycles
+  mutable visiting: array<string>,
+}
+
+// Create a registry from an OpenAPI spec
+let fromSpec = (spec: openAPISpec): t => {
+  let schemas = switch spec.components {
+  | None => Dict.make()
+  | Some(components) => {
+      switch components.schemas {
+      | None => Dict.make()
+      | Some(s) => s
+      }
+    }
+  }
+  
+  {
+    schemas,
+    visiting: [],
+  }
+}
+
+// Create an empty registry
+let empty = (): t => {
+  {
+    schemas: Dict.make(),
+    visiting: [],
+  }
+}
+
+// Extract schema name from a $ref string
+// e.g., "#/components/schemas/Note" -> Some("Note")
+let extractSchemaName = (ref: string): option<string> => {
+  let prefix = "#/components/schemas/"
+  if String.startsWith(ref, prefix) {
+    Some(String.slice(ref, ~start=String.length(prefix)))
+  } else {
+    None
+  }
+}
+
+// Check if a schema name is currently being visited (cycle detection)
+let isVisiting = (registry: t, name: string): bool => {
+  registry.visiting->Array.includes(name)
+}
+
+// Start visiting a schema (for cycle detection)
+let startVisiting = (registry: t, name: string): unit => {
+  registry.visiting = Array.concat(registry.visiting, [name])
+}
+
+// Stop visiting a schema
+let stopVisiting = (registry: t, name: string): unit => {
+  registry.visiting = registry.visiting->Array.filter(n => n != name)
+}
+
+// Look up a schema by name
+let getSchema = (registry: t, name: string): option<jsonSchema> => {
+  Dict.get(registry.schemas, name)
+}
+
+// Look up a schema by $ref string
+let resolveRef = (registry: t, ref: string): option<jsonSchema> => {
+  switch extractSchemaName(ref) {
+  | None => None
+  | Some(name) => getSchema(registry, name)
+  }
+}
+
+// Get all schema names
+let getSchemaNames = (registry: t): array<string> => {
+  Dict.keysToArray(registry.schemas)
+}
+
+// Check if a schema exists
+let hasSchema = (registry: t, name: string): bool => {
+  Dict.get(registry.schemas, name)->Option.isSome
+}
+
+// Add a schema to the registry
+let addSchema = (registry: t, name: string, schema: jsonSchema): unit => {
+  Dict.set(registry.schemas, name, schema)
+}
+
+// Merge schemas from another registry
+let merge = (registry: t, other: t): unit => {
+  Dict.toArray(other.schemas)->Array.forEach(((name, schema)) => {
+    if !hasSchema(registry, name) {
+      addSchema(registry, name, schema)
+    }
+  })
+}