{"id":22127245,"url":"https://github.com/devflowinc/openapi-schema-ref-parser","last_synced_at":"2025-10-12T09:30:45.913Z","repository":{"id":265799306,"uuid":"896623800","full_name":"devflowinc/openapi-schema-ref-parser","owner":"devflowinc","description":"Parse, Resolve, and Dereference OpenAPI Schema $ref pointers for LLM's","archived":false,"fork":false,"pushed_at":"2024-12-02T08:04:24.000Z","size":55,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-30T03:33:25.787Z","etag":null,"topics":["javascript","json-pointer","json-schema","nodejs","parser","resolver","universal-javascript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/openapi-schema-ref-parser","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devflowinc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-30T21:25:35.000Z","updated_at":"2025-03-15T04:01:51.000Z","dependencies_parsed_at":"2024-12-03T09:15:18.938Z","dependency_job_id":null,"html_url":"https://github.com/devflowinc/openapi-schema-ref-parser","commit_stats":null,"previous_names":["devflowinc/openapi-schema-ref-parser"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/devflowinc/openapi-schema-ref-parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devflowinc%2Fopenapi-schema-ref-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devflowinc%2Fopenapi-schema-ref-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devflowinc%2Fopenapi-schema-ref-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devflowinc%2Fopenapi-schema-ref-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devflowinc","download_url":"https://codeload.github.com/devflowinc/openapi-schema-ref-parser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devflowinc%2Fopenapi-schema-ref-parser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010938,"owners_count":26084837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","json-pointer","json-schema","nodejs","parser","resolver","universal-javascript"],"created_at":"2024-12-01T17:17:32.525Z","updated_at":"2025-10-12T09:30:45.650Z","avatar_url":"https://github.com/devflowinc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAPI Schema Reference Parser\n\nRecursively parse OpenAPI specifications such that all `\"$ref\": \"#/foo\"` entries are replaced with what the reference in the spec resolves to.\n\nOur goal is to make it easier to load an OpenAPI schema into a search index or tool calling repository for RAG-style LLM usecases. This is a very simple package which wraps [@json-schema-tools/reference-resolver](https://github.com/json-schema-tools/reference-resolver). You may want to consider copying the `index.ts` function intead of installing this entire package.\n\nPhil Sturgeon published [Only You Can Bring Modern OpenAPI Bundling to JavaScript](https://philsturgeon.com/bundling-openapi-with-javascript/) in October of 2022, and this is us tip-toe'ing into doing that. We tried using the canonical [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser?ref=philsturgeon.com), but it's `continueOnError` feature is deeply broken and was not simple to fix.\n\n## Install\n\n`npm install openapi-schema-ref-parser`\n\n## Usage Example\n\n```js\nimport expandRefs from \"openapi-schema-ref-parser\";\n\nasync function expandOpenapiSpec() {\n  const specResponse = await fetch(\n    \"https://api.trieve.ai/api-docs/openapi.json\"\n  );\n  const specText = await specResponse.text();\n  const openapiSpec = JSON.parse(specText);\n\n  // Expand all $ref pointers within the OpenAPI document\n  const expandedSpec = await expandRefs(openapiSpec);\n\n  // Process each route in the specification\n  for (const path in expandedSpec.paths) {\n    for (const method in expandedSpec.paths[path]) {\n      const methodPath = `${method.toUpperCase()} ${path}`;\n      const route = { [methodPath]: expandedSpec.paths[path][method] };\n\n      // Instead of logging, you might want to:\n      // - Add to a search/RAG system like trieve.ai\n      // - Update a tool repository\n      console.log(JSON.stringify(route, null, 2));\n    }\n  }\n}\n\nexpandOpenapiSpec();\n```\n\n## Context\n\nOpenAPI specs have gotten more valuable in the past couple years of LLMs being around since LLMs are able to intelligently do things once they know about every route available in a given API. However, they can be hard to process into a search index or tool calling repository because they leverage a `$ref` system.\n\nOpenAPI specifications tend to re-use types across many `path`'s and `method`'s. To simplify their defitions, the final `JSON` or `YAML` files contain several field values like `{\"schema\": { \"$ref\": \"#/components/schemas/ErrorResponseBody\" }}` where the actual value lies at `openapiSpec.components.schemas.ErrorResponseBody`.\n\n- [x] parses all $ref values to their specifications\n- [x] handles circular dependencies\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevflowinc%2Fopenapi-schema-ref-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevflowinc%2Fopenapi-schema-ref-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevflowinc%2Fopenapi-schema-ref-parser/lists"}