{"id":48274,"library":"json-schema-for-openapi","title":"JSON Schema to OpenAPI v3.0.x Converter","description":"Converts standard JSON Schema (draft-07, 2019-09, 2020-12) to an OpenAPI v3.0.x compatible Schema Object. Current stable version is 0.5.0, released irregularly with breaking changes (v0.3.0 removed built-in $ref handling). Key differentiators: focused solely on v3.0.x compatibility (not v3.1.x), handles specific JSON Schema features unsupported by v3.0.x — converting items from array to object, multiple types to oneOf, const to enum, null type to nullable, and default values to proper OpenAPI types. Does NOT dereference $ref; users must pre-process with a separate dereferencing library. Lightweight with no runtime dependencies.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/JaredCE/json-schema-to-openAPI-schema-object","tags":["javascript","json","json-schema","openAPI","openAPI-v3"],"install":[{"cmd":"npm install json-schema-for-openapi","lang":"bash","label":"npm"},{"cmd":"yarn add json-schema-for-openapi","lang":"bash","label":"yarn"},{"cmd":"pnpm add json-schema-for-openapi","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to dereference $ref before conversion (since v0.3.0 removed internal resolving)","package":"@apidevtools/json-schema-ref-parser","optional":true}],"imports":[{"note":"Default export is deprecated; use named export convertOpenApi.","symbol":"convertOpenApi","correct":"import { convertOpenApi } from 'json-schema-for-openapi'"},{"note":"Library is ESM-only. CommonJS require may work in some bundlers but is not guaranteed.","wrong":"const { convertSchemaObj } = require('json-schema-for-openapi')","symbol":"convertSchemaObj","correct":"import { convertSchemaObj } from 'json-schema-for-openapi'"},{"note":"Returns a Promise; must be awaited.","symbol":"convertSchemaObj","correct":"import { convertSchemaObj } from 'json-schema-for-openapi'"}],"quickstart":{"code":"import { convertOpenApi } from 'json-schema-for-openapi';\n\nconst jsonSchema = {\n  type: 'object',\n  properties: {\n    id: { type: 'string' },\n    price: { type: ['number', 'null'] },\n    tags: { type: 'array', items: [{ type: 'string' }] },\n    status: { type: 'string', const: 'active' }\n  }\n};\n\nasync function convert() {\n  const openApiSchema = await convertOpenApi(jsonSchema);\n  console.log(JSON.stringify(openApiSchema, null, 2));\n}\n\nconvert();","lang":"typescript","description":"Converts a JSON Schema with multiple unsupported patterns (array items, null type, const) to OpenAPI v3.0.x compatible schema object."},"warnings":[{"fix":"Pre-process your schema with @apidevtools/json-schema-ref-parser: const dereferenced = await $RefParser.dereference(schema);","message":"As of v0.3.0, built-in $ref resolution was removed. You must dereference your schema before passing to the converter.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Use import { convertSchemaObj } instead of import convertOpenApi.","message":"Default export (convertOpenApi) is deprecated in favor of named export convertSchemaObj.","severity":"deprecated","affected_versions":">=0.4.0"},{"fix":"Ensure array items are either a single schema object or only one schema in the array. Manually merge if needed.","message":"When converting array items from an array to object, only the first item is used. Multiple item schemas are discarded.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use a dereferencing library to flatten schemas before conversion, and check for circular refs.","message":"The library does not handle recursive $ref or circular references. Conversion may throw or produce invalid output.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'-07':12 '-09':14 '-12':16 '0.5.0':28 '2019':13 '2020':15 'array':61 'break':32 'built':37 'built-in':36 'chang':33 'compat':21,47 'const':68 'convert':6,7,58 'current':24 'default':76 'depend':100 'derefer':84 'dereferenc':94 'differenti':42 'draft':11 'enum':70 'featur':54 'focus':43 'handl':40,50 'irregular':30 'item':59 'javascript':101 'json':1,9,52,102,104 'json-schema':103 'key':41 'librari':95 'lightweight':96 'multipl':64 'must':87 'null':71 'nullabl':74 'object':23,63 'oneof':67 'openapi':4,19,80,106,108 'openapi-v3':107 'pre':89 'pre-process':88 'process':90 'proper':79 'ref':39,85 'releas':29 'remov':35 'runtim':99 'schema':2,10,22,53,105 'separ':93 'sole':44 'specif':51 'stabl':25 'standard':8 'type':65,72,81 'unsupport':55 'user':86 'v0.3.0':34 'v3':109 'v3.0.x':5,20,46,57 'v3.1.x':49 'valu':77 'version':26","created_at":"2026-06-07T16:55:47.464648+00:00","updated_at":"2026-06-07T16:55:47.464648+00:00","problems":[{"fix":"Dereference the schema first: const deref = await $RefParser.dereference(schema); then call convertSchemaObj(deref);","cause":"Passing an undereferenced schema that still contains unresolved $ref nodes.","error":"TypeError: Cannot read properties of undefined (reading 'properties')"},{"fix":"Change to: import { convertSchemaObj } from 'json-schema-for-openapi';","cause":"Using the deprecated default export import instead of named import.","error":"TypeError: convertSchemaObj is not a function"},{"fix":"Ensure input is standard JSON Schema; if necessary, manually convert items array to a single object before calling the library.","cause":"The library expects 'items' to be an object, but JSON Schema allows an array (for tuple validation). It converts but logs a warning; if the error occurs, the schema might have been pre-processed incorrectly.","error":"Error: 'items' must be an object, not an array"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/JaredCE/json-schema-to-openAPI-schema-object#readme","github":"https://github.com/JaredCE/json-schema-to-openAPI-schema-object","docs":null,"changelog":null,"pypi":null,"npm":"json-schema-for-openapi","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}