ReportArtefact

ReportArtefact manifests define top-level report outputs. Each artefact typically corresponds to one PDF file.

Minimal definition

This is the smallest well-formed ReportArtefact: the two required fields (filename, title) plus the fields a real report sets, because their defaults rarely fit — page geometry, renderer language and the page order.

apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: sales_report
spec:
  format: xga
  orientation: landscape
  language: en
  filename: sales-report.pdf
  title: "Sales Overview"
  layoutPages:
    - cover
    - sales-*

All attributes are listed in the Attribute Reference below. Each layoutPages entry has two forms: a name or glob pattern as shown here (see Page selection) and an object with page and params (see Parameterized LayoutPages).

Fields:

• spec.format – logical page size, default xga.
• spec.orientation – portrait or landscape, default landscape.
• spec.language – current options: de or en, default de.
• spec.layoutPages – optional list of patterns to select LayoutPages by metadata.name. Supports glob syntax (*, ?, [abc]). A single pattern may also be written as a plain string (layoutPages: cover). Pages appear in pattern order; within each pattern, pages are sorted alphabetically. Default: ["*"] (every LayoutPage in the bundle).
• spec.filename – required output filename (relative to output directory).
• spec.title – required human-readable title; also used in PDF metadata.
• spec.description – optional description.
• spec.subject – optional subject stored in PDF metadata.
• spec.author – optional author name.
• spec.keywords – optional list of metadata keywords.
• spec.signingProfile – optional reference to a SigningProfile manifest.
• spec.selectedStyle – optional reference to a named ComponentStyle applied as the default style for every page and component in this artefact. A selectedStyle set on a page, card, grid, tree, or leaf component overrides it (nearest ancestor wins).
• spec.i18nNamespace – optional i18n namespace inherited as the default by every page and component in this artefact. An i18nNamespace set on a page, card, grid, tree, or leaf component overrides it (nearest ancestor wins).

Default style

Set spec.selectedStyle once on the artefact to theme the whole report:

apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: sales_report
spec:
  filename: sales-report.pdf
  title: "Sales Overview"
  selectedStyle: corporateTheme

Every LayoutPage and component in the artefact now renders with corporateTheme unless it selects its own style. See Component style — Style inheritance for the full precedence rules.

Minimal artefact

---
apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: monthly_sales
spec:
  filename: monthly-sales.pdf
  title: "Monthly Sales Report"

Artefact with signing

---
apiVersion: bino.bi/v1alpha1
kind: SigningProfile
metadata:
  name: corporateSigner
spec:
  certificate:
    path: ./certs/corporate-cert.pem
  privateKey:
    path: ./certs/corporate-key.pem
  signer:
    name: "Group Controlling"
    location: "Headquarters"
    reason: "Approved financial report"
---
apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: annual_sales
spec:
  format: a4
  orientation: portrait
  language: en
  filename: annual-sales.pdf
  title: "Annual Sales Report"
  description: "Yearly consolidated sales figures."
  author: "Group Controlling"
  signingProfile: corporateSigner

Page selection

By default, a ReportArtefact includes every LayoutPage in the bundle, in alphabetical order — a page is only left out when its own metadata.constraints exclude it. Use spec.layoutPages to explicitly select which pages to include and control their order.

---
apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: quarterly-report
spec:
  format: xga
  layoutPages:
    - cover              # cover page first
    - executive-summary  # then summary
    - detail-*           # all detail pages (alphabetically)
    - appendix-*         # appendices last
  filename: quarterly-report.pdf
  title: "Quarterly Report"

Pattern syntax:

• * matches any sequence of characters
• ? matches a single character
• [abc] matches any character in the set

Pages are rendered in the order their patterns appear. Within each pattern, matching pages are sorted alphabetically by name.

Parameterized LayoutPages

You can include the same LayoutPage multiple times with different parameter values. This is useful for generating reports that repeat a layout for different regions, time periods, or other dimensions.

Basic syntax

Use the object form with page and params to pass parameter values:

apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: regional-report
spec:
  format: xga
  layoutPages:
    # String form - simple page reference
    - cover-page

    # Object form - page with parameters
    - page: regional-sales
      params:
        REGION: EU
        YEAR: "2024"

    # Same page with different parameters
    - page: regional-sales
      params:
        REGION: US
        YEAR: "2024"

    - page: regional-sales
      params:
        REGION: APAC
        YEAR: "2024"

  filename: regional-report.pdf
  title: "Regional Sales Report"

Each parameterized reference creates a unique page instance with the specified values substituted into the LayoutPage's spec.

All params values are strings. Quote numbers and dates (YEAR: "2024"), otherwise the manifest fails schema validation.

Mixing forms

You can mix string patterns and parameterized objects in the same list:

layoutPages:
  - cover                          # String: exact name
  - executive-summary              # String: exact name
  - page: regional-sales           # Object: with params
    params:
      REGION: EU
  - page: regional-sales
    params:
      REGION: US
  - appendix-*                     # String: glob pattern

Note

Glob patterns (*, ?, [abc]) only work with the string form. To pass parameters, you must use the object form with an explicit page name.

Dynamic parameter values

Parameter values can reference environment variables:

layoutPages:
  - page: regional-sales
    params:
      REGION: ${DEFAULT_REGION}      # Resolved from environment
      YEAR: ${REPORT_YEAR:2024}      # With fallback default

This enables runtime configuration of reports without modifying the manifest.

Example: Multi-region report

---
# Define a parameterized LayoutPage (in pages.yaml)
apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: regional-sales
  params:
    - name: REGION
      type: select
      required: true
      options:
        items:
          - value: "EU"
            label: "Europe"
          - value: "US"
            label: "North America"
          - value: "APAC"
            label: "Asia Pacific"
    - name: YEAR
      type: number
      default: "2024"
spec:
  titleBusinessUnit: "Sales Report - ${REGION}"
  pageLayout: split-vertical
  children:
    - kind: Text
      spec:
        value: "Region: ${REGION} | Year: ${YEAR}"
    - kind: Table
      spec:
        dataset: regional-sales-data

---
# Use it multiple times (in report.yaml)
apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: all-regions-report
spec:
  format: xga
  orientation: landscape
  layoutPages:
    - page: regional-sales
      params:
        REGION: EU
        YEAR: "2024"
    - page: regional-sales
      params:
        REGION: US
        YEAR: "2024"
    - page: regional-sales
      params:
        REGION: APAC
        YEAR: "2024"
  filename: all-regions-2024.pdf
  title: "2024 Sales by Region"

This generates a single PDF with three pages, each showing sales data for a different region.

Example: Time comparison report

---
apiVersion: bino.bi/v1alpha1
kind: LayoutPage
metadata:
  name: quarterly-summary
  params:
    - name: QUARTER
      type: string
      required: true
    - name: START_DATE
      type: date
      required: true
    - name: END_DATE
      type: date
      required: true
spec:
  titleBusinessUnit: "${QUARTER} Summary"
  children:
    - kind: Text
      spec:
        value: "${QUARTER}: ${START_DATE} to ${END_DATE}"
    - kind: ChartStructure
      spec:
        dataset: quarterly-data

---
apiVersion: bino.bi/v1alpha1
kind: ReportArtefact
metadata:
  name: year-in-review
spec:
  layoutPages:
    - page: quarterly-summary
      params:
        QUARTER: "Q1 2024"
        START_DATE: "2024-01-01"
        END_DATE: "2024-03-31"
    - page: quarterly-summary
      params:
        QUARTER: "Q2 2024"
        START_DATE: "2024-04-01"
        END_DATE: "2024-06-30"
    - page: quarterly-summary
      params:
        QUARTER: "Q3 2024"
        START_DATE: "2024-07-01"
        END_DATE: "2024-09-30"
    - page: quarterly-summary
      params:
        QUARTER: "Q4 2024"
        START_DATE: "2024-10-01"
        END_DATE: "2024-12-31"
  filename: year-in-review-2024.pdf
  title: "2024 Year in Review"

For complete documentation on defining parameters in LayoutPages, see LayoutPage Parameters.

Attribute Reference

Common Metadata

Attribute	Type	Required	Default	Description
apiVersion	string	yes	—	Must be bino.bi/v1alpha1.
kind	string	yes	—	Must be ReportArtefact.
metadata.name	string	yes	—	Unique identifier.
metadata.labels	object	no	—	Key-value pairs for categorization and constraint matching.
metadata.annotations	object	no	—	Arbitrary key-value metadata, not used by the system.
metadata.description	string	no	—	Free-form description.
metadata.constraints	array	no	—	Conditional inclusion rules. See Constraints.

Spec Attributes

Attribute	Type	Required	Default	Description	Sample
spec.filename	string	yes	—	Output filename of the generated artefact, relative to the output directory.	filename: sales-report.pdf
spec.title	string	yes	—	Human-readable title of the artefact. Also stored in the PDF metadata.	title: "Sales Overview"
spec.format	string	no	xga	Logical page size, for example xga, a4, letter. Lowercase letters, digits, _ and - only.	format: a4
spec.orientation	string	no	landscape	Page orientation. Values: portrait, landscape.	orientation: portrait
spec.language	string	no	de	Language code passed to the renderer. Values: de, en.	language: en
spec.layoutPages	string or array	no	["*"] (every LayoutPage in the bundle)	LayoutPage selection. A single pattern as a plain string, or a non-empty array of references. Pages appear in pattern order; within each pattern, pages are sorted alphabetically. See Page selection.	layoutPages: [cover, "sales-*"]
spec.layoutPages[]	string or object	—	—	One reference: a name or glob pattern (*, ?, [abc]), or the object form below.	- sales-*
spec.layoutPages[].page	string	yes (in object form)	—	Name of the LayoutPage. Must be an exact name, not a glob pattern.	page: regional-sales
spec.layoutPages[].params	object	no	—	Parameter values passed to the LayoutPage; keys must match its metadata.params, all values are strings. See Parameterized LayoutPages.	params: { REGION: EU }
spec.description	string	no	—	Short description of the artefact contents, used in logs and metadata.	description: "Quarterly sales overview for the group."
spec.subject	string	no	—	Subject line stored in the PDF metadata.	subject: "Sales report"
spec.author	string	no	—	Author or owning team name stored in the PDF metadata.	author: "Group Controlling"
spec.keywords	array of strings	no	—	Keywords stored in the PDF metadata to help search and classification. Entries must be unique.	keywords: ["sales", "quarterly", "internal"]
spec.keywords[]	string	—	—	A single keyword.	sales
spec.signingProfile	string	no	—	Name of a SigningProfile manifest used to digitally sign the PDF. If omitted, the artefact is not signed.	signingProfile: corporateSigner
spec.selectedStyle	string	no	—	Name of a ComponentStyle manifest applied as the default style for every page and component in this artefact; a nearer ancestor wins. Maps to the selected-style HTML attribute.	selectedStyle: corporateTheme
spec.i18nNamespace	string	no	—	I18n namespace inherited as the default by every page and component in this artefact; a nearer ancestor wins.	i18nNamespace: audited