JsonSchema
With the JsonSchema
component, you can insert JSON schemas into MDX pages in your portal. The schemas can be imported from API definitions, or added as standalone schemas imported from a file or written manually in the component (but there is no $ref
support for the standalone schemas).
When the component is included in an MDX page, the JSON schema is rendered to look like response and request body schemas in Reference pages (without the code samples panel).
To use the component in an MDX page, you must first import it (usually at the top of the page):
import { componentName } from '@redocly/developer-portal/ui';
Then, insert the component code block wherever you want it to appear in the page.
To insert a JSON schema, you must use one of the following methods in your component code block:
- specify the
definitionId
of the API document and thepointer
to the schema within the document - add the
schema
property with the path to the file containing the JSON schema, or with the schema body directly in the code block
Here is an example of the JsonSchema
component inserted into an MDX page (this page).
id | integer <int64> |
object (Category) | |
name required | string |
photoUrls required | Array of strings |
Array of objects (Tag) | |
status | string pet status in the store |
The following code block inserts the JsonSchema
component into the page.
<JsonSchema definitionId="petstore" pointer="#/components/schemas/Pet" />
In the previous example, we used the definitionId
and pointer
properties to insert the schema. For comparison, here is the component with the schema
property.
name | string The name given to a pet |
status | string Pet status in the store |
petType | string Type of a pet |
huntingSkill required | string Default: "lazy" The measured skill for hunting |
In this example, the schema is manually written in the code block.
<JsonSchema
schema={{
type: 'object',
description: 'A representation of a cat',
properties: {
huntingSkill: {
type: 'string',
description: 'The measured skill for hunting',
default: 'lazy',
example: 'adventurous',
enum: ['clueless', 'lazy', 'adventurous', 'aggressive'],
},
},
required: ['huntingSkill'],
}}
/>
Component properties
Use the following properties to customize the component when inserting it into an MDX page. Required properties are marked with an asterisk (*
).
Note that the component is not rendered if you don't include the required properties in your code block.
Props
Name | Type | Description |
---|---|---|
definitionId* | string | Specifies the API definition to use in the component. The value must match one of the definition IDs from the `oasDefinitions` section of the `siteConfig.yaml` file. |
options | object | Use Reference docs configuration options in this object to customize the appearance and behavior of the component. |
pointer* | string | JSON pointer to a schema from the specified API definition that will be used in the component. The pointer should be relative to the root of the API definition in the form of a URI (e.g. `#/components/schemas/User`). Required only if using `definitionId`. |
schema* | object | Specifies the JSON Schema contents to display in the component. The object can contain the full schema or a reference to an imported schema file. Mutually exclusive with `definitionId` and required only if not using `definitionId` and `pointer`. |
Usage examples
Add the options
object
Use the options
object to customize the component by applying supported Reference docs options.
The JsonSchema
component supports the following options:
jsonSampleExpandLevel
schemaExpansionLevel
In this example, we're adding some of the supported configuration options to the options
object.
<JsonSchema
definitionId="petstore"
pointer="#/components/schemas/Pet"
options={{
schemaExpansionLevel: 5,
}}
/>
Import schema as a standalone file
When using the schema
property instead of definitionId
and pointer
, you can save your JSON schema in a standalone file and import it from there.
To import the file, specify the file reference and its path at the top of your MDX page.
import { JsonSchema } from '@redocly/developer-portal/ui';
import Schema from './developer-portal/schemas/example-schema.yaml';
In this example, Schema
is the file reference. Use this reference in the component code block together with the schema
property to import the JSON schema directly from the file.
<JsonSchema
schema={Schema}
/>
Note that this imports the entire contents of the file. The schema in the file must be valid for the component to display it.