Example of using json-ref-resolver within docusaurus-json-schema-plugin

[Paul-Hanlon-Renaissance-Learning]

Hi, love the plugin thank you loads for it.

Was wondering if you'd have an example for how to dereference.

I have a schema that has two properties that ref from two other schemas.
These are located in a folder located at: (project root)/static/schemas/

I have a .mdx that refs the base schema

import CodeBlock from '@theme/CodeBlock';
import Schema from "/static/schemas/base.schema.json";
import JSONSchemaViewer from "@theme/JSONSchemaViewer";

export const resolverOptions = {
    baseUri: 'static/schemas/'
  };

# assessment-v1.1.schema 
<JSONSchemaViewer schema={Schema} resolverOptions={resolverOptions} />

Am I right in thinking that this type is correct?

is it the uri that's incorrect or am I miles off?
Any more info required please do let me know.

Thanks

[jy95]

Hello @PaulHanlon,

In the documentation, I have an example with a local dereference but you are right : a dereference with local file resolution might help how to use it to fit your case.

Yes, this type is correct.
By default, json-ref-resolver resolve only local references within the same file but you can extend it to fit your needs using resolvers option like (json-ref-resolver explained that you can add your own $ref resolution like file:// , custom:// ).

One example could be :

import CodeBlock from '@theme/CodeBlock';
import Schema from "@site/static/schemas/base.schema.json";
import JSONSchemaViewer from "@theme/JSONSchemaViewer";
import useBaseUrl from '@docusaurus/useBaseUrl';

const resolverOptions = {
    resolvers: {
        file: { 
           // Inspired by @stoplight/json-ref-readers
            resolve: (ref: string) => {
                return new Promise((resolve, reject) => {
                     // TODO
                }
            }
        }
    }
  };

# assessment-v1.1.schema 
<JSONSchemaViewer schema={Schema} resolverOptions={resolverOptions} />


# source : 
<CodeBlock language="json">{JSON.stringify(Schema, null, 2)}</CodeBlock>

And the related schema could be :

{
  "type": "object",
  "properties": {
    "prop1": { "$ref": "file://prop1-schema.json" },
    "prop2": { "$ref": "file://prop2-schema.json" }
  }
}

Or

{
  "type": "object",
  "properties": {
    "prop1": { "$ref": "../models/user.json" },
    "prop2": { "$ref": "./rank.json" }
  }
}

[jy95]

@PaulHanlon I updated https://jy95.github.io/docusaurus-json-schema-plugin/docs/category/-references with valid examples of local / remote $ref.

While it isn't a bulletproof solution to meet everyone needs ($ref handling can be quite complex), it should help to achieve 80% of what people want. If you or somebody else have ideas on how to improve it, be my guest ;)