---
sidebar_label: Overview
toc_max_heading_level: 3
doc_id: 9a4d2c11-6b3f-4f2d-b7d7-8f9b0b5e3e6a
description: Learn how JSON Schema and UI Schema work together in nullplatform to define data and design forms.
keywords:
  - json schema
  - ui schema
  - keywords
  - forms
  - specifications
  - nullplatform
---

# Special schema keys and UI schema

When you define a **service**, **scope**, or **catalog specification** in nullplatform, you describe **what data is needed** and **how it should be filled in the UI**. You do this using two schemas that work together: **JSON Schema** for structure and validation, and **UI Schema** for layout and usability.

In other words:
- **JSON Schema**: Defines the data model, validation rules, and field types.
- **UI Schema**: Defines how those fields are displayed and organized in the UI.

These two schemas work together to generate dynamic configuration forms inside the platform.


## When to use JSON Schema vs UI Schema

Use **JSON Schema** when you need to:

- Define fields and their types (`string`, `number`, `boolean`, `object`, `array`)
- Validate values (`minLength`, `maximum`, `pattern`, etc.)
- Mark fields as required
- Use platform‑specific functionality such as `secret`, `export`, `visibleOn`, and `config`

Use **UI Schema** when you need to:

- Arrange layout (rows, columns, tabs, groups)
- Control usability (toggles, selection patterns, descriptions)
- Add help text or formatting (Markdown labels)
- Apply conditional logic (show/hide/enable/disable fields)

> ✅ **JSON Schema = what the data is**  
> ✅ **UI Schema = how it looks and behaves**


## Where schemas are defined

Both JSON Schema and UI Schema are defined inside a specification under `attributes.schema`.

```json
{
  "attributes": {
    "schema": {
      "type": "object",
      "properties": {
        "region": { "type": "string", "enum": ["us-east-1", "eu-central-1"] }
      },
      "uiSchema": {
        "type": "VerticalLayout",
        "elements": [
          { "type": "Control", "scope": "#/properties/region", "label": "Region" }
        ]
      }
    }
  }
}
```

## Supported specification types

| Spec type | Supports UI Schema               | Supports JSON Schema |
| --------- | -------------------------------- | -------------------- |
| Services  | ✅ Yes                            | ✅ Yes                |
| Scopes    | ✅ Yes                            | ✅ Yes                |
| Catalogs  | Partial (used but no preview UI) | ✅ Yes                |


## Preview your schema

You can preview JSON Schema and UI Schema inside the platform:

- Go to **Platform settings → Services** (or **Scopes**)
- Open a specification
- Add schema definitions
- See changes live in the **Preview panel**

👉 Learn more in **[Preview results live](./preview-results.md)**


## JSON Schema + UI Schema together

These schemas always work together. For example:

| Goal                   | JSON Schema defines         | UI Schema defines               |
| ---------------------- | --------------------------- | ------------------------------- |
| Collect a string field | `type: string`              | Input control                   |
| Validate user input    | `minimum`, `format`, `enum` | —                               |
| Show help text         | `description`               | Markdown help block             |
| Organize layout        | —                           | Group or tabs                   |
| Hide/show by lifecycle | `visibleOn`, `editableOn`   | —                               |
| Conditional UI         | —                           | Rules (`SHOW`, `HIDE`, `APPLY`) |


## Example: combined schema

```json
{
  "type": "object",
  "properties": {
    "environment": {
      "type": "string",
      "enum": ["dev", "staging", "prod"],
      "visibleOn": ["create"]
    },
    "debug": {
      "type": "boolean",
      "default": false
    }
  },
  "uiSchema": {
    "type": "Group",
    "label": "Settings",
    "elements": [
      { "type": "Control", "scope": "#/properties/environment" },
      {
        "type": "Control",
        "scope": "#/properties/debug",
        "options": { "toggle": true }
      }
    ]
  }
}
```