Lint rules

This appendix lists all lint rules that bino lint and bino build apply to your report manifests. Lint rules check the content of your documents (semantic/business rules), while schema validation checks the structure.

Most lint findings are treated as warnings and do not block builds. However, some rules produce errors that will cause the build to fail (marked with severity below).

Rules

ID	Name	Severity	Description
report-artefact-required	Report Artefact Required	Warning	At least one ReportArtefact document must be defined.
artefact-layoutpage-required	Artefact LayoutPage Required	Warning	Each ReportArtefact must have at least one LayoutPage that matches its constraints and format.
text-content-required	Text Content Required	Warning	Text components must have a non-empty spec.value field.
dataset-required	Dataset Required	Warning	Table, ChartStructure, and ChartTime components must have a spec.dataset binding.
missing-required-reference	Missing Required Reference	Error	Required child references (ref) must point to existing documents.
page-layout-slots-used	Page Layout Slots Used	Warning	LayoutPage children count must match the expected slots for its pageLayout.
card-layout-slots-used	Card Layout Slots Used	Warning	LayoutCard children count must match the expected slots for its cardLayout.
inline-ref-bounds	Inline Reference Bounds	Warning	@inline(N) references must have valid indices within the dependencies array.
dataset-source-exclusive	DataSet Source Exclusive	Warning	The source field is mutually exclusive with query and prql in DataSet specs.
inline-naming-conflict	Inline Naming Conflict	Warning	Document names must not start with _inline_ as this prefix is reserved.

Rule details

report-artefact-required

Every bino report project needs at least one ReportArtefact document to define what PDF(s) to generate.

Example fix: Add a ReportArtefact manifest to your project:

apiVersion: bino.bi/v1
kind: ReportArtefact
metadata:
  name: my-report
spec:
  title: Monthly Sales Report

artefact-layoutpage-required

Each ReportArtefact must have at least one LayoutPage that:

1. Passes constraints — The page’s metadata.constraints must match the artefact’s context (labels, spec, or mode). The linter checks both build and preview modes; a page is valid if it matches in either mode.
2. Matches format — The page’s spec.pageFormat must match the artefact’s spec.format. Both default to xga if not specified.

Example problem:

# Artefact with format: a4
kind: ReportArtefact
metadata:
  name: print-report
spec:
  format: a4
---
# Page with default format (xga) won't match!
kind: LayoutPage
metadata:
  name: page1
spec:
  children: [...]

Fix: Set spec.pageFormat: a4 on the LayoutPage.

text-content-required

Text components are meant to display content. An empty spec.value produces blank output.

Example problem:

kind: Text
metadata:
  name: header
spec:
  value: "" # Empty!

Fix: Provide meaningful content in spec.value.

dataset-required

Data visualization components (Table, ChartStructure, ChartTime) need a dataset to display. Without spec.dataset, there’s nothing to render.

Example problem:

kind: Table
metadata:
  name: sales-table
spec:
  tableTitle: Sales Overview
  # Missing dataset!

Fix: Add a dataset reference:

spec:
  dataset: sales-data

Or multiple datasets for charts:

spec:
  dataset:
    - revenue
    - costs

missing-required-reference

Child references (ref) in LayoutPage and LayoutCard must point to documents that exist. This rule catches typos, missing files, and broken references early.

Severity: Error (blocks build)

Example problem:

kind: LayoutPage
metadata:
  name: dashboard
spec:
  pageLayout: 2x2
  children:
    - kind: ChartTime
      ref: revnue_chart  # Typo! Should be "revenue_chart"

Error message:

required reference "revnue_chart" of kind "ChartTime" not found (use optional: true to allow missing refs)

Fixes:

1. Correct the typo — Fix the reference name to match the target document’s metadata.name.

2. Create the missing document — Add the referenced manifest to your project.

3. Mark as optional — If the reference is legitimately optional (e.g., debug-only component), add optional: true:

children:
  - kind: ChartTime
    ref: debug_chart
    optional: true  # Won't error if missing

Note: References that exist but are filtered out by constraints (e.g., mode == "preview") do not trigger this error. Only genuinely missing references cause failures.

See also: Optional references

page-layout-slots-used

Each LayoutPage must have exactly the number of children that match its pageLayout slot count. This rule is evaluated per artefact, counting only children that:

1. Pass constraints — Children with metadata.constraints must match the artefact’s context.
2. Have valid refs — Children with ref must point to an existing document (or be marked optional: true). Missing required refs trigger the missing-required-reference error. Optional refs that are missing don’t count as slots.
3. Are renderable — Children must have either a ref or inline spec.

Slot counts for predefined layouts:

Layout	Slots
full	1
split-horizontal	2
split-vertical	2
2x2	4
3x3	9
4x4	16
1-over-2	3
1-over-3	4
2-over-1	3
3-over-1	4

For custom-template, the slot count is the number of distinct named area tokens in pageCustomTemplate:

# 3 slots: a, b, c
pageLayout: custom-template
pageCustomTemplate: |
  "a a"
  "b c"

# 2 slots: aa, bb
pageLayout: custom-template
pageCustomTemplate: |
  "aa aa"
  "bb bb"

Example problem:

kind: LayoutPage
metadata:
  name: dashboard
spec:
  pageLayout: 2x2 # Expects 4 children
  children:
    - kind: Text
      spec: { value: "Hello" }
    - kind: Table
      ref: sales-table
    # Only 2 children, but 2x2 expects 4!

Fix: Add children to fill all slots, or change pageLayout to match actual children count.

card-layout-slots-used

Same as page-layout-slots-used, but for LayoutCard components. Each card’s cardLayout defines how many children it expects.

Example problem:

kind: LayoutCard
metadata:
  name: summary-card
spec:
  cardLayout: split-horizontal # Expects 2 children
  children:
    - kind: Text
      spec: { value: "Only one child" }

Fix: Add a second child or change cardLayout: full.

inline-ref-bounds

When using inline DataSource definitions in a DataSet’s dependencies, the @inline(N) references in queries must point to valid indices.

Example problem:

kind: DataSet
metadata:
  name: my_dataset
spec:
  dependencies:
    - type: csv
      path: ./data/sales.csv
  query: |
    SELECT * FROM @inline(5)  # Index 5 doesn't exist!

Error message:

@inline(5) out of bounds (have 1 inline dependencies)

Fix: Use @inline(0) to reference the first (and only) inline dependency.

See also: Inline DataSet definitions

dataset-source-exclusive

The source field in DataSet provides direct pass-through to a DataSource without transformation. It cannot be used together with query or prql.

Example problem:

kind: DataSet
metadata:
  name: conflicting_dataset
spec:
  source: sales_csv
  query: |  # Can't have both source and query!
    SELECT * FROM sales_csv

Fix: Choose one approach:

# Option 1: Use source for pass-through
spec:
  source: sales_csv

# Option 2: Use query for transformation
spec:
  query: SELECT * FROM sales_csv
  dependencies:
    - sales_csv

See also: Direct source pass-through

inline-naming-conflict

Document names starting with _inline_ are reserved for generated inline definitions. User-defined documents must not use this prefix.

Example problem:

kind: DataSource
metadata:
  name: _inline_my_data  # Reserved prefix!
spec:
  type: csv
  path: ./data.csv

Fix: Choose a different name that doesn’t start with _inline_:

metadata:
  name: my_data

Adding custom rules

The bino linter is designed for easy rule addition. Each rule has:

• ID: A unique identifier (e.g., naming-lowercase, reference-undefined-dataset).
• Name: A short human-readable name.
• Description: An explanation of what the rule checks.
• Check function: The logic that inspects documents and returns findings.

Rules are registered in internal/report/lint/rules.go.

Suppressing warnings

Currently, lint warnings cannot be suppressed. Future versions may add per-rule or per-file suppression.

See also

• bino lint – CLI command for running lint.
• bino build – build command (runs lint by default).