Build a Schema

Utilizing the Schema Editor

The Schema Editor is a powerful tool that aids in designing and modeling the data structures your API utilizes. It is based on JSON Schema and is utilized for designing JSON or XML data structures.

Utilize the Schema Editor to:

Develop API request and response bodies tailored for specific API endpoints.

Construct data models that are applicable across one or several APIs.

Every schema begins with a root object. To build a schema, add properties to this root object.

Building a Schema

Add Properties

Click on the + (Add a child node) sign next to the root object to introduce new properties.

Name Your Property

Enter the name (or key) for the property.

Select Property Type

Choose common data types or select references to predefined schemas.

Advanced Settings

Utilize the Type Editor to assign data types, such as default values and formats, for each property.

Manage Properties

Rearrange properties by moving, copying, or deleting them. You can also embellish properties with descriptions and mark them as required.

Alternative Methods

You can also create new schemas by importing from database tables or JSON schema files. Learn more about Generate Schemas from JSON etc..

Property Type

In alignment with the JSON Schema standard, the Apidog Schema Editor supports the following basic data types:

Type	Description
null	Represents a JSON "null" value.
boolean	Represents a "true" or "false" value, corresponding to the JSON "true" or "false" value.
object	Represents an unordered collection of key-value pairs, corresponding to the JSON "object" value.
array	Represents an ordered list of values, corresponding to the JSON "array" value.
number	Represents an arbitrary-precision, base-10 decimal number value, corresponding to the JSON "number" value.
string	Represents a string of Unicode characters, corresponding to the JSON "string" value.

Array Data Type

When using the array data type, a sub-level ITEMS property will be automatically generated. It specifies the data type of the elements within the array.

In addition to the standard data structures mentioned earlier, the Apidog Schema Editor also supports the following:

Reference other schemas: Ability to reference and reuse schemas defined elsewhere within the API documentation.

any: Represents a value that can be of any data type.

Schema Composition: Allows for combining multiple schemas to create complex data structures.

Customization: Enables users to customize and tailor the schema to meet specific requirements and data modeling needs.

Referencing Other Schemas

You can utilize the "Reference other schemas" feature to reference previously defined schemas.

After referencing another schema, you can view the referenced schema in the Schema Editor.

Key points about referenced schemas:

Any modifications made to the original schema will be reflected in the referencing schema.

The referenced schema cannot be directly edited; to make changes, you can:

Click the schema name to navigate to the original schema to edit.

By clicking Dereference on the schema, the schema will transform into a series of independent properties, allowing you to edit them individually.

If you need to modify a specific property's definition independently, you can choose to Dereference that property, allowing for individual modifications. Any changes to the original schema will not affect the dereferenced property.

In cases where not all properties of the referenced schema are required in the endpoint, you can click Hide to conceal unnecessary properties.

Schema Composition

If a property in your data structure can have multiple possible data types, you can use Schema Composition to combine multiple schemas.

Apidog supports the following composition keywords:

Keyword	Description
allOf (AND)	Specifies that the property must adhere to all the schemas defined in the composition.
anyOf (OR)	Specifies that the property can conform to any of the schemas listed in the composition.
oneOf (XOR)	Specifies that the property must adhere to one and only one of the schemas defined in the composition.

After selecting Schema Composition, sub-properties named "0" and "1" will appear under the property, representing each schema within the composition. You can modify the schema type for each sub-property and add additional schemas as needed.

In the API documentation, Schema Composition will be displayed like this:

You'll notice the two optional objects under OneOf. If you want to display their names as shown in the image, you need to enter the names in the title field in the Type editor.

Customization

By choosing "Customize," you can directly edit the JSON Schema within the editor.

Property Settings

For each property, there are several buttons located next to the data type:

Button	Description
*	Indicates if the property is required.
N	Specifies if the property allows for null values.
Settings	Allows you to edit advanced settings in the Type Editor.

Type Editor

The Type Editor visually describes a property in alignment with JSON Schema.

Once these advanced settings are configured, they will take effect in the following areas:

When adding response examples, you can click to auto-generate based on the settings.

They will be displayed in the API documentation.

In the request body, you can click to auto-generate based on the settings.

Upon sending a request, the returned data will be automatically validated against the settings.

In the mock service, response data will be generated based on the settings.

Enumerated Property

For String, Integer, and Number types, Apidog supports enum. By toggling the enum switch, you can add enum values and descriptions. Additionally, you can perform Bulk Edit for enum values.

Mock

In addition to the advanced settings in the property, you can specify mock content for fields by filling in mock values. Mock values take precedence over the settings in advanced settings.

Mock values support Faker.js syntax, allowing you to choose the desired faker data directly from the dropdown options.

Mock values can also be entered as fixed values.

XML Settings

For XML data, the Type Editor in Apidog offers additional XML Settings. You can enable the XML switch, configure properties such as tag name, namespace, etc., and preview the corresponding XML structure.

HashMap, Dictionary, Array

HashMap, also known as Map, dictionary, or associative array. It is a collection of key-value pairs, where the key names can be any content, rather than predefined.

The OpenAPI specification supports defining a HashMap with string keys. This is done by setting the element type to object, and then using the additionalProperties keyword to specify the type of the values in the key-value pairs.

Suppose there is a user information query API, and the returned data format has the following requirements:

The returned data is an object

The child elements of the object are key-value pairs of a HashMap

The user ID is the key, and the user information is the value

To define this in Apidog:

Create a new schema and name it "UserProfiles".

In the "UserProfiles", specify the root node as an "object" type. Then click Advanced Configuration, set additionalProperties to Allow, and click the Settings button on the right.

In the pop-up, add the required user information, with the user's name and email as fields of the object. It saves automatically.

In the API documentation's responses, reference the schema at the root node and select "user profiles" that you just created.

Click save, and then you can see the defined schema and example values in the return response example within the API documentation.

Objects with additionalProperties

As the actual development work iterates, the objects returned by the API may have additionalProperties compared to the originally defined object. According to the OpenAPI specification, this situation can also be handled using the "additionalProperties" feature.

Suppose there is now a user information query API, where the originally defined response fields when querying user information by user ID were name and email. Now, with the system upgrade, you want to include other fields.

When editing the API documentation, you can define it as follows: In the root node of the data model, click Advanced Settings, set additionalProperties to Allow, and set the field value type to any.

Then you can see the defined data structure and example values in the API documentation.

Data structure with additionalProperties

Tuples

Typically, the internal elements of an array must be of the same type, while tuples can contain different types of data. If you want to define a tuple that includes both string and integer types, such as data like (0,"A",2,"C"), you can set the element type to array in the data model, then set the type of items to anyOf in the combination pattern, and then add child elements of type string and integer respectively.

TIP

If you want to generate multiple elements when generating examples, please specify the minimum and maximum number of elements in the advanced settings of the root node.

After saving, click Generate Automatically in the API documentation to see the defined data structure and example values.

You can also see the example values of the tuple in the return response in the documentation.

Tools

The Schema Editor in Apidog provides several highly useful tools.

Tool	Description
Generate from JSON etc.	This tool allows you to automatically generate schemas from JSON, XML data, and other sources, or directly from database table structures. Learn more about Generate schemas from JSON etc..
Preview	This tool creates mock data that adheres to the schema definition, providing a preview of the expected data.
Generate code	This tool can produce data structure definition code in various programming languages. Learn more about Generate code.
JSON Schema	This tool allows direct editing of JSON schemas for fine-tuning and customization.

FAQ

Q: If a string property has multiple enumerated values and is used in various locations, how can this enum be consistently referenced throughout?

A: You can define this property as a standalone schema consisting of a single property, enabling it to be consistently referenced across different parts of the API documentation.

Utilizing the Schema Editor#

Building a Schema#

Property Type#

Referencing Other Schemas#

Schema Composition#

Customization#

Property Settings#

Type Editor#

Enumerated Property#

Mock#

XML Settings#

HashMap, Dictionary, Array#

Objects with additionalProperties#

Tuples#

Tools#

FAQ#

Utilizing the Schema Editor

Building a Schema

Property Type

Referencing Other Schemas

Schema Composition

Customization

Property Settings

Type Editor

Enumerated Property

Mock

XML Settings

HashMap, Dictionary, Array

Objects with additionalProperties

Tuples

Tools

FAQ