# APIDevTools/json-schema-ref-parser

Parse, Resolve, and Dereference JSON Schema $ref pointers in Node and browsers

Repository: https://github.com/APIDevTools/json-schema-ref-parser
Canonical: https://ross.abutalabs.com/products/json-schema-ref-parser
Homepage: http://apidevtools.com/json-schema-ref-parser/
Language: TypeScript
License: MIT
License Family: permissive
Topics: javascript, nodejs, json-schema, json-reference, json-pointer, resolver, parser, universal-javascript, openapi
Last push: 2026-08-26T05:19:41+00:00

## Health v2 (maintenance only)
Score: 99/100 (v2, computed 2026-09-03T02:20:16.233290+00:00)
- activity 99, release rhythm 99, longevity 100
- inputs: {"age_days": 4069, "days_push": 7, "days_rel": 7, "gap_med": 7, "n_releases_24m": 46}
- flags: none
- formula: round(0.45*activity + 0.35*rhythm + 0.20*longevity); archived -> min(score, 10)

## Adoption (not part of the score)
Stars 1113, forks 251 (observed 2026-08-28T04:03:38.059229+00:00)

## What it is
A JavaScript/TypeScript library that parses, resolves, and dereferences JSON Schema $ref pointers, supporting external files, URLs, JSON/YAML, circular references, and custom resolvers. It can bundle multi-file schemas into a single self-contained schema or produce plain JavaScript object trees.

## Use cases
- resolve $ref pointers in a JSON Schema across local files and URLs
- bundle a multi-file OpenAPI spec into a single file
- dereference a JSON Schema into a plain JavaScript object
- load schemas written in a mix of JSON and YAML
- handle circular references in JSON Schemas
- add a custom resolver to load $refs from a database
- validate or preprocess OpenAPI definitions before code generation

## When to choose
- you work with JSON Schema or OpenAPI specs that use $ref pointers to external files or URLs
- you need to bundle or flatten multi-file schemas into one portable document
- your schemas mix JSON and YAML or contain circular references
- you need the same library to run in both Node.js and browsers

## When to avoid
- you need full JSON Schema validation rather than reference resolution
- you work with non-JSON/YAML schema formats or non-JSON Reference linking conventions
- you need a language other than JavaScript/TypeScript

## Facets
- artifact type: library
- maturity: stable
- function: parser, developer-tools, yaml
- domain: developer-tools, apis, web-development, parsers
- platform: browser, cross-platform
- tags: -schema, -pointer, -reference, openapi, dereference, bundle, schema-resolution, typescript, nodejs, javascript

## Member repositories
- APIDevTools/json-schema-ref-parser (main) score 99

## Provenance
- Observed fields: from GitHub, fetched 2026-08-28T04:03:38.059229+00:00.
- Health v2: computed from the inputs above; adoption is never an input.
- Inferred fields (summary, facets, guidance): AI-extracted, prompt v1, taxonomy v1, on 2026-08-30T06:42:33.244106+00:00, confidence not recorded.
  - readme: https://github.com/APIDevTools/json-schema-ref-parser (fetched 2026-08-28T04:03:38.059229+00:00, sha af071a94160d)
  - homepage: http://apidevtools.com/json-schema-ref-parser/ (fetched 2026-08-29T12:46:18.531688+00:00, sha a0a90b696190)
  - site_page: https://apidevtools.com/json-schema-ref-parser/docs/plugins/resolvers.html (fetched 2026-08-29T12:46:18.541053+00:00, sha b24b106ec72e)
  - site_page: https://apidevtools.com/json-schema-ref-parser/docs/ref-parser.html (fetched 2026-08-29T12:46:18.543100+00:00, sha 6f5a4f67d507)
  - site_page: https://apidevtools.com/json-schema-ref-parser/docs (fetched 2026-08-29T12:46:18.544922+00:00, sha e1154522f903)
  - registry_npm: https://registry.npmjs.org/json-schema-ref-parser (fetched 2026-08-29T12:46:18.546639+00:00, sha 8044e07c36c6)
- Data as of 2026-08-30T08:39:29.467469+00:00.