Skip to content

UI Components Spec

Specification of the json format (as JSON Schema) of the Data UI Blocks produced by the UI Agent json UI renderer. Mainly useful to implement client-side renderers as they consume this format.

How relevant object types are generated to TypeScript then can be tested here: https://transform.tools/json-schema-to-typescript

Dynamic components for one Object input data

Dynamic Components Documentation
One Object input data Documentation

One Card

One Card JSON Schema

Example JSON output: 

{
  "component": "one-card",
  "id": "test-id",
  "title": "Toy Story Details",
  "image": "https://image.tmdb.org/t/p/w440_and_h660_face/uXDfjJbdP4ijW5hWSBrPrlKpxab.jpg",
  "fields": [
    {
      "data": [
        "Toy Story"
      ],
      "data_path": "movie.title",
      "name": "Title"
    },
    {
      "data": [
        1995
      ],
      "data_path": "movie.year",
      "name": "Year"
    },
    {
      "data": [
        8.3
      ],
      "data_path": "movie.imdbRating",
      "name": "IMDB Rating"
    },
    {
      "data": [
        "2022-11-02 00:00:00"
      ],
      "data_path": "movie.released",
      "name": "Release Date"
    },
    {
      "data": [
        "Jim Varney",
        "Tim Allen",
        "Tom Hanks",
        "Don Rickles"
      ],
      "data_path": "actors[*]",
      "name": "Actors"
    }
  ]
}

Image

JSON Schema

Example JSON output: 

{
  "component": "image",
  "id": "test-id",
  "image": "https://image.tmdb.org/t/p/w440_and_h660_face/uXDfjJbdP4ijW5hWSBrPrlKpxab.jpg",
  "title": "Toy Story Poster"
}

Video Player

JSON Schema

Example JSON output: 

{
  "component": "video-player",
  "id": "test-id",
  "title": "Toy Story Trailer",
  "video": "https://www.youtube.com/embed/v-PjgYDrg70",
  "video_img": "https://img.youtube.com/vi/v-PjgYDrg70/maxresdefault.jpg"
}

Dynamic components for Array of objects input data

Dynamic Components Documentation
Array of objects input data Documentation

Set Of Cards

JSON Schema

Example JSON output: 

{
  "component": "set-of-cards",
  "id": "test-id",
  "title": "My Favorite Movies",
  "fields": [
    {
      "data": [
        "Toy Story",
        "My Name is Khan"
      ],
      "data_path": "movie.title",
      "name": "Title"
    },
    {
      "data": [
        1995,
        2003
      ],
      "data_path": "movie.year",
      "name": "Year"
    },
    {
      "data": [
        8.3,
        8.5
      ],
      "data_path": "movie.imdbRating",
      "name": "IMDB Rating"
    },
    {
      "data": [
        [
          "Jim Varney",
          "Tim Allen",
          "Tom Hanks",
          "Don Rickles"
        ],[
          "Shah Rukh Khan",
          "Kajol Devgan"
        ]
      ],
      "data_path": "actors[*]",
      "name": "Actors"
    }
  ]
}

Table

JSON Schema

Example JSON output: 

{
  "component": "table",
  "id": "test-id",
  "title": "My Favorite Movies",
  "fields": [
    {
      "data": [
        "Toy Story",
        "My Name is Khan"
      ],
      "data_path": "movie.title",
      "name": "Title"
    },
    {
      "data": [
        1995,
        2003
      ],
      "data_path": "movie.year",
      "name": "Year"
    },
    {
      "data": [
        8.3,
        8.5
      ],
      "data_path": "movie.imdbRating",
      "name": "IMDB Rating"
    },
    {
      "data": [
        [
          "Jim Varney",
          "Tim Allen",
          "Tom Hanks",
          "Don Rickles"
        ],[
          "Shah Rukh Khan",
          "Kajol Devgan"
        ]
      ],
      "data_path": "actors[*]",
      "name": "Actors"
    }
  ]
}

Chart

JSON Schema

Chart components support multiple visualization types:

  • chart-bar - Bar charts for comparing metrics across categories
  • chart-line - Line charts for trends over time
  • chart-pie - Pie charts for showing proportions
  • chart-donut - Donut charts for showing proportions with a central metric
  • chart-mirrored-bar - Mirrored bar charts for comparing two metrics side-by-side

Example JSON output (bar chart):

{
  "component": "chart-bar",
  "id": "test-id",
  "title": "Sales Data",
  "x_axis_label": "Month",
  "data": [
    {
      "name": "Q1",
      "data": [
        {"x": "Jan", "y": 100},
        {"x": "Feb", "y": 150},
        {"x": "Mar", "y": 200}
      ]
    },
    {
      "name": "Q2",
      "data": [
        {"x": "Apr", "y": 180},
        {"x": "May", "y": 220},
        {"x": "Jun", "y": 250}
      ]
    }
  ]
}

Data for chart can be represented as one or more named data series in the data array, containing array of data points. Data point contains x (string or number) and y (number) values.

Example JSON output (line chart - standard): 

{
  "component": "chart-line",
  "id": "test-id",
  "title": "Sales and Profit Over Time",
  "x_axis_label": "Month",
  "data": [
    {
      "name": "Sales",
      "data": [
        {"x": "Jan", "y": 100},
        {"x": "Feb", "y": 150},
        {"x": "Mar", "y": 120}
      ]
    },
    {
      "name": "Profit",
      "data": [
        {"x": "Jan", "y": 20},
        {"x": "Feb", "y": 35},
        {"x": "Mar", "y": 25}
      ]
    }
  ]
}

Example JSON output (line chart - multi-series): 

{
  "component": "chart-line",
  "id": "test-id",
  "title": "Weekly Revenue by Movie",
  "x_axis_label": "Week",
  "data": [
    {
      "name": "Movie A",
      "data": [
        {"x": "W1", "y": 100},
        {"x": "W2", "y": 150}
      ]
    },
    {
      "name": "Movie B",
      "data": [
        {"x": "W1", "y": 80},
        {"x": "W2", "y": 120}
      ]
    }
  ]
}

Note: The x_axis_label field is automatically populated from the first field's name for standard charts, or the second field's name for multi-series line charts. This label can be used by renderers to display the x-axis label on the chart.

Exact data requirements for individual chart types, and how are they converted from the UI Agent input data structures, is described in this documentation guide.

Hand Build Component (aka HBC)

Hand Build Component (HBC) Documentation

HBC expects there is a hand build code implemented and registered in the UI renderer for component value, which is able to visualize/show JSON from the data field, which is simply input data into the UI Agent (transformed to JSON if necessary). How to register hand-build code for the component depends on the UI renderer type, see renderers documentation please.

JSON Schema

Example JSON output: 

{
  "id": "test-id",
  "component": "movies:movie-detail",
  "data": {
    "movie": {
      "title": "Toy Story",
      "trailer": "https://www.youtube.com/embed/v-PjgYDrg70",
      "poster": "https://image.tmdb.org/t/p/w440_and_h660_face/uXDfjJbdP4ijW5hWSBrPrlKpxab.jpg"
    }
  }
}