-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Hack around limitation re: $refs with siblings
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
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 versions, 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: "..." }`- Loading branch information
Showing
3 changed files
with
229 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
144 changes: 144 additions & 0 deletions
144
packages/web/src/theme/JSONSchemaViewer/components/UnnecessaryComposition.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,144 @@ | ||
| import React from "react"; | ||
| import type { JSONSchema } from "json-schema-typed/draft-2020-12"; | ||
| import CreateNodes from "@theme/JSONSchemaViewer/components/CreateNodes"; | ||
| import CreateEdge from "@theme-original/JSONSchemaViewer/components/CreateEdge"; | ||
| import { SchemaHierarchyComponent } from "@theme-original/JSONSchemaViewer/contexts" | ||
| import { Collapsible } from "@theme/JSONSchemaViewer/components"; | ||
| import { GenerateFriendlyName, QualifierMessages } from "@theme/JSONSchemaViewer/utils"; | ||
| import { internalIdKey } from "@site/src/contexts/SchemaContext"; | ||
| import { CreateDescription } from "@theme/JSONSchemaViewer/JSONSchemaElements"; | ||
| import { useJSVOptionsContext } from "@theme/JSONSchemaViewer/contexts" | ||
|
|
||
| export interface UnnecessaryComposition { | ||
| schemaWithoutUnnecessaryComposition: Exclude<JSONSchema, boolean>; | ||
| unnecessaryCompositionKeyword: "allOf" | "oneOf" | "anyOf"; | ||
| unnecessarilyComposedSchema: JSONSchema; | ||
| } | ||
|
|
||
| export function detectUnnecessaryComposition( | ||
| schema: JSONSchema | ||
| ): UnnecessaryComposition | undefined { | ||
| if (typeof schema === "boolean") { | ||
| return; | ||
| } | ||
|
|
||
| const unnecessaryCompositionKeywords = (["allOf", "oneOf", "anyOf"] as const) | ||
| .filter(keyword => keyword in schema && (schema[keyword] || []).length === 1); | ||
|
|
||
| if (unnecessaryCompositionKeywords.length !== 1) { | ||
| return; | ||
| } | ||
|
|
||
| const [unnecessaryCompositionKeyword] = unnecessaryCompositionKeywords; | ||
|
|
||
| const { | ||
| [unnecessaryCompositionKeyword]: composition, | ||
| ...schemaWithoutUnnecessaryComposition | ||
| } = schema; | ||
|
|
||
| const [unnecessarilyComposedSchema] = | ||
| composition as [JSONSchema] /* (we know this from filter above) */; | ||
|
|
||
| return { | ||
| unnecessarilyComposedSchema, | ||
| unnecessaryCompositionKeyword, | ||
| schemaWithoutUnnecessaryComposition | ||
| }; | ||
| } | ||
|
|
||
| export interface UnnecessaryCompositionSchemaProps extends UnnecessaryComposition { | ||
| } | ||
|
|
||
| export default function UnnecessaryCompositionSchema({ | ||
| schemaWithoutUnnecessaryComposition, | ||
| unnecessaryCompositionKeyword, | ||
| unnecessarilyComposedSchema | ||
| }: UnnecessaryCompositionSchemaProps): JSX.Element { | ||
| const jsvOptions = useJSVOptionsContext(); | ||
|
|
||
| // treat the unnecessary composition to represent the extension of a base | ||
| // schema, where the unnecessarily composed schema is the base | ||
| const baseSchema = unnecessarilyComposedSchema; | ||
| const extensionSchema = schemaWithoutUnnecessaryComposition; | ||
| const { | ||
| documentation, | ||
| semantics | ||
| } = separateDocumentationFromSemantics(extensionSchema); | ||
|
|
||
| if (Object.keys(semantics).length === 0) { | ||
| const { description } = documentation; | ||
|
|
||
| return <> | ||
| <QualifierMessages schema={documentation} options={jsvOptions} /> | ||
| {description && <CreateDescription description={description} />} | ||
| <hr /> | ||
|
|
||
| <SchemaHierarchyComponent | ||
| innerJsonPointer={`/${unnecessaryCompositionKeyword}/0`} | ||
| > | ||
| <CreateNodes schema={unnecessarilyComposedSchema} /> | ||
| </SchemaHierarchyComponent> | ||
| </>; | ||
| } | ||
|
|
||
| return ( | ||
| <> | ||
| <span className="badge badge--info">extensions</span> | ||
| These extensions apply to the base schema below: | ||
| <p> | ||
| <CreateNodes schema={extensionSchema} /> | ||
| </p> | ||
|
|
||
| <Collapsible | ||
| summary={ | ||
| <> | ||
| <strong><GenerateFriendlyName schema={baseSchema} /></strong> | ||
| <span className="badge badge--info">base schema</span> | ||
| </> | ||
| } | ||
| detailsProps={{ | ||
| open: true | ||
| }} | ||
| > | ||
| <SchemaHierarchyComponent | ||
| innerJsonPointer={`/${unnecessaryCompositionKeyword}/0`} | ||
| > | ||
| <CreateNodes schema={unnecessarilyComposedSchema} /> | ||
| </SchemaHierarchyComponent> | ||
| </Collapsible> | ||
|
|
||
| </> | ||
| ); | ||
| } | ||
|
|
||
| function separateDocumentationFromSemantics(schema: JSONSchema): { | ||
| documentation: Exclude<JSONSchema, boolean>, | ||
| semantics: JSONSchema | ||
| } { | ||
| if (typeof schema === "boolean") { | ||
| return { | ||
| documentation: {}, | ||
| semantics: schema | ||
| }; | ||
| } | ||
|
|
||
| const { | ||
| title, | ||
| description, | ||
| examples, | ||
| default: default_, | ||
| // @ts-ignore | ||
| [internalIdKey]: _id, | ||
| ...semantics | ||
| } = schema; | ||
|
|
||
| return { | ||
| documentation: { | ||
| title, | ||
| description, | ||
| examples, | ||
| default: default_ | ||
| }, | ||
| semantics | ||
| }; | ||
| } |