UI Pass-Thru Mode

Status: Normative · Platform version: 0.3.1 · Display label: ADL v0.3

This chapter specifies ADL’s native support for “UI Pass-Thru Mode” (Phase 12.5), a feature that allows arbitrary graphical user interface (GUI) configurations to be safely embedded within ADL schemas without triggering parsing or validation errors.

UI Pass-Thru support was added in v0.3.1 to address the complexity of managing dual-schema architectures (where backend data schemas were separated from frontend presentation schemas).

42.1 Overview

A major feature of modern Kalos applications is the ability for frontends to dynamically generate forms, lists, and tables based on the backend data model.

Historically, Kalos rejected any unrecognized YAML properties in a domain file (e.g. example.yaml), maintaining strict structural integrity. This forced frontends to maintain companion configuration files (like ui.yaml) mapping fields to widgets (e.g., Markdown editors, Date pickers, Hidden fields).

UI Pass-Thru Mode solves this by instructing the Kalos ADL parser to cleanly ingest, store, and re-export any arbitrary configuration object placed under a field’s ui property.

42.2 Schema Definition

Any object field definition within a Resource can optionally include a ui block. Kalos treats this block as an opaque JSON payload (ui_passthru), completely bypassing schema validation for the contents of the block itself.

42.2.1 Example

domain:
  name: cms
  version: "1.0.0"
  resources:
    Article:
      object:
        title:
          type: string
          required: true
        content:
          type: string
          ui:
            widget: "markdown"
            rows: 10
        publishedAt:
          type: datetime
          ui:
            widget: "datetime"
            hidden: true

In the example above, content uses widget: "markdown" and publishedAt uses hidden: true. The Kalos C++ backend engine natively parses this ui object and attaches it directly to the field’s internal memory model.

42.3 Serialization & Export

Kalos preserves the ui object across its entire lifecycle.

When a client queries the live schema via GET /api/v1/domains/{name}/schema, the AdlExporter checks if the ui_passthru internal property is populated. If it is, the exact JSON structure is exported securely into the JSON response:

{
  "domain": {
    "resources": {
      "Article": {
        "object": {
          "content": {
            "type": "string",
            "ui": {
              "widget": "markdown",
              "rows": 10
            }
          }
        }
      }
    }
  }
}

This guarantees a single source of truth for both data persistence constraints and frontend presentation logic, streamlining the development of auto-generating GUIs.