Schemas

A Schema is a JSON Schema definition that specifies the fields, types, and validation rules for a Data Model. 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.

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

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:

{
  "$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.