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):

Copy
Copied
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 the pointer 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

Enum: "available" "pending" "sold"

The following code block inserts the JsonSchema component into the page.

Copy
Copied
<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

Enum: "available" "pending" "sold"
petType
string

Type of a pet

huntingSkill
required
string
Default: "lazy"

The measured skill for hunting

Enum: "clueless" "lazy" "adventurous" "aggressive"

In this example, the schema is manually written in the code block.

Copy
Copied
<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 will not be rendered if you don't include the required properties in your code block.

Props

NameTypeDescription
definitionId*stringSpecifies 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.
optionsobjectUse Reference docs configuration options in this object to customize the appearance and behavior of the component.
pointer*stringJSON 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*objectSpecifies 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.

Copy
Copied
<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.

Copy
Copied
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.

Copy
Copied
<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.