Merge branch 'main' of github.com:openapi-contrib/json-schema-to-openapi-schema

Author: jonluca

README.md

@@ -86,6 +86,74 @@ Options:
     -d, --dereference       If set all local and remote references (http/https and file) $refs will be dereferenced
 ```
 
+## Synchronous API
+
+For synchronous conversion without async operations, use `convertSync`:
+
+```ts
+import { convertSync } from '@openapi-contrib/json-schema-to-openapi-schema';
+
+const schema = {
+	$schema: 'http://json-schema.org/draft-04/schema#',
+	type: ['string', 'null'],
+	format: 'date-time',
+};
+
+const convertedSchema = convertSync(schema);
+console.log(convertedSchema);
+```
+
+This will output the same result as the async version:
+
+```js
+{
+  type: 'string',
+  format: 'date-time',
+  nullable: true
+}
+```
+
+### Options for convertSync
+
+`convertSync` supports a subset of the options available to `convert`:
+
+#### `cloneSchema` (boolean)
+
+If set to `false`, converts the provided schema in place. If `true`, clones the schema by converting it to JSON and back. The overhead of the cloning is usually negligible. Defaults to `true`.
+
+#### `convertUnreferencedDefinitions` (boolean)
+
+Defaults to `true`.
+
+If a schema has a `definitions` property (valid in JSON Schema), and only some entries are referenced, we'll still try to convert the remaining definitions to OpenAPI. If you do not want this behavior, set this to `false`.
+
+### ⚠️ Limitations
+
+`convertSync` does **not** support dereferencing external references (`$ref` to HTTP/HTTPS URLs or external files). If your schema contains external references, use the async `convert` function with the `dereference: true` option instead.
+
+#### Example:
+
+```ts
+// Schema with external reference
+const schema = {
+	type: 'object',
+	properties: {
+		user: {
+			$ref: 'https://example.com/schemas/user.json',
+		},
+	},
+};
+
+// convertSync leaves the reference unresolved
+const result = convertSync(schema);
+// Result: { type: 'object', properties: { user: { $ref: 'https://example.com/schemas/user.json' } } }
+
+// Use async convert for proper resolution:
+const resolved = await convert(schema, { dereference: true });
+```
+
+**Note:** External references will remain as `$ref` pointers in the output schema. They will not be expanded or validated.
+
 ## Why?
 
 OpenAPI is often described as an extension of JSON Schema, but both specs have changed over time and grown independently. OpenAPI v2 was based on JSON Schema draft v4 with a long list of deviations, but OpenAPI v3 shrank that list, upping their support to draft v4 and making the list of discrepancies shorter. This has been solved for OpenAPI v3.1, but for those using OpenAPI v3.0, you can use this tool to solve [the divergence](https://apisyouwonthate.com/blog/openapi-and-json-schema-divergence).

src/index.ts

@@ -3,10 +3,10 @@ import type {
 	JSONSchema6Definition,
 	JSONSchema7Definition,
 } from 'json-schema';
-import type { Options, SchemaType, SchemaTypeKeys } from './types';
+import type { Options, OptionsSync, SchemaType, SchemaTypeKeys } from './types';
 import { Walker } from 'json-schema-walker';
 import { allowedKeywords } from './const';
-import type { OpenAPIV3 } from 'openapi-types';
+import { type OpenAPIV3 } from 'openapi-types';
 import type { JSONSchema } from '@apidevtools/json-schema-ref-parser';
 
 class InvalidTypeError extends Error {
@@ -70,6 +70,51 @@ const handleDefinition = async <T extends JSONSchema4 = JSONSchema4>(
 	return def;
 };
 
+const handleDefinitionSync = <T extends JSONSchema4 = JSONSchema4>(
+	def: JSONSchema7Definition | JSONSchema6Definition | JSONSchema4,
+	schema: T,
+) => {
+	if (typeof def !== 'object') {
+		return def;
+	}
+
+	const type = def.type;
+	if (type) {
+		// Walk just the definitions types
+		const walker = new Walker<T>();
+		walker.loadSchemaSync(
+			{
+				definitions: schema['definitions'] || [],
+				...def,
+				$schema: schema['$schema'],
+			} as any,
+			{
+				cloneSchema: true,
+			},
+		);
+		walker.walkSync(convertSchema, walker.vocabularies.DRAFT_07);
+		if ('definitions' in walker.rootSchema) {
+			delete (<any>walker.rootSchema).definitions;
+		}
+		return walker.rootSchema;
+	}
+	if (Array.isArray(def)) {
+		// if it's an array, we might want to reconstruct the type;
+		const typeArr = def;
+		const hasNull = typeArr.includes('null');
+		if (hasNull) {
+			const actualTypes = typeArr.filter((l) => l !== 'null');
+			return {
+				type: actualTypes.length === 1 ? actualTypes[0] : actualTypes,
+				nullable: true,
+				// this is incorrect but thats ok, we are in the inbetween phase here
+			} as JSONSchema7Definition | JSONSchema6Definition | JSONSchema4;
+		}
+	}
+
+	return def;
+};
+
 export const convert = async <T extends object = JSONSchema4>(
 	schema: T,
 	options?: Options,
@@ -89,6 +134,25 @@ export const convert = async <T extends object = JSONSchema4>(
 	return rootSchema as OpenAPIV3.Document;
 };
 
+export const convertSync = <T extends object = JSONSchema4>(
+	schema: T,
+	options?: OptionsSync,
+): OpenAPIV3.Document => {
+	const walker = new Walker<T>();
+	const convertDefs = options?.convertUnreferencedDefinitions ?? true;
+	walker.loadSchemaSync(schema, options);
+	walker.walkSync(convertSchema, walker.vocabularies.DRAFT_07);
+	// if we want to convert unreferenced definitions, we need to do it iteratively here
+	const rootSchema = walker.rootSchema as unknown as JSONSchema;
+	if (convertDefs && rootSchema?.definitions) {
+		for (const defName in rootSchema.definitions) {
+			const def = rootSchema.definitions[defName];
+			rootSchema.definitions[defName] = handleDefinitionSync(def, schema);
+		}
+	}
+	return rootSchema as OpenAPIV3.Document;
+};
+
 function stripIllegalKeywords(schema: SchemaType) {
 	if (typeof schema !== 'object') {
 		return schema;

src/types.ts

@@ -11,6 +11,12 @@ export interface Options {
 	convertUnreferencedDefinitions?: boolean;
 	dereferenceOptions?: ParserOptions | undefined;
 }
+
+export interface OptionsSync {
+	cloneSchema?: boolean;
+	convertUnreferencedDefinitions?: boolean;
+}
+
 type ExtendedJSONSchema = addPrefixToObject & JSONSchema;
 export type SchemaType = ExtendedJSONSchema & {
 	example?: JSONSchema['examples'][number];