For any schema that defines a $ref property alongside any other properties, docusaurus-json-schema-plugin currently loses all other properties and treats the schema as just the $ref'd other schema itself. This is because docusaurus-json-schema-plugin uses the now-unmaintained @stoplight/json-ref-resolver, which is stuck on the old JSON Schema drafts 4-7 semantics. (In those older drafts, this behavior was correct.)
To work around this issue:
Expand the existing schema preprocessing logic to detect all $ref's with siblings
For each such case, replace the { $ref: "...", ...props } with that $ref moved into an available schema composition keyword. (e.g., it might become { ...props, allOf: [{ $ref: "..." }] }).
Throw an error if the schema uses all three composition keywords and there's no place for this weird unnecessary composition. (This seems quite unlikely, though)
Override docusaurus-json-schema-plugin's rendering to detect this preprocessed "unnecessary composition" and treat it as a special-case apart from the normal way it presents lists of composed schemas.
When a schema composition is used with only one item, treat it as representing the extension of a base schema, and present it as such.
Present purely annotative extensions with less visual clutter (like, for when a schema is just { $ref: "...", description: "..." }
For any schema that defines a
$refproperty alongside any other properties, docusaurus-json-schema-plugin currently loses all other properties and treats the schema as just the $ref'd other schema itself. This is because docusaurus-json-schema-plugin uses the now-unmaintained @stoplight/json-ref-resolver, which is stuck on the old JSON Schema drafts 4-7 semantics. (In those older drafts, this behavior was correct.)To work around this issue:
Expand the existing schema preprocessing logic to detect all $ref's with siblings
For each such case, replace the
{ $ref: "...", ...props }with that $ref moved into an available schema composition keyword. (e.g., it might become{ ...props, allOf: [{ $ref: "..." }] }).Throw an error if the schema uses all three composition keywords and there's no place for this weird unnecessary composition. (This seems quite unlikely, though)
Override docusaurus-json-schema-plugin's rendering to detect this preprocessed "unnecessary composition" and treat it as a special-case apart from the normal way it presents lists of composed schemas.
When a schema composition is used with only one item, treat it as representing the extension of a base schema, and present it as such.
Present purely annotative extensions with less visual clutter (like, for when a schema is just
{ $ref: "...", description: "..." }