---
title: "Schemas"
slug: "schemas-overview"
tags: ["workspaces"]
updated: 2026-09-15T16:49:39Z
published: 2026-09-15T16:49:39Z
canonical: "docs.unqork.io/schemas-overview"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Schemas

A Schema is a JSON Schema definition that specifies the fields, types, and validation rules for a [Data Model](/unqorkai/docs/data-models-overview). Every Data Model must link to a published Schema. Schemas are managed independently from Data Models. Multiple Data Models can share a common field structure, and a Data Model can be updated to a new Schema version over time.

## When to Use Schemas

Schemas are the foundation of any application that uses Data Models. Create a Schema when any of the following apply:

- The application stores structured, typed records that multiple modules read or write.
- Field-level validation must be enforced at the data layer, not only in UI forms.
- The record structure might change over time and must be managed through a version-controlled definition.

## Schema Lifecycle

Each Schema moves through two states: **Draft** and **Published**.

| State | Description |
| --- | --- |
| **Draft** | The Schema is editable. Creators can rename it, replace its JSON definition, and publish it when it is ready for use. |
| **Published** | The Schema is locked and read-only. Data Models can only link to published Schemas. The JSON definition cannot be changed after publishing. |

> [!NOTE]
> Publishing a Schema is irreversible. Once a Schema is published, its definition is permanent. To make changes to a published Schema, duplicate it to create a new Draft, edit that Draft, then publish it when ready.

The transition from Draft to Published is a deliberate gate. It prevents unreviewed or incomplete Schema definitions from being used in production Data Models.

## Schemas in the Workspace

![[docs-mockup:DocsSchemaExplorerMockup] Schema Explorer panel](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20260915_163808_846f29e608d247d7ab5e835eaa4404af.png?sv=2026-02-06&spr=https&st=2026-11-03T08%3A17%3A31Z&se=2026-11-03T09%3A17%3A31Z&sr=c&sp=r&sig=U57K1q6He5ZscKmdcIYGgoAB1JKEHyizBlzDSS7K68k%3D)

Schemas are accessible from the **Explorer panel**. In the panel, expand the **Schemas** folder to see the Schema files in the current workspace. Select a Schema file to open its definition page.

> [!NOTE]
> If the Schemas folder is not visible in the Explorer panel, a workspace administrator must enable the Data Models feature for the organization.

## Creating a Schema

To create a Schema, hover over the Schemas folder in the Explorer panel, click the ⋮ (**ellipsis**) button, then select **Create Schema**. In the creation dialog, complete the following:

- **Name** (required): A display name for the Schema, unique in the workspace.
- **Schema File** (required): Upload a valid JSON Schema file. The file defines the field structure: field names, types, and validation rules.
- **Ref /** (optional): An external reference identifier. Use this field to associate the Schema with an external system or data owner.

New Schemas always begin in **Draft** status.

The platform validates the JSON file on upload. The following rules must be met for a Schema to be accepted:

- The root `type` must be `"object"`. A Schema cannot have an array as its top-level type.
- The root must include a `properties` key with at least one field defined.
- `additionalProperties` is not permitted at the root level.
- Property keys must not contain periods. The platform uses for data resolution, so a key like `address.city` is rejected.
- Fields with `type: "array"` must include an `items` key that defines the array's item type.
- Fields that use `format` or `pattern` must also include `maxLength`. This is a security requirement that prevents slow validation on large strings.
- These JSON Schema keywords are not supported and must be omitted: `$ref`, `allOf`, `anyOf`, `oneOf`, `not`, `if`, `then`, `else`, `definitions`, `patternProperties`, and `examples`.

The following is an example of a valid JSON Schema file:

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Loan Applicant",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "maxLength": 255,
      "description": "The applicant's first name"
    },
    "lastName": {
      "type": "string",
      "maxLength": 255,
      "description": "The applicant's last name"
    },
    "dateOfBirth": {
      "type": "string",
      "format": "date",
      "maxLength": 10,
      "description": "The applicant's date of birth"
    },
    "annualIncome": {
      "type": "number",
      "description": "The applicant's annual income in USD"
    },
    "isEmployed": {
      "type": "boolean",
      "description": "Whether the applicant is currently employed"
    }
  },
  "required": ["firstName", "lastName", "dateOfBirth"]
}
```

## Schema Definition Page

Select a Schema from the Explorer panel to open its definition page. For details on the definition page layout, available fields, and actions, see [Schema Definition Page](/unqorkai/docs/schema-definition-page).

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-08-05 | Corrected Schemas in the Workspace section — removed inaccurate list page description; Schemas are accessed by expanding the Schemas folder in the Explorer panel. |
| 2026-08-04 | Split Schema Detail and Actions into separate Schema Definition Page article. Moved JSON example to Creating a Schema section. Fixed Explore panel terminology. |
| 2026-08-03 | Initial publication. |

JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data.

The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application.

Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform.

A functionality of a software. For example, Copy and Paste is a feature of a computer's operating system.

An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects.

A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases.

A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases.

A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.