@zudojs/openapi 0.0.1 → 1.1.0

package/dist/openApiRouting/routeConverter.core.js

@@ -1,27 +1,5 @@
-/**
- * Converts a Zudojs-style route path to an OpenAPI path template.
- *
- * Example:
- *   "/users/:id" -> "/users/{id}"
- *   "/users/:id?": throws (optional path params not supported in OpenAPI)
- */
-export function toOpenAPIPath(path) {
-    if (path.includes(":")) {
-        const segments = path.split("/");
-        const openApiSegments = segments.map((segment) => {
-            if (segment.startsWith(":") && segment.endsWith("?")) {
-                throw new Error(`Optional path parameter "${segment}" is not supported in OpenAPI. ` +
-                    `Use separate routes or a query parameter instead.`);
-            }
-            if (segment.startsWith(":")) {
-                return `{${segment.slice(1)}}`;
-            }
-            return segment;
-        });
-        return openApiSegments.join("/");
-    }
-    return path;
-}
+import { OpenAPIRouteError } from "../openApiErrors/openApiError.types.js";
+import { PATH_TEMPLATE_PARAMETER } from "../openApiConstants/openApiConstants.core.js";
 /**
  * Maps Zudojs HTTP methods to OpenAPI methods.
  */
@@ -35,49 +13,117 @@ export const ZUDOLIB_TO_OPENAPI_METHODS = [
     "patch",
     "trace",
 ];
+/** True when `method` is one an OpenAPI path item can carry. */
+export function isOpenAPIMethod(method) {
+    return ZUDOLIB_TO_OPENAPI_METHODS.includes(method.toLowerCase());
+}
+/** A `:name` path segment, optionally suffixed with `?`. */
+const COLON_PARAMETER = /^:([A-Za-z0-9_]+)(\?)?$/;
+/**
+ * Converts a Zudojs-style route path to an OpenAPI path template.
+ *
+ * Example:
+ *   `/users/:id` → `/users/{id}`
+ *   `/users/{id}` → unchanged (already a template)
+ *   `/users/:id?` → throws (OpenAPI has no optional path parameters)
+ *   `/files/*` → throws (OpenAPI has no wildcard paths)
+ *
+ * Anything it cannot convert throws rather than passing through: an
+ * unconvertible segment that reaches the document produces an invalid path
+ * template, and the failure then surfaces in whatever consumes the spec
+ * rather than at the route that caused it.
+ */
+export function toOpenAPIPath(path) {
+    if (!path.startsWith("/")) {
+        throw new OpenAPIRouteError(`Route path "${path}" must start with "/" to be a valid OpenAPI path.`, { metadata: { path } });
+    }
+    const segments = path.split("/").map((segment) => {
+        if (segment === "")
+            return segment;
+        if (segment === "*" || segment.startsWith("*")) {
+            throw new OpenAPIRouteError(`Wildcard path segment "${segment}" in "${path}" is not supported in OpenAPI. ` +
+                `Declare the concrete paths, or document it as a single templated parameter.`, { metadata: { path, segment } });
+        }
+        const colon = COLON_PARAMETER.exec(segment);
+        if (colon) {
+            if (colon[2] === "?") {
+                throw new OpenAPIRouteError(`Optional path parameter "${segment}" in "${path}" is not supported in OpenAPI. ` +
+                    `Use separate routes or a query parameter instead.`, { metadata: { path, segment } });
+            }
+            return `{${colon[1]}}`;
+        }
+        if (segment.startsWith(":")) {
+            throw new OpenAPIRouteError(`Path parameter "${segment}" in "${path}" uses a syntax OpenAPI cannot express ` +
+                `(typed or pattern-constrained parameters). Use a plain ":name" segment and ` +
+                `describe the constraint with a parameter schema.`, { metadata: { path, segment } });
+        }
+        return segment;
+    });
+    return segments.join("/");
+}
+/** Extracts the parameter names from an OpenAPI path template. */
+export function extractPathParameters(path) {
+    const names = [];
+    for (const match of path.matchAll(PATH_TEMPLATE_PARAMETER)) {
+        const name = match[1];
+        if (name !== undefined)
+            names.push(name);
+    }
+    return names;
+}
+function toParameter(parameter) {
+    return {
+        name: parameter.name,
+        in: parameter.in,
+        ...(parameter.description ? { description: parameter.description } : {}),
+        // A path parameter is required by the specification, so declaring one
+        // that is not required is a document that cannot validate.
+        required: parameter.in === "path" ? true : (parameter.required ?? false),
+        ...(parameter.deprecated ? { deprecated: true } : {}),
+        ...(parameter.schema !== undefined ? { schema: parameter.schema } : {}),
+        ...(parameter.example !== undefined ? { example: parameter.example } : {}),
+    };
+}
+/**
+ * Builds the `responses` object for an operation.
+ *
+ * Every documented response is carried through. Only when a route documents
+ * none at all is a `200` synthesized, because `responses` is required.
+ */
+export function buildResponses(metadata) {
+    const declared = metadata?.openapi?.responses;
+    if (declared && Object.keys(declared).length > 0) {
+        return Object.freeze({ ...declared });
+    }
+    return Object.freeze({ "200": { description: "OK" } });
+}
 /**
  * Converts a route with metadata into an OpenAPI operation.
  */
 export function convertRouteToOpenAPI(method, path, metadata) {
+    if (!isOpenAPIMethod(method)) {
+        throw new OpenAPIRouteError(`HTTP method "${method}" has no OpenAPI path item field. ` +
+            `Supported: ${ZUDOLIB_TO_OPENAPI_METHODS.join(", ")}.`, { metadata: { method, path } });
+    }
     const openApiPath = toOpenAPIPath(path);
-    const openApiMetadata = metadata?.openapi;
+    const meta = metadata?.openapi;
     const operation = {
-        responses: openApiMetadata?.responses
-            ? {
-                "200": {
-                    description: "OK",
-                    ...(openApiMetadata.responses["200"] ?? {}),
-                },
-            }
-            : { "200": { description: "OK" } },
-        ...(openApiMetadata?.operationId
-            ? { operationId: openApiMetadata.operationId }
-            : {}),
-        ...(openApiMetadata?.summary ? { summary: openApiMetadata.summary } : {}),
-        ...(openApiMetadata?.description
-            ? { description: openApiMetadata.description }
-            : {}),
-        ...(openApiMetadata?.tags?.length
-            ? { tags: [...openApiMetadata.tags] }
-            : {}),
-        ...(openApiMetadata?.deprecated !== undefined
-            ? { deprecated: openApiMetadata.deprecated }
-            : {}),
-        ...(openApiMetadata?.parameters?.length
-            ? { parameters: [...openApiMetadata.parameters] }
-            : {}),
-        ...(openApiMetadata?.requestBody
-            ? { requestBody: openApiMetadata.requestBody }
-            : {}),
-        ...(openApiMetadata?.security?.length
-            ? { security: [...openApiMetadata.security] }
-            : {}),
-        ...(openApiMetadata?.servers?.length
-            ? { servers: [...openApiMetadata.servers] }
+        ...(meta?.operationId ? { operationId: meta.operationId } : {}),
+        ...(meta?.summary ? { summary: meta.summary } : {}),
+        ...(meta?.description ? { description: meta.description } : {}),
+        ...(meta?.tags?.length ? { tags: [...meta.tags] } : {}),
+        ...(meta?.deprecated !== undefined ? { deprecated: meta.deprecated } : {}),
+        ...(meta?.parameters?.length
+            ? { parameters: meta.parameters.map(toParameter) }
             : {}),
+        ...(meta?.requestBody ? { requestBody: meta.requestBody } : {}),
+        ...(meta?.security?.length ? { security: [...meta.security] } : {}),
+        ...(meta?.servers?.length ? { servers: [...meta.servers] } : {}),
+        ...(meta?.externalDocs ? { externalDocs: meta.externalDocs } : {}),
+        responses: buildResponses(metadata),
     };
     return {
-        method,
+        method: method.toLowerCase(),
         path: openApiPath,
         operation,
     };

package/dist/openApiRouting/routeMetadata.type.d.ts

@@ -1,22 +1,15 @@
-import type { OpenAPIRequestBody } from "../openApiTypes/openApiTypes.core.js";
 /**
- * Metadata attached to a route for OpenAPI generation.
+ * Route metadata consumed by the OpenAPI generator.
+ *
+ * This is the single definition of these shapes. They were previously
+ * declared in both this file and the scanner, and had already drifted —
+ * `requestBody` was typed one way in one copy and `unknown` in the other,
+ * so which one a consumer got depended on the import path they happened to
+ * use.
  */
-export interface RouteOpenAPIMetadata {
-    readonly operationId?: string;
-    readonly summary?: string;
-    readonly description?: string;
-    readonly tags?: readonly string[];
-    readonly deprecated?: boolean;
-    readonly parameters?: readonly RouteParameterMetadata[];
-    readonly requestBody?: OpenAPIRequestBody;
-    readonly responses?: Record<string, unknown>;
-    readonly security?: readonly Record<string, readonly string[]>[];
-    readonly servers?: readonly {
-        readonly url: string;
-        readonly description?: string;
-    }[];
-}
+import type { OpenAPIExternalDocumentation, OpenAPIRequestBody, OpenAPIResponse, OpenAPISecurityRequirement, OpenAPIServer } from "../openApiTypes/openApiTypes.core.js";
+/** HTTP methods an OpenAPI path item can carry. */
+export type OpenAPIHttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
 /**
  * Parameter metadata for OpenAPI generation.
  */
@@ -29,10 +22,40 @@ export interface RouteParameterMetadata {
     readonly schema?: unknown;
     readonly example?: unknown;
 }
+/**
+ * Metadata attached to a route for OpenAPI generation.
+ */
+export interface RouteOpenAPIMetadata {
+    readonly operationId?: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly deprecated?: boolean;
+    readonly parameters?: readonly RouteParameterMetadata[];
+    readonly requestBody?: OpenAPIRequestBody;
+    /**
+     * Responses keyed by status code, `default`, or a `2XX`-style range.
+     * Every entry reaches the document — this is not a 200-only field.
+     */
+    readonly responses?: Readonly<Record<string, OpenAPIResponse>>;
+    readonly security?: readonly OpenAPISecurityRequirement[];
+    readonly servers?: readonly OpenAPIServer[];
+    readonly externalDocs?: OpenAPIExternalDocumentation;
+    /** Excludes the route from the generated document. */
+    readonly hidden?: boolean;
+}
 /**
  * Route metadata container.
  */
 export interface RouteMetadata {
     readonly openapi?: RouteOpenAPIMetadata;
 }
+/**
+ * Route information accepted by the scanner.
+ */
+export interface RouteInfo {
+    readonly method: OpenAPIHttpMethod;
+    readonly path: string;
+    readonly metadata?: RouteMetadata;
+}
 //# sourceMappingURL=routeMetadata.type.d.ts.map

package/dist/openApiRouting/routeMetadata.type.js

@@ -1,2 +1,11 @@
+/**
+ * Route metadata consumed by the OpenAPI generator.
+ *
+ * This is the single definition of these shapes. They were previously
+ * declared in both this file and the scanner, and had already drifted —
+ * `requestBody` was typed one way in one copy and `unknown` in the other,
+ * so which one a consumer got depended on the import path they happened to
+ * use.
+ */
 export {};
 //# sourceMappingURL=routeMetadata.type.js.map

package/dist/openApiRouting/routeScanner.core.d.ts

@@ -1,56 +1,26 @@
 import type { OpenAPIRoute } from "../openApiRegistry/openApiRegistry.type.js";
+import type { RouteInfo } from "./routeMetadata.type.js";
 /**
- * Metadata attached to a route for OpenAPI generation.
- */
-export interface RouteOpenAPIMetadata {
-    readonly operationId?: string;
-    readonly summary?: string;
-    readonly description?: string;
-    readonly tags?: readonly string[];
-    readonly deprecated?: boolean;
-    readonly parameters?: readonly RouteParameterMetadata[];
-    readonly requestBody?: unknown;
-    readonly responses?: Record<string, unknown>;
-    readonly security?: readonly Record<string, readonly string[]>[];
-    readonly servers?: readonly {
-        readonly url: string;
-        readonly description?: string;
-    }[];
-}
-/**
- * Parameter metadata for OpenAPI generation.
- */
-export interface RouteParameterMetadata {
-    readonly name: string;
-    readonly in: "query" | "header" | "path" | "cookie";
-    readonly description?: string;
-    readonly required?: boolean;
-    readonly deprecated?: boolean;
-    readonly schema?: unknown;
-    readonly example?: unknown;
-}
-/**
- * Route metadata container.
- */
-export interface RouteMetadata {
-    readonly openapi?: RouteOpenAPIMetadata;
-}
-/**
- * Route information for scanning.
- */
-export interface RouteInfo {
-    readonly method: "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
-    readonly path: string;
-    readonly metadata?: {
-        readonly openapi?: RouteOpenAPIMetadata;
-    };
-}
-/**
- * Default OpenAPI route scanner implementation.
+ * Collects routes and converts them into OpenAPI operations.
+ *
+ * Duplicates are rejected on the way in. Accepting them and letting the
+ * registry throw during generation reported the problem far from the
+ * `addRoute` call that caused it, and only after some routes had already been
+ * registered.
  */
 export declare class OpenAPIRouteScannerImpl {
     private readonly routes;
+    /** Registers a route. */
     addRoute(route: RouteInfo): void;
+    /** Registers a route, replacing any existing one for the same method+path. */
+    setRoute(route: RouteInfo): void;
+    /** True when a route is registered for this method and path. */
+    hasRoute(method: string, path: string): boolean;
+    /** Removes a route. Returns whether one was removed. */
+    removeRoute(method: string, path: string): boolean;
+    /** Number of registered routes. */
+    get size(): number;
+    /** Converts every registered route into an OpenAPI operation. */
     scan(): readonly OpenAPIRoute[];
     clear(): void;
 }

package/dist/openApiRouting/routeScanner.core.js

@@ -1,71 +1,56 @@
-import { toOpenAPIPath } from "./routeConverter.core.js";
+import { convertRouteToOpenAPI } from "./routeConverter.core.js";
+import { OpenAPIRouteError } from "../openApiErrors/openApiError.types.js";
 /**
- * Default OpenAPI route scanner implementation.
+ * Collects routes and converts them into OpenAPI operations.
+ *
+ * Duplicates are rejected on the way in. Accepting them and letting the
+ * registry throw during generation reported the problem far from the
+ * `addRoute` call that caused it, and only after some routes had already been
+ * registered.
  */
 export class OpenAPIRouteScannerImpl {
-    routes = [];
+    routes = new Map();
+    /** Registers a route. */
     addRoute(route) {
-        this.routes.push(route);
+        const key = `${route.method.toLowerCase()}:${route.path}`;
+        if (this.routes.has(key)) {
+            throw new OpenAPIRouteError(`Route ${route.method.toUpperCase()} ${route.path} is already registered.`, { metadata: { method: route.method, path: route.path } });
+        }
+        this.routes.set(key, route);
+    }
+    /** Registers a route, replacing any existing one for the same method+path. */
+    setRoute(route) {
+        this.routes.set(`${route.method.toLowerCase()}:${route.path}`, route);
+    }
+    /** True when a route is registered for this method and path. */
+    hasRoute(method, path) {
+        return this.routes.has(`${method.toLowerCase()}:${path}`);
+    }
+    /** Removes a route. Returns whether one was removed. */
+    removeRoute(method, path) {
+        return this.routes.delete(`${method.toLowerCase()}:${path}`);
+    }
+    /** Number of registered routes. */
+    get size() {
+        return this.routes.size;
     }
+    /** Converts every registered route into an OpenAPI operation. */
     scan() {
         const result = [];
-        for (const route of this.routes) {
-            const openApiPath = toOpenAPIPath(route.path);
-            const response200 = {
-                "200": {
-                    description: "OK",
-                    ...(route.metadata?.openapi?.responses?.["200"]
-                        ? route.metadata.openapi.responses["200"]
-                        : {}),
-                },
-            };
-            const operation = {
-                ...(route.metadata?.openapi?.operationId
-                    ? { operationId: route.metadata.openapi.operationId }
-                    : {}),
-                ...(route.metadata?.openapi?.summary
-                    ? { summary: route.metadata.openapi.summary }
-                    : {}),
-                ...(route.metadata?.openapi?.description
-                    ? { description: route.metadata.openapi.description }
-                    : {}),
-                ...(route.metadata?.openapi?.tags?.length
-                    ? { tags: [...route.metadata.openapi.tags] }
-                    : {}),
-                ...(route.metadata?.openapi?.deprecated !== undefined
-                    ? { deprecated: route.metadata.openapi.deprecated }
-                    : {}),
-                ...(route.metadata?.openapi?.parameters?.length
-                    ? {
-                        parameters: [
-                            ...route.metadata.openapi.parameters,
-                        ],
-                    }
-                    : {}),
-                ...(route.metadata?.openapi?.requestBody
-                    ? {
-                        requestBody: route.metadata.openapi
-                            .requestBody,
-                    }
-                    : {}),
-                ...(route.metadata?.openapi?.security?.length
-                    ? { security: [...route.metadata.openapi.security] }
-                    : {}),
-                ...(route.metadata?.openapi?.servers?.length
-                    ? { servers: [...route.metadata.openapi.servers] }
-                    : {}),
-                responses: response200,
-            };
+        for (const route of this.routes.values()) {
+            if (route.metadata?.openapi?.hidden === true)
+                continue;
+            const converted = convertRouteToOpenAPI(route.method, route.path, route.metadata);
             result.push({
-                method: route.method,
-                path: openApiPath,
-                operation: operation,
+                method: converted.method,
+                path: converted.path,
+                operation: converted.operation,
             });
         }
         return result;
     }
     clear() {
-        this.routes.length = 0;
+        this.routes.clear();
     }
 }
 //# sourceMappingURL=routeScanner.core.js.map

package/dist/openApiSchema/index.d.ts

@@ -3,9 +3,9 @@
  *
  * Schema conversion and registry for OpenAPI generation.
  */
-export type { SchemaConverter, SchemaConversionResult, } from "./schemaConverter.core.js";
-export { convertSchema, createSchemaConverter, } from "./schemaConverter.core.js";
-export type { SchemaRegistry } from "./schemaRegistry.core.js";
+export type { SchemaConverter, SchemaConversionResult, SchemaConversionOptions, } from "./schemaConverter.core.js";
+export { convertSchema, createSchemaConverter, isVersion31, } from "./schemaConverter.core.js";
+export type { SchemaRegistry, SchemaRegistryOptions, } from "./schemaRegistry.core.js";
 export { SchemaRegistryImpl } from "./schemaRegistry.core.js";
-export { createComponentReference } from "./references.core.js";
+export { createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, type ComponentSection, } from "./references.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiSchema/index.js

@@ -3,7 +3,7 @@
  *
  * Schema conversion and registry for OpenAPI generation.
  */
-export { convertSchema, createSchemaConverter, } from "./schemaConverter.core.js";
+export { convertSchema, createSchemaConverter, isVersion31, } from "./schemaConverter.core.js";
 export { SchemaRegistryImpl } from "./schemaRegistry.core.js";
-export { createComponentReference } from "./references.core.js";
+export { createComponentReference, escapeJsonPointerSegment, unescapeJsonPointerSegment, } from "./references.core.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiSchema/references.core.d.ts

@@ -1,9 +1,26 @@
 import type { OpenAPIReference } from "../openApiTypes/openApiTypes.core.js";
+/** The component sections a `$ref` may point into. */
+export type ComponentSection = "schemas" | "responses" | "parameters" | "requestBodies" | "headers" | "examples" | "securitySchemes" | "links" | "callbacks";
+/**
+ * Escapes a component name for use inside a JSON Pointer.
+ *
+ * RFC 6901 reserves `~` and `/`; a component called `Order/Line` produces a
+ * pointer that resolves to the wrong place — or nowhere — unless they are
+ * escaped. The `~0` substitution must come first, or the `~1` it introduces
+ * would be escaped again.
+ */
+export declare function escapeJsonPointerSegment(segment: string): string;
+/** Reverses {@link escapeJsonPointerSegment}. */
+export declare function unescapeJsonPointerSegment(segment: string): string;
 /**
  * Creates an OpenAPI component reference.
  *
+ * This is the single `$ref` builder in the package — the registry and the
+ * schema registry both delegate here, so escaping cannot be right in one
+ * place and missing in another.
+ *
  * @param section - The component section (e.g., "schemas", "responses")
  * @param name - The component name
  */
-export declare function createComponentReference(section: string, name: string): OpenAPIReference;
+export declare function createComponentReference(section: ComponentSection | string, name: string): OpenAPIReference;
 //# sourceMappingURL=references.core.d.ts.map

package/dist/openApiSchema/references.core.js

@@ -1,12 +1,32 @@
+import { COMPONENT_REF_PREFIX } from "../openApiConstants/openApiConstants.core.js";
+/**
+ * Escapes a component name for use inside a JSON Pointer.
+ *
+ * RFC 6901 reserves `~` and `/`; a component called `Order/Line` produces a
+ * pointer that resolves to the wrong place — or nowhere — unless they are
+ * escaped. The `~0` substitution must come first, or the `~1` it introduces
+ * would be escaped again.
+ */
+export function escapeJsonPointerSegment(segment) {
+    return segment.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+/** Reverses {@link escapeJsonPointerSegment}. */
+export function unescapeJsonPointerSegment(segment) {
+    return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
 /**
  * Creates an OpenAPI component reference.
  *
+ * This is the single `$ref` builder in the package — the registry and the
+ * schema registry both delegate here, so escaping cannot be right in one
+ * place and missing in another.
+ *
  * @param section - The component section (e.g., "schemas", "responses")
  * @param name - The component name
  */
 export function createComponentReference(section, name) {
     return {
-        $ref: `#/components/${section}/${name}`,
+        $ref: `${COMPONENT_REF_PREFIX}/${escapeJsonPointerSegment(section)}/${escapeJsonPointerSegment(name)}`,
     };
 }
 //# sourceMappingURL=references.core.js.map

package/dist/openApiSchema/schemaConverter.core.d.ts

@@ -1,11 +1,59 @@
 import type { OpenAPISchema } from "../openApiTypes/openApiTypes.core.js";
+/**
+ * Converts `@zudojs/schema` schemas into OpenAPI schema objects.
+ *
+ * The conversion reads the schema classes' runtime fields directly rather
+ * than importing them, so this package stays usable with any object that
+ * follows the same shape. That structural coupling is the reason every field
+ * name below is named in one place and covered by tests: a rename in
+ * `@zudojs/schema` is not a compile error here, it is a silently empty
+ * document.
+ *
+ * Field names as of `@zudojs/schema@0.1.0`:
+ *   object   `_config.shape`, `_config.requiredKeys` (a Set), `_config.unknownKeys`
+ *   array    `_config.itemSchema`, `_config.min`, `_config.max`, `_config.length`
+ *   string   `_config.min|max|length|pattern|format`
+ *   number   `_config.min|max|int|gt|lt|multipleOf`
+ *   union    `_schemas`          intersection `_left` / `_right`
+ *   enum     `_values`           literal      `_expected`
+ *   optional `_inner`            nullable     `_inner`
+ *   default  `_inner`, `_defaultValue`        refine `_inner`
+ *   transform `_base`            lazy         `_factory` / `_inner`
+ *   record   `_keySchema`, `_valueSchema`     tuple  `_schemas`
+ *   map      `_keySchema`, `_valueSchema`     set    `_valueSchema`
+ *   metadata `_metadata` (description, example, title, deprecated)
+ */
 export interface SchemaConversionResult {
     readonly schema: OpenAPISchema;
     readonly warnings: readonly string[];
 }
-export declare function convertSchema(input: unknown, _visited?: Set<object>): SchemaConversionResult;
+/** Options controlling how a schema is converted. */
+export interface SchemaConversionOptions {
+    /**
+     * Target specification version. 3.1 expresses nullability as
+     * `type: [t, "null"]`; 3.0 uses `nullable: true`, which 3.1 removed.
+     */
+    readonly version?: string;
+    /**
+     * Depth at which conversion stops descending. Guards against a recursive
+     * schema whose `lazy` wrapper resolves to itself. Default: 32.
+     */
+    readonly maxDepth?: number;
+}
+/** True when the document being produced follows OpenAPI 3.1 or later. */
+export declare function isVersion31(version: string): boolean;
+/**
+ * Converts a schema into an OpenAPI schema object.
+ *
+ * Warnings describe everything that could not be represented exactly. They
+ * are part of the result rather than a side channel, because silently
+ * emitting `{}` for an unsupported construct is how a specification ends up
+ * documenting nothing.
+ */
+export declare function convertSchema(input: unknown, options?: SchemaConversionOptions): SchemaConversionResult;
 export interface SchemaConverter {
-    convert(input: unknown, visited?: Set<object>): SchemaConversionResult;
+    convert(input: unknown, options?: SchemaConversionOptions): SchemaConversionResult;
 }
-export declare function createSchemaConverter(): SchemaConverter;
+/** Creates a converter bound to a specification version. */
+export declare function createSchemaConverter(defaults?: SchemaConversionOptions): SchemaConverter;
 //# sourceMappingURL=schemaConverter.core.d.ts.map