JSON Schema and UI Schema overview

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. This is done 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.

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

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

{
  "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 }
      }
    ]
  }
}