Splitting a schema across multiple sections of a documentation site

[gnidan]

I'm looking to author a Docusaurus site for a collection of several complex JSON Schemas. These schemas are recursive, but also just too big to explain properly in a single collapsible <JSONSchemaViewer />. I want to be able to document my schema in parts, with distinct pages or sections that contain individual <JSONSchemaViewer />s for individual definitions.

This plugin already allows specifying a JSON Pointer (which is essential!), but I'd also like to be specify known permalinks for subschemas when creating each <JSONSchemaViewer />. I'm imagining something like this:

Example interface to tell JSONSchemaViewer about known permalinks

<JSONSchemaViewer
  {...otherOptions}
  knownRefs: {
    "#/$defs/ComplexStandaloneSubschemaWithSeparateDocumentation": "/spec/concepts/#documentation-for-complex-standalone-subschema"
  }
  />

In this example, I'm imagining this plugin to keep track of "$ref"s and render a component that hyperlinks to the corresponding page instead of recursively rendering the schema.¹

Incidentally, this seems to be a viable way to workaround the lack of support for recursive $refs. I've confirmed this already in my initial hacking, but I'm doing it with a wrapper around JSONSchemaViewer that preprocesses my schema object by finding/rewriting all { $ref: ..., ...others } objects². I don't like this approach because there's no way to customize the component rendering for a particular subschema other than specifying a component for all description fields... I want hyperlinked schemas to appear visually obvious, and I believe there's no way to hyperlink at all via preprocessing except via the use of a description field with a custom <ReactMarkdown /> component

Since this behavior would dramatically improve the readability of my specification docs, over the next few days I plan to try implementing a proof of concept of this approach in my forked repo. I'd love to get insight from the maintainers here if this sort of use case is worth targeting, and if there's a particular interface or implementation strategy that they'd be most willing to accept. I really want this behavior, and I really don't want to have a lingering fork with this sort of behavior bolted on.

Any advice would be much appreciated 🙏 (and thank you for reading this!)

Footnotes

1. For now, I'm ignoring the concern about equivalent IDs (like schema:my-schema#/$defs/... vs. unprefixed #), but I imagine this to be solvable or ignorable. ↩

2. My hacky preprocessing strategy now is that I remove $ref fields and instead borrow fields from the referenced schema directly. For the hyperlink, I override with a custom description that includes the link. ↩

[jy95]

Hello @gnidan ,

For the being time, recursive schemas are not on the roadmap yet because I didn't find a clear way to make that obvious to the end-users. So I am curious about your approch (with examples with pictures as I find it helps understanding) ...

Here is one possible idea I have :

Thanks to the parsing library used here, unresolved $ref like in the case of recursive schema will be present as it in the schema object like in CreateNodes . I think a new component UnresolvedRef could have its place. Of course, it could be customized as well the ValueComponent we are discussing in #224 so users can do whatever they want with it. (In my mind, permalinks could be anything - not only parts on the same page or website if you see my point)

Draft specs about this UnresolvedRef could be :

Input 1 : The current JSON Schema at that level 
        (Instead of a standalone "$ref" / "$recursiveRef" / .. input, users will be able to understand the context, 
        not to mention debugging)
Input 2 : The current JSON pointer at that level 
        (I had a proposal to add json pointer  https://github.com/jy95/docusaurus-json-schema-plugin/discussions/120 
        but never got feedbacks on the idea ... )
Output : JSX.Element

Let's focus on Input 1 & Output : Input 2 could come later.
(For the default implementation if the custom UnresolvedRef isn't here, it could be some kind of placeholder like Unresolved $ref : xxx )

What do you think ?

[jy95]

@gnidan Like good things, it will have an end soon ^^

For schema composition and schema conditionals, we could add the context provider around the calls for the being time. You don't have to put the ids in the html yet : we need some thinking.

About that another component (or rework of SchemaItem), what would be your idea ? My thoughts :

• I need the distinction between <CreateEdge /> and <CreateNodes /> (e.g. to know when I need the Collapsible and the friendly name generator, ...)
• From a user perspective, short paths would be easier understood and testable : /properties/config instead of /properties/config/allOf/0 , not to mention if they planned some kind of migration to refactor their schema as well
• CreateNodes could put the id in the React frament (instead of the <> empty element) but obviously it needs to have the context provider in the various schema conditionals and compositions cases. It will just not be collapsible
• I am open to discuss about schema composition and schema conditionals rendering refactoring, just first things first. The good point is that as code is specialised, we can tweak and test proposals (for example, having a Collapsible component for both so that we could put id somewhere)

[gnidan]

Hm, so I want to keep thinking about this a bit more, but I think that maybe there's some way to separate a component for the full <Collapsible /> schema container and have something like <SchemaItem /> be the primary component for rendering a subschema, with HTML DOM ID and <CreateNodes /> both.

On first glance, I was thinking that some of the behavior from <SchemaItem /> could be moved to a <SchemaContainer /> component that takes children, but it does look a bit messy.

Anyway, just to respond to one thing you said...

Not the main point, but regarding short paths being better.

• From a user perspective, short paths would be easier understood and testable : /properties/config instead of /properties/config/allOf/0

Sure, but what about this sort of schema:

allOf:
  - oneOf:
    - type: object
      properties:
        foo:
          const: "a"

Obviously contrived, but you can see how the subschema will need its JSON pointer context to include the /allOf/0/oneOf/0 bit, so long paths might be unavoidable depending on the schema.

I'll keep poking around here and see if I get further inspiration.

[jy95]

@gnidan Regardless of the component that will use the pointer, we need to specify the context provider. Since code talks more than words sometimes ...

#234 Having a second pair of eyes could help ;) It think it should solve 99% of our present issues.

PS: your example should work with my suggested changes. The fact I don't put the id in the html for CreateNotes case yet is to move implementation forward. Putting id on nodes could come later.

[jy95]

@gnidan Now that 1.10.0 is out, let's see how it goes for you

[gnidan]

I got it working for my purposes last night :D

Unfortunately I had to do some janky stuff... the JSON pointers themselves weren't actually that useful - since your ref resolver removes the $ref fields, a given schema component doesn't know its "canonical" ID+pointer, only the ID+pointer from the viewer root. This turned out to be a bit annoying because I did not want to have long tables of "this pointer in this schema corresponds to this section of the docs", so I ended up just inserting a unique symbol via preprocessing, to contain the ID+pointer at every level. I'm using the changes from 1.10 to check level only (see here).

You can see how I transform my schema to insert IDs here. Not super nice, but it is passable for me I think. I'm able to define a "schema index" with all the HREFs I need... you can see that here if you're curious.

Anyway, it works! (Deployed preview)

Screenshot of desired behavior working now

Thank you for all your help on this! I'm sure I'll talk to you again soon as I continue to leverage this library :)

[gnidan]

Just realized that this discussion is still open. There's probably more to discuss here, but in the end the changes that resulted from this (namely the new context stuff in #234) enable me to achieve what I was looking for with only a small bit of ugly hackery.

I think we can close this until someone else wants something better :)