LiveReportArtefact

LiveReportArtefact manifests define production-ready web applications that serve multiple ReportArtefacts as navigable pages with support for dynamic query parameter substitution.

Spec outline

apiVersion: bino.bi/v1alpha1
kind: LiveReportArtefact
metadata:
  name: sales-dashboard
spec:
  title: "Sales Dashboard"
  description: "Interactive sales reporting application"
  routes:
    "/":
      artefact: overview-report
      queryParams:
        - name: YEAR
          default: "2024"
          description: "Year to display"
    "/sales":
      artefact: sales-report
      title: "Sales Analysis"
      queryParams:
        - name: REGION
          description: "Region filter (required)"
    "/regions":
      artefact: region-report
      title: "Regional Breakdown"
    "/quick-view":
      # Alternative: use layoutPages instead of artefact
      layoutPages:
        - summary-page
        - charts-page

Fields

spec.title (required)

Human-readable title of the live report application.

spec.description

Optional description of the application.

spec.routes (required)

Map of URL paths to route configurations. The root route / is mandatory.

Each route must specify either artefact or layoutPages (but not both):

• artefact – name of a ReportArtefact to render for this route.
• layoutPages – name of a LayoutPage or an array of LayoutPage names to render directly (without a ReportArtefact wrapper).
• title – optional page title override.
• queryParams – array of query parameters allowed for this route.

Routes are accessible at their defined paths, e.g., /sales renders sales-report.

Using artefact:

routes:
  "/":
    artefact: overview-report

Using layoutPages (single page):

routes:
  "/":
    layoutPages: overview-page

Using layoutPages (multiple pages):

routes:
  "/":
    layoutPages:
      - page-1
      - page-2
      - page-3

The layoutPages option is useful when you want to serve individual LayoutPage documents directly without defining a full ReportArtefact.

spec.routes[path].queryParams

Array of query parameters allowed for this specific route.

Each parameter has:

• name (required) – parameter name, used as ${name} in documents.
• type – input type for the serve UI. One of: string (default), number, number_range, select, date, date_time.
• default – default value if parameter is not provided.
• optional – if true, the parameter is optional even without a default value. The parameter will be empty if not provided.
• description – human-readable description.
• options – configuration for select, number, and number_range types.

Important: If a parameter has no default and optional is not true, the server returns HTTP 400 with a JSON error listing the missing parameters.

Parameter types

Type	Input control	Description
string	Text input	Default type. Free-text input.
number	Number input	Numeric input with optional min/max/step.
number_range	Dual range slider	For min/max range filtering. Creates two parameters: {name} and {name}_max.
select	Dropdown	Selection from predefined options (static or from a DataSet).
date	Date picker	Date selection (YYYY-MM-DD format).
date_time	DateTime picker	Date and time selection (ISO 8601 format).

Options configuration

The options object supports different settings depending on the parameter type:

For select type:

queryParams:
  - name: REGION
    type: select
    description: "Select region"
    options:
      items:
        - value: "EU"
          label: "Europe"
        - value: "US"
          label: "United States"
        - value: "APAC"
          label: "Asia Pacific"

For select with DataSet:

queryParams:
  - name: CATEGORY
    type: select
    description: "Select category"
    options:
      dataset: category_list
      valueColumn: category_id
      labelColumn: category_name

The referenced DataSet should return rows with the specified columns. If labelColumn is omitted, valueColumn is used for both.

For number and number_range types:

queryParams:
  - name: YEAR
    type: number
    default: "2024"
    options:
      min: 2000
      max: 2030
      step: 1
  - name: PRICE
    type: number_range
    description: "Price range filter"
    options:
      min: 0
      max: 10000
      step: 100

Query parameter substitution

Query parameters are substituted into your report documents using the same ${VAR} syntax as environment variables. This allows dynamic filtering of data.

Example DataSet using a query parameter:

apiVersion: bino.bi/v1alpha1
kind: DataSet
metadata:
  name: filtered_sales
spec:
  type: query
  query: |
    SELECT * FROM sales
    WHERE year = ${YEAR}
    AND region = '${REGION}'

When accessed with ?YEAR=2024&REGION=EU, the query becomes:

SELECT * FROM sales
WHERE year = 2024
AND region = 'EU'

Minimal example

---
apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: main-report
spec:
  filename: main.pdf
  title: "Main Report"
---
apiVersion: bino.bi/v1alpha1
kind: LiveReportArtefact
metadata:
  name: dashboard
spec:
  title: "Dashboard"
  routes:
    "/":
      artefact: main-report

Serve with:

bino serve --live dashboard

Multi-page application

---
apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: overview
spec:
  filename: overview.pdf
  title: "Overview"
---
apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: sales
spec:
  filename: sales.pdf
  title: "Sales Detail"
---
apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: regions
spec:
  filename: regions.pdf
  title: "Regional Analysis"
---
apiVersion: bino.bi/v1alpha1
kind: LiveReportArtefact
metadata:
  name: sales-app
spec:
  title: "Sales Application"
  routes:
    "/":
      artefact: overview
      queryParams:
        - name: YEAR
          default: "2024"
          description: "Reporting year"
    "/sales":
      artefact: sales
      title: "Sales Details"
    "/regions":
      artefact: regions
      title: "Regions"

Dynamic reports with query params

---
apiVersion: bino.bi/v1alpha1
kind: DataSet
metadata:
  name: year_sales
spec:
  type: query
  query: |
    SELECT * FROM raw_sales
    WHERE extract(year from sale_date) = ${YEAR:2024}
---
apiVersion: bino.bi/v1alpha1
kind: DataSet
metadata:
  name: department_list
spec:
  type: query
  query: |
    SELECT DISTINCT department_id, department_name FROM departments ORDER BY department_name
---
apiVersion: bino.bi/v1alpha1
kind: LiveReportArtefact
metadata:
  name: dynamic-report
spec:
  title: "Dynamic Report"
  routes:
    "/":
      artefact: main-report
      queryParams:
        - name: YEAR
          type: number
          default: "2024"
          description: "Year for analysis"
          options:
            min: 2000
            max: 2030
        - name: DEPARTMENT
          type: select
          description: "Department (required)"
          options:
            dataset: department_list
            valueColumn: department_id
            labelColumn: department_name
        - name: START_DATE
          type: date
          description: "Start date for report period"
        - name: AMOUNT_RANGE
          type: number_range
          description: "Filter by amount"
          options:
            min: 0
            step: 100

Access patterns:

• / – uses default YEAR=2024, but requires DEPARTMENT
• /?DEPARTMENT=sales – works, uses default YEAR
• /?YEAR=2023&DEPARTMENT=marketing – overrides YEAR
• /?YEAR=2023 – returns HTTP 400: missing DEPARTMENT

Navigation

LiveReportArtefact applications include built-in navigation. When navigating between routes:

1. The browser URL updates via History API.
2. Only the report content is fetched and swapped.
3. Assets (CSS, fonts, scripts) are not reloaded.

This provides a smooth single-page application experience while maintaining proper URL routing.

Validation

The CLI validates LiveReportArtefact manifests at load time:

• Root route / must be present.
• All route paths must start with /.
• All referenced artefact names must correspond to existing ReportArtefact manifests.
• Query parameter names must be unique within each route.

Validation errors are reported before the server starts.