​RefParser

Jedison includes a RefParser class, which processes a JSON Schema and builds an internal list of dereferenced $ref pointers.
You can pass the RefParser instance to a Jedison instance, which will then use it to handle schema dereferencing internally.
The original schema remains unchanged—schemas are dereferenced at runtime only when needed.
This approach makes it easier to support and manage recursive schemas.

const schema = {
  "type": "object",
  "properties": {
    "user": {
      "$ref": "#/$defs/user"
    }
  },
  "$defs": {
    "user": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  }
}

const refParser = new Jedison.RefParser()

const init = async () => {
  await refParser.dereference(schema)

  const jedison = new Jedison.Create({
    container: document.querySelector('#jedison-container'),
    theme: new Jedison.ThemeBootstrap5(),
    refParser: refParser,
    schema: schema
  })
}

init()

​Before Dereferencing

The "user" property schema has not been dereferenced, so the editor only sees an empty schema.
Since there's no defined type, the schema is interpreted as allowing any JSON type.
As a result, Jedison displays a multiple editor, enabling the user to select from all possible JSON types.

​After Dereferencing

The "user" property schema has been dereferenced and has now type.
As a result, Jedison renders a object editor.

​Recursive schema

A schema that references itself (directly, or through a chain of $refs) would otherwise make RefParser expand it infinitely. RefParser detects these cycles and marks the recursive schema so Jedison can render it safely instead of looping forever.

Jedison can handle recursive JSON Schemas, provided certain conditions are met.
In this example, we use the x-deactivateNonRequired keyword, which requires properties to be added manually.
To support this, the Jedison option enablePropertiesToggle: true allows manual activation of properties.
This setup is necessary to prevent infinite recursion during schema processing.

In some cases, handling recursion is easier—for example, when the recursive $ref is inside an "items" schema.
This is because the schema is only instantiated at runtime when a new item is added to the array.

​External refs & custom fetch

A $ref value starting with http or https is treated as an external reference: RefParser loads it over the network instead of resolving it against the schema's own $defs. By default this uses the global fetch, but the RefParser constructor accepts two options to override that:

  • fetchOptions — passed as the second argument to fetch, e.g. to forward an Authorization header or credentials so an authenticated endpoint can be reached
  • fetch — a full replacement for the fetch function itself, useful server-side to resolve refs entirely in-process (no network round-trip, and no need to carry the caller's session/cookie through an HTTP request to your own API)

Whichever fetch is used, it must resolve to an object with an ok boolean and a json() method, matching the Fetch API's Response shape.

// Forward auth headers/cookies to a real network request
const refParser = new Jedison.RefParser({
  fetchOptions: {
    headers: { Authorization: `Bearer ${token}` },
    credentials: 'include'
  }
})

// Or resolve refs entirely in-process, without a network round-trip at all
const refParser = new Jedison.RefParser({
  fetch: async (url) => {
    const schema = await resolveRefInProcess(url) // however your server builds the fragment
    return { ok: true, json: async () => schema }
  }
})

await refParser.dereference(schema)