@mintlify/validation 0.1.177 → 0.1.179

package/dist/openapi/OpenApiToEndpointConverter.js

@@ -1,20 +1,19 @@
 import { BaseConverter } from './BaseConverter.js';
-import { ParametersConverter } from './ParametersConverter.js';
+import { generateFirstIncrementalSchema } from './IncrementalEvaluator.js';
+import { IncrementalParametersConverter, ParametersConverter } from './ParametersConverter.js';
 import { SchemaConverter } from './SchemaConverter.js';
 import { SecurityConverter } from './SecurityConverter.js';
 import { ServersConverter } from './ServersConverter.js';
 import { InvalidSchemaError } from './errors.js';
 import { generateExampleFromSchema } from './generateExampleFromSchema.js';
-export class OpenApiToEndpointConverter extends BaseConverter {
+import { dereference } from './utils.js';
+export class BaseOpenApiToEndpointConverter extends BaseConverter {
     constructor(document, path, method, safeParse = false) {
         super(safeParse);
         this.document = document;
         this.path = path;
         this.method = method;
         this.safeParse = safeParse;
-    }
-    convert() {
-        var _a, _b, _c, _d, _e;
         const paths = this.document.paths;
         if (paths === undefined) {
             throw new InvalidSchemaError(['#'], 'paths not defined');
@@ -23,25 +22,27 @@ export class OpenApiToEndpointConverter extends BaseConverter {
         if (pathObject === undefined) {
             throw new InvalidSchemaError(['#', 'paths'], `path not defined: ${this.path}`);
         }
+        this.pathObject = pathObject;
         const operationObject = pathObject[this.method];
         if (operationObject === undefined) {
             throw new InvalidSchemaError(['#', 'paths', this.path], `operation does not exist: ${this.method}`);
         }
-        const securityRequirements = (_a = operationObject.security) !== null && _a !== void 0 ? _a : this.document.security;
+        this.operationObject = operationObject;
+    }
+    convert() {
+        var _a, _b, _c, _d, _e;
+        const securityRequirements = (_a = this.operationObject.security) !== null && _a !== void 0 ? _a : this.document.security;
         const securitySchemes = (_b = this.document.components) === null || _b === void 0 ? void 0 : _b.securitySchemes;
         const security = SecurityConverter.convert(securityRequirements, securitySchemes, this.safeParse);
-        const pathParameters = pathObject.parameters;
-        const operationParameters = operationObject.parameters;
-        const parameters = ParametersConverter.convert(this.method, pathParameters, operationParameters, ['#', 'paths', this.path], this.safeParse);
-        const servers = ServersConverter.convert((_d = (_c = operationObject.servers) !== null && _c !== void 0 ? _c : pathObject.servers) !== null && _d !== void 0 ? _d : this.document.servers);
+        const parameters = this.convertParameters();
+        const servers = ServersConverter.convert((_d = (_c = this.operationObject.servers) !== null && _c !== void 0 ? _c : this.pathObject.servers) !== null && _d !== void 0 ? _d : this.document.servers);
         // title is a bit too specific to take from the path object
-        const title = operationObject.summary;
-        const description = (_e = operationObject.description) !== null && _e !== void 0 ? _e : pathObject.description;
-        const requestBody = operationObject.requestBody;
-        const body = this.convertContent(['#', 'paths', this.path, this.method, 'requestBody', 'content'], requestBody === null || requestBody === void 0 ? void 0 : requestBody.content, 'request', requestBody === null || requestBody === void 0 ? void 0 : requestBody.required);
-        const deprecated = !!operationObject.deprecated;
-        const codeSamples = this.convertCodeSamples(['#', 'paths', this.path, this.method], operationObject);
-        const response = this.convertResponses(['#', 'paths', this.path, this.method, 'responses'], operationObject.responses);
+        const title = this.operationObject.summary;
+        const description = (_e = this.operationObject.description) !== null && _e !== void 0 ? _e : this.pathObject.description;
+        const body = this.convertBody();
+        const deprecated = !!this.operationObject.deprecated;
+        const codeSamples = this.convertCodeSamples(['#', 'paths', this.path, this.method], this.operationObject);
+        const response = this.convertResponses();
         return {
             title,
             description,
@@ -58,24 +59,6 @@ export class OpenApiToEndpointConverter extends BaseConverter {
             deprecated,
         };
     }
-    convertContent(debugPath, content, location, required) {
-        if (content === undefined) {
-            return {};
-        }
-        const newEntries = Object.entries(content).map(([contentType, mediaObject]) => {
-            const schemaArray = SchemaConverter.convert({
-                schema: mediaObject.schema,
-                path: [...debugPath, contentType, 'schema'],
-                required,
-                location,
-                contentType,
-                safeParse: this.safeParse,
-            });
-            const examples = this.convertExamples(mediaObject.examples, mediaObject.example, schemaArray);
-            return [contentType, { schemaArray, examples }];
-        });
-        return Object.fromEntries(newEntries);
-    }
     convertExamples(examples, example, schemaArray) {
         if (examples && Object.values(examples).some(({ value }) => value !== undefined)) {
             return Object.fromEntries(Object.entries(examples)
@@ -94,13 +77,6 @@ export class OpenApiToEndpointConverter extends BaseConverter {
         }
         return { example: { value: generateExampleFromSchema(schemaArray[0]) } };
     }
-    convertResponses(debugPath, responses) {
-        const newEntries = Object.entries(responses).map(([statusCode, response]) => [
-            statusCode,
-            this.convertContent([...debugPath, statusCode, 'content'], response.content, 'response'),
-        ]);
-        return Object.fromEntries(newEntries);
-    }
     convertCodeSamples(debugPath, operation) {
         let key;
         let rawCodeSamples;
@@ -140,7 +116,115 @@ export class OpenApiToEndpointConverter extends BaseConverter {
         });
         return codeSamples;
     }
+}
+export class OpenApiToEndpointConverter extends BaseOpenApiToEndpointConverter {
+    convertBody() {
+        const requestBody = this.operationObject.requestBody;
+        return this.convertContent(['#', 'paths', this.path, this.method, 'requestBody', 'content'], requestBody === null || requestBody === void 0 ? void 0 : requestBody.content, 'request', requestBody === null || requestBody === void 0 ? void 0 : requestBody.required);
+    }
+    convertResponses() {
+        const responses = this.operationObject.responses;
+        if (!responses)
+            return {};
+        const newEntries = Object.entries(responses).map(([statusCode, response]) => [
+            statusCode,
+            this.convertContent(['#', 'paths', this.path, this.method, 'responses', statusCode, 'content'], response.content, 'response'),
+        ]);
+        return Object.fromEntries(newEntries);
+    }
+    convertContent(debugPath, content, location, required) {
+        if (content === undefined) {
+            return {};
+        }
+        const newEntries = Object.entries(content).map(([contentType, mediaObject]) => {
+            const schemaArray = SchemaConverter.convert({
+                schema: mediaObject.schema,
+                path: [...debugPath, contentType, 'schema'],
+                required,
+                location,
+                contentType,
+                safeParse: this.safeParse,
+            });
+            const examples = this.convertExamples(mediaObject.examples, mediaObject.example, schemaArray);
+            return [contentType, { schemaArray, examples }];
+        });
+        return Object.fromEntries(newEntries);
+    }
+    convertParameters() {
+        const pathParameters = this.pathObject.parameters;
+        const operationParameters = this.operationObject.parameters;
+        return ParametersConverter.convert(this.method, pathParameters, operationParameters, ['#', 'paths', this.path], this.safeParse);
+    }
     static convert(spec, path, method, safeParse) {
         return new OpenApiToEndpointConverter(spec, path, method, safeParse).convert();
     }
 }
+export class OpenApiToIncrementalEndpointConverter extends BaseOpenApiToEndpointConverter {
+    constructor(rawDocument, document, path, method, safeParse = false) {
+        super(document, path, method, safeParse);
+        this.rawDocument = rawDocument;
+    }
+    convertParameters() {
+        var _a, _b, _c, _d, _e;
+        const pathParameters = (_b = (_a = this.rawDocument.paths) === null || _a === void 0 ? void 0 : _a[this.path]) === null || _b === void 0 ? void 0 : _b.parameters;
+        const operationParameters = (_e = (_d = (_c = this.rawDocument.paths) === null || _c === void 0 ? void 0 : _c[this.path]) === null || _d === void 0 ? void 0 : _d[this.method]) === null || _e === void 0 ? void 0 : _e.parameters;
+        return IncrementalParametersConverter.convert(this.rawDocument, this.method, pathParameters, operationParameters, ['#', 'paths', this.path], this.safeParse);
+    }
+    convertBody() {
+        var _a, _b, _c, _d;
+        let rawRequestBody = (_c = (_b = (_a = this.rawDocument.paths) === null || _a === void 0 ? void 0 : _a[this.path]) === null || _b === void 0 ? void 0 : _b[this.method]) === null || _c === void 0 ? void 0 : _c.requestBody;
+        if (rawRequestBody && '$ref' in rawRequestBody) {
+            rawRequestBody = dereference('requestBodies', rawRequestBody.$ref, (_d = this.rawDocument.components) === null || _d === void 0 ? void 0 : _d.requestBodies);
+        }
+        if (!rawRequestBody || '$ref' in rawRequestBody)
+            return {};
+        const requestBody = this.operationObject.requestBody;
+        return this.convertContent(['#', 'paths', this.path, this.method, 'requestBody', 'content'], rawRequestBody.content, requestBody === null || requestBody === void 0 ? void 0 : requestBody.content, 'request', requestBody === null || requestBody === void 0 ? void 0 : requestBody.required);
+    }
+    convertResponses() {
+        var _a, _b, _c;
+        const rawResponses = (_c = (_b = (_a = this.rawDocument.paths) === null || _a === void 0 ? void 0 : _a[this.path]) === null || _b === void 0 ? void 0 : _b[this.method]) === null || _c === void 0 ? void 0 : _c.responses;
+        if (!rawResponses)
+            return {};
+        const newEntries = Object.entries(rawResponses).map(([statusCode, rawResponse]) => {
+            var _a, _b;
+            if ('$ref' in rawResponse) {
+                const dereferencedRes = dereference('responses', rawResponse.$ref, (_a = this.rawDocument.components) === null || _a === void 0 ? void 0 : _a.responses);
+                if (!dereferencedRes || '$ref' in dereferencedRes)
+                    throw Error();
+                rawResponse = dereferencedRes;
+            }
+            const response = (_b = this.operationObject.responses) === null || _b === void 0 ? void 0 : _b[statusCode];
+            return [
+                statusCode,
+                this.convertContent(['#', 'paths', this.path, this.method, 'responses', statusCode, 'content'], rawResponse.content, response === null || response === void 0 ? void 0 : response.content, 'response'),
+            ];
+        });
+        return Object.fromEntries(newEntries);
+    }
+    convertContent(debugPath, rawContent, dereferencedContent, location, required) {
+        if (!rawContent || !dereferencedContent) {
+            return {};
+        }
+        const newEntries = Object.entries(rawContent).map(([contentType, mediaObject]) => {
+            var _a;
+            const incrementalSchemaArray = generateFirstIncrementalSchema(mediaObject.schema, (_a = this.rawDocument.components) === null || _a === void 0 ? void 0 : _a.schemas, required, location, contentType);
+            // still need to generate schemaArray so we can generate examples
+            const dereferencedMediaObject = dereferencedContent[contentType];
+            const schemaArray = SchemaConverter.convert({
+                schema: dereferencedMediaObject === null || dereferencedMediaObject === void 0 ? void 0 : dereferencedMediaObject.schema,
+                path: [...debugPath, contentType, 'schema'],
+                required,
+                location,
+                contentType,
+                safeParse: this.safeParse,
+            });
+            const examples = this.convertExamples(dereferencedMediaObject === null || dereferencedMediaObject === void 0 ? void 0 : dereferencedMediaObject.examples, dereferencedMediaObject === null || dereferencedMediaObject === void 0 ? void 0 : dereferencedMediaObject.example, schemaArray);
+            return [contentType, { schemaArray: incrementalSchemaArray, examples }];
+        });
+        return Object.fromEntries(newEntries);
+    }
+    static convert(rawDocument, resolvedDocument, path, method, safeParse) {
+        return new OpenApiToIncrementalEndpointConverter(rawDocument, resolvedDocument, path, method, safeParse).convert();
+    }
+}

package/dist/openapi/ParametersConverter.d.ts

@@ -1,6 +1,6 @@
 import { OpenAPIV3_1 } from 'openapi-types';
 import { BaseConverter } from './BaseConverter.js';
-import { ParameterSections } from './types/endpoint.js';
+import { DataSchemaArray, IncrementalDataSchemaArray, ParameterSections } from './types/endpoint.js';
 export declare class ParametersConverter extends BaseConverter {
     readonly method: string;
     readonly pathParameters: OpenAPIV3_1.ParameterObject[] | undefined;
@@ -11,5 +11,18 @@ export declare class ParametersConverter extends BaseConverter {
     private constructor();
     private convert;
     private addParameter;
-    static convert(method: string, pathParameters: OpenAPIV3_1.ParameterObject[] | undefined, operationParameters: OpenAPIV3_1.ParameterObject[] | undefined, path: string[], safeParse?: boolean): ParameterSections;
+    static convert(method: string, pathParameters: OpenAPIV3_1.ParameterObject[] | undefined, operationParameters: OpenAPIV3_1.ParameterObject[] | undefined, path: string[], safeParse?: boolean): ParameterSections<DataSchemaArray>;
+}
+export declare class IncrementalParametersConverter extends BaseConverter {
+    readonly rawDocument: OpenAPIV3_1.Document;
+    readonly method: string;
+    readonly pathParameters: (OpenAPIV3_1.ParameterObject | OpenAPIV3_1.ReferenceObject)[] | undefined;
+    readonly operationParameters: (OpenAPIV3_1.ParameterObject | OpenAPIV3_1.ReferenceObject)[] | undefined;
+    readonly path: string[];
+    readonly safeParse: boolean;
+    private parameterSections;
+    private constructor();
+    private convert;
+    private addParameter;
+    static convert(rawDocument: OpenAPIV3_1.Document, method: string, pathParameters: (OpenAPIV3_1.ParameterObject | OpenAPIV3_1.ReferenceObject)[] | undefined, operationParameters: (OpenAPIV3_1.ParameterObject | OpenAPIV3_1.ReferenceObject)[] | undefined, path: string[], safeParse?: boolean): ParameterSections<IncrementalDataSchemaArray>;
 }

package/dist/openapi/ParametersConverter.js

@@ -1,7 +1,8 @@
 import { BaseConverter } from './BaseConverter.js';
+import { generateFirstIncrementalSchema } from './IncrementalEvaluator.js';
 import { SchemaConverter } from './SchemaConverter.js';
 import { InvalidSchemaError } from './errors.js';
-import { copyKeyIfDefined } from './utils.js';
+import { copyKeyIfDefined, dereference } from './utils.js';
 export class ParametersConverter extends BaseConverter {
     constructor(method, pathParameters, operationParameters, path, safeParse = false) {
         super(safeParse);
@@ -48,3 +49,62 @@ export class ParametersConverter extends BaseConverter {
         return new ParametersConverter(method, pathParameters, operationParameters, path, safeParse).convert();
     }
 }
+export class IncrementalParametersConverter extends BaseConverter {
+    constructor(rawDocument, method, pathParameters, operationParameters, path, safeParse = false) {
+        super(safeParse);
+        this.rawDocument = rawDocument;
+        this.method = method;
+        this.pathParameters = pathParameters;
+        this.operationParameters = operationParameters;
+        this.path = path;
+        this.safeParse = safeParse;
+        this.parameterSections = {
+            path: {},
+            query: {},
+            header: {},
+            cookie: {},
+        };
+    }
+    convert() {
+        var _a, _b;
+        (_a = this.pathParameters) === null || _a === void 0 ? void 0 : _a.forEach((parameterObject, i) => {
+            this.addParameter([...this.path, 'parameters', i.toString()], parameterObject);
+        });
+        (_b = this.operationParameters) === null || _b === void 0 ? void 0 : _b.forEach((parameterObject, i) => {
+            this.addParameter([...this.path, this.method, 'parameters', i.toString()], parameterObject);
+        });
+        return this.parameterSections;
+    }
+    addParameter(path, parameter) {
+        var _a, _b, _c;
+        if ('$ref' in parameter) {
+            const dereferencedParam = dereference('parameters', parameter.$ref, (_a = this.rawDocument.components) === null || _a === void 0 ? void 0 : _a.parameters);
+            if (!dereferencedParam || '$ref' in dereferencedParam) {
+                return;
+            }
+            parameter = dereferencedParam;
+        }
+        if (!['path', 'header', 'query', 'cookie'].includes(parameter.in)) {
+            this.handleNewError(InvalidSchemaError, path, `invalid parameter location: '${parameter.in}'`);
+            return;
+        }
+        const location = parameter.in;
+        // parameter.schema may be undefined (if the schema is instead defined in parameter.content), but this is likely super rare
+        let schema = parameter.schema;
+        if (schema && '$ref' in schema) {
+            schema = dereference('schemas', schema.$ref, (_b = this.rawDocument.components) === null || _b === void 0 ? void 0 : _b.schemas);
+        }
+        if (!schema) {
+            return;
+        }
+        // maintain immutability
+        const schemaCopy = Object.assign({}, schema);
+        copyKeyIfDefined('description', parameter, schemaCopy);
+        copyKeyIfDefined('deprecated', parameter, schemaCopy);
+        const incrementalSchema = generateFirstIncrementalSchema(schemaCopy, (_c = this.rawDocument.components) === null || _c === void 0 ? void 0 : _c.schemas, location === 'path' ? true : parameter.required);
+        this.parameterSections[location][parameter.name] = { schema: incrementalSchema };
+    }
+    static convert(rawDocument, method, pathParameters, operationParameters, path, safeParse) {
+        return new IncrementalParametersConverter(rawDocument, method, pathParameters, operationParameters, path, safeParse).convert();
+    }
+}

package/dist/openapi/SchemaConverter.d.ts

@@ -62,3 +62,17 @@ export declare class SchemaConverter extends BaseConverter {
         safeParse?: boolean;
     }): DataSchemaArray;
 }
+/**
+ * Given an OpenAPI 3.1 schema, this function will attempt to determine the schema type
+ * based on the properties present in the schema. This is useful for assigning types to
+ * schemas that are missing a type.
+ *
+ * For example, if a schema has no type but has `schema.properties`, we can infer the
+ * intended type is `object`.
+ *
+ * Used in the Conversion step.
+ *
+ * @param schema
+ * @returns if exactly one type can be inferred, the string corresponding to that type; otherwise `undefined`
+ */
+export declare const inferType: (schema: Omit<OpenAPIV3_1.SchemaObject, "type">) => OpenAPIV3_1.ArraySchemaObjectType | OpenAPIV3_1.NonArraySchemaObjectType | undefined;

package/dist/openapi/SchemaConverter.js

@@ -2,13 +2,7 @@ import lcm from 'lcm';
 import _ from 'lodash';
 import { BaseConverter } from './BaseConverter.js';
 import { ConversionError, ImpossibleSchemaError, InvalidSchemaError } from './errors.js';
-import { addKeyIfDefined, copyKeyIfDefined } from './utils.js';
-const structuredDataContentTypes = [
-    'multipart/form-data',
-    'application/json',
-    'application/x-www-form-urlencoded',
-];
-const stringFileFormats = ['binary', 'base64'];
+import { addKeyIfDefined, copyExampleIfDefined, copyKeyIfDefined, stringFileFormats, structuredDataContentTypes, } from './utils.js';
 export class SchemaConverter extends BaseConverter {
     constructor(schema, required, path = ['#'], location, contentType, safeParse = false) {
         super(safeParse);
@@ -484,13 +478,6 @@ export class SchemaConverter extends BaseConverter {
         return new SchemaConverter(schema, required, path, location, contentType, safeParse).convert();
     }
 }
-const copyExampleIfDefined = (source, destination) => {
-    var _a;
-    const example = ((_a = source.examples) === null || _a === void 0 ? void 0 : _a[0]) !== undefined ? source.examples[0] : source.example;
-    if (example !== undefined) {
-        destination.example = example;
-    }
-};
 const takeLast = (schema1, schema2, key) => {
     var _a;
     return (_a = schema2[key]) !== null && _a !== void 0 ? _a : schema1[key];
@@ -514,7 +501,7 @@ const combine = (schema1, schema2, key, transform) => {
  * @param schema
  * @returns if exactly one type can be inferred, the string corresponding to that type; otherwise `undefined`
  */
-const inferType = (schema) => {
+export const inferType = (schema) => {
     var _a, _b;
     let type = undefined;
     if (schema.format !== undefined ||

package/dist/openapi/stripComponents.d.ts

@@ -0,0 +1,3 @@
+import { OpenAPIV3_1 } from 'openapi-types';
+export declare function findRefsUsed(schema: unknown, components?: Record<string, unknown>): Set<string>;
+export declare function stripComponents(valueContainingRefs: unknown, rawDocument: OpenAPIV3_1.Document): Record<string, OpenAPIV3_1.SchemaObject>;

package/dist/openapi/stripComponents.js

@@ -0,0 +1,31 @@
+const schemaPrefix = '#/components/schemas/';
+export function findRefsUsed(schema, components = {}) {
+    const refsUsed = new Set();
+    function traverse(value) {
+        if (typeof value === 'object' && value !== null) {
+            if ('$ref' in value &&
+                typeof value.$ref === 'string' &&
+                value.$ref.startsWith(schemaPrefix)) {
+                const schemaName = value.$ref.slice(schemaPrefix.length);
+                if (!refsUsed.has(schemaName)) {
+                    refsUsed.add(schemaName);
+                    traverse(components[schemaName]);
+                }
+            }
+            for (const val of Object.values(value)) {
+                traverse(val);
+            }
+        }
+    }
+    traverse(schema);
+    return refsUsed;
+}
+export function stripComponents(valueContainingRefs, rawDocument) {
+    var _a;
+    const schemas = (_a = rawDocument.components) === null || _a === void 0 ? void 0 : _a.schemas;
+    if (schemas === undefined)
+        return {};
+    const refsUsed = findRefsUsed(valueContainingRefs, schemas);
+    const newEntries = Object.entries(schemas).filter(([schemaName]) => refsUsed.has(schemaName));
+    return Object.fromEntries(newEntries);
+}

package/dist/openapi/types/endpoint.d.ts

@@ -1,11 +1,12 @@
-export type Endpoint = {
+import { OpenAPIV3_1 } from 'openapi-types';
+export type Endpoint<D extends DataSchemaArray | IncrementalDataSchemaArray = DataSchemaArray | IncrementalDataSchemaArray> = {
     title?: string;
     description?: string;
     path: string;
     method: HttpMethod;
     servers?: Server[];
-    request: RequestSchema;
-    response: ResponseSchema;
+    request: RequestSchema<D>;
+    response: ResponseSchema<D>;
     deprecated: boolean;
 };
 export type Server = {
@@ -29,10 +30,10 @@ export type ServerVariableStringEnumSchema = {
 };
 export declare const httpMethods: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
 export type HttpMethod = (typeof httpMethods)[number];
-export type RequestSchema = {
+export type RequestSchema<D extends DataSchemaArray | IncrementalDataSchemaArray = DataSchemaArray | IncrementalDataSchemaArray> = {
     security: SecurityOption[];
-    parameters: ParameterSections;
-    body: BodySchema;
+    parameters: ParameterSections<D>;
+    body: BodySchema<D>;
     codeSamples?: CodeSample[];
 };
 export type CodeSample = {
@@ -40,11 +41,11 @@ export type CodeSample = {
     lang: string;
     source: string;
 };
-export type BodySchema = {
-    [contentType: string]: ContentSchema;
+export type BodySchema<D extends DataSchemaArray | IncrementalDataSchemaArray = DataSchemaArray | IncrementalDataSchemaArray> = {
+    [contentType: string]: ContentSchema<D>;
 };
-export type ContentSchema = {
-    schemaArray: DataSchemaArray;
+export type ContentSchema<D extends DataSchemaArray | IncrementalDataSchemaArray = DataSchemaArray | IncrementalDataSchemaArray> = {
+    schemaArray: D;
     examples: {
         [title: string]: ExampleSchema;
     };
@@ -54,15 +55,15 @@ export type ExampleSchema = {
     description?: string;
     value: unknown;
 };
-export type ParameterSchema = {
-    schema: DataSchemaArray;
+export type ParameterSchema<D extends DataSchemaArray | IncrementalDataSchemaArray = DataSchemaArray | IncrementalDataSchemaArray> = {
+    schema: D;
 };
-export type ParameterGroup = {
-    [name: string]: ParameterSchema;
+export type ParameterGroup<D extends DataSchemaArray | IncrementalDataSchemaArray = DataSchemaArray | IncrementalDataSchemaArray> = {
+    [name: string]: ParameterSchema<D>;
 };
 export type ParameterLocation = 'query' | 'header' | 'cookie' | 'path';
 type NonPathParameterLocation = Exclude<ParameterLocation, 'path'>;
-export type ParameterSections = Record<ParameterLocation, ParameterGroup>;
+export type ParameterSections<D extends DataSchemaArray | IncrementalDataSchemaArray = DataSchemaArray | IncrementalDataSchemaArray> = Record<ParameterLocation, ParameterGroup<D>>;
 export type SecurityOption = {
     title: string;
     parameters: SecurityParameterSections;
@@ -85,13 +86,11 @@ export type SecurityParameterGroup = {
     [name: string]: SecurityParameterSchema;
 };
 export type SecurityParameterSections = Record<NonPathParameterLocation, SecurityParameterGroup>;
-export type ResponseSchema = {
-    [code: string]: BodySchema;
+export type ResponseSchema<D extends DataSchemaArray | IncrementalDataSchemaArray = DataSchemaArray | IncrementalDataSchemaArray> = {
+    [code: string]: BodySchema<D>;
 };
-export type DataSchemaArray = [DataSchema, ...DataSchema[]];
 export declare const typeList: readonly ["boolean", "string", "number", "integer", "object", "array", "enum<string>", "enum<number>", "enum<integer>", "file", "null", "any"];
 export type SchemaType = (typeof typeList)[number];
-export type DataSchema = BooleanSchema | StringSchema | NumberSchema | ObjectSchema | ArraySchema | StringEnumSchema | NumberEnumSchema | FileSchema | NullSchema | AnySchema;
 export type BaseSchema<T> = {
     type: SchemaType;
     title?: string;
@@ -121,18 +120,19 @@ export type NumberSchema = {
     minimum?: number;
     exclusiveMinimum?: boolean;
 } & BaseSchema<number>;
-export type ObjectSchema = {
+type BaseObjectSchema<R> = {
     type: 'object';
-    additionalProperties?: boolean | DataSchemaArray;
+    additionalProperties?: boolean | R;
     maxProperties?: number;
     minProperties?: number;
     properties: {
-        [key: string]: DataSchemaArray;
+        [key: string]: R;
     };
+    requiredProperties?: string[];
 } & BaseSchema<Record<string, unknown>>;
-export type ArraySchema = {
+type BaseArraySchema<R> = {
     type: 'array';
-    items: DataSchemaArray;
+    items: R;
     maxItems?: number;
     minItems?: number;
     uniqueItems?: boolean;
@@ -156,4 +156,12 @@ export type NullSchema = {
 export type AnySchema = {
     type: 'any';
 } & BaseSchema<unknown>;
+export type ObjectSchema = BaseObjectSchema<DataSchemaArray>;
+export type ArraySchema = BaseArraySchema<DataSchemaArray>;
+export type DataSchema = BooleanSchema | StringSchema | NumberSchema | ObjectSchema | ArraySchema | StringEnumSchema | NumberEnumSchema | FileSchema | NullSchema | AnySchema;
+export type DataSchemaArray = [DataSchema, ...DataSchema[]];
+export type IncrementalObjectSchema = BaseObjectSchema<OpenAPIV3_1.SchemaObject>;
+export type IncrementalArraySchema = BaseArraySchema<OpenAPIV3_1.SchemaObject>;
+export type IncrementalDataSchema = BooleanSchema | StringSchema | NumberSchema | IncrementalObjectSchema | IncrementalArraySchema | StringEnumSchema | NumberEnumSchema | FileSchema | NullSchema | AnySchema;
+export type IncrementalDataSchemaArray = [IncrementalDataSchema, ...IncrementalDataSchema[]];
 export {};

package/dist/openapi/types/endpoint.js

@@ -9,6 +9,7 @@ export const httpMethods = [
     'patch',
     'trace',
 ];
+// Schema types
 export const typeList = [
     'boolean',
     'string',

package/dist/openapi/utils.d.ts

@@ -1,2 +1,10 @@
+import { OpenAPIV3_1 } from 'openapi-types';
+import { DataSchema } from './types/endpoint.js';
+export declare const stringFileFormats: string[];
+export declare const structuredDataContentTypes: string[];
+type ComponentsSection = keyof OpenAPIV3_1.ComponentsObject;
+export declare function dereference<S extends ComponentsSection>(section: S, $ref: string, components: Record<string, NonNullable<OpenAPIV3_1.ComponentsObject[S]>[string]> | undefined, maxDepth?: number): NonNullable<OpenAPIV3_1.ComponentsObject[S]>[string] | undefined;
 export declare const addKeyIfDefined: <D, K extends keyof D>(key: K, value: D[K] | undefined, destination: D) => void;
 export declare const copyKeyIfDefined: <D, K extends keyof D>(key: K, source: Pick<D, K>, destination: D) => void;
+export declare const copyExampleIfDefined: (source: Pick<OpenAPIV3_1.SchemaObject, "example" | "examples">, destination: Pick<DataSchema, "example">) => void;
+export {};

package/dist/openapi/utils.js

@@ -1,3 +1,26 @@
+export const stringFileFormats = ['binary', 'base64'];
+export const structuredDataContentTypes = [
+    'multipart/form-data',
+    'application/json',
+    'application/x-www-form-urlencoded',
+];
+// the number of times a $ref can point to another $ref before we give up
+const MAX_DEREFERENCE_DEPTH = 5;
+export function dereference(section, $ref, components, maxDepth = MAX_DEREFERENCE_DEPTH) {
+    const sectionPrefix = `#/components/${section}/`;
+    if (!$ref.startsWith(sectionPrefix))
+        return undefined;
+    const key = $ref.slice(sectionPrefix.length);
+    const value = components === null || components === void 0 ? void 0 : components[key];
+    // if a $ref points to another $ref, keep resolving until we hit our max depth
+    if (value && '$ref' in value) {
+        if (maxDepth > 0 && typeof value.$ref === 'string') {
+            return dereference(section, value.$ref, components, maxDepth - 1);
+        }
+        return undefined;
+    }
+    return value;
+}
 export const addKeyIfDefined = (key, value, destination) => {
     if (value !== undefined) {
         destination[key] = value;
@@ -10,3 +33,10 @@ export const copyKeyIfDefined = (key, source, destination) => {
         destination[key] = source[key];
     }
 };
+export const copyExampleIfDefined = (source, destination) => {
+    var _a;
+    const example = ((_a = source.examples) === null || _a === void 0 ? void 0 : _a[0]) !== undefined ? source.examples[0] : source.example;
+    if (example !== undefined) {
+        destination.example = example;
+    }
+};