ChartScatter

ChartScatter manifests describe XY scattergrams: two numeric value axes, one point per data row, points colored by series, selective collision-free labels, optional highlight bands, and hyperbolic iso-lines x·y = k for a third derived measure.

Minimal definition

The smallest well-formed ChartScatter sets the required dataset, x and y plus the fields a readable scattergram needs: an axis label and unit on both axes (values are drawn as delivered, so the unit is the only magnitude cue) and a chartTitle carrying the message.

apiVersion: bino.bi/v1alpha1
kind: ChartScatter
metadata:
  name: product_portfolio
spec:
  dataset: products
  chartTitle: "Product portfolio"
  x:
    measure: ac1
    label: "Margin"
    unit: "% of net sales"
  y:
    measure: ac2
    label: "Net sales"
    unit: "mUSD"

All attributes are listed in the Attribute Reference below.

Both axis mappings also accept the short form x: ac1 instead of the object shown above - see Measure tokens.

Measure tokens

The x and y mappings accept either a bare measure token or an object whose measure property is a token:

• Scenario slots: ac1-ac4, pp1-pp4, fc1-fc4, pl1-pl4 - the row columns of the dataset.
• Variance tokens: d<base>_<delta> (absolute) or dr<base>_<delta> (relative), e.g. dac1_pp1 (AC minus PY) or drac1_pl1 (AC vs. plan in percent). An optional _pos/_neg/_neu sentiment suffix is accepted and ignored on axes.

An axis with a relative variance (a dr token such as drac1_pp1) is a percent axis. Its ticks print percent (20%), and min, max, refLine, highlight.from and highlight.to of that axis are read in percent: write min: -40, not min: -0.4. The ticks already carry the percent sign, so such an axis needs no unit: "%".

All plain scenario measures across x and y must share one scenario family (e.g. don’t mix ac1 with pp2); the family selects the mark treatment through the rule set. Variance tokens don’t count toward the family.

A bare string is shorthand for the object form: x: ac1 equals x: { measure: ac1 }.

Data mapping

One dataset row is one point - aggregate in the DataSet SQL; duplicate point identities keep the first row and raise a warning. Values are drawn as delivered (no auto-SI scaling).

• level picks the hierarchy column that identifies a point (auto uses the deepest populated level of rowGroup → category → subCategory).
• seriesLevel picks the level whose values become the color series; it must be strictly above the point level. none renders a single series.
• facet splits the plot into small-multiple panels on a level above the series level.

Iso-lines require a strictly positive domain on both axes.

Fields

• dataset - required dataset name, inline definition, or array of either.
• x, y - required axis measure mappings (token or object with measure, label, unit, min, max, refLine, and highlight with from/to; an open end runs to the domain edge).
• iso - optional iso-line configuration (values, label, unit, highlight.from shades the region where x·y >= from).
• level, seriesLevel - point identity and series grouping levels.
• facet - small-multiple configuration (level required, columns).
• labels - point labels: points is auto (up to max collision-free candidates), all, none, or an explicit list of point names; values adds the measure value. Defaults: points: auto, values: false, max: 12.
• legend - series legend (show defaults to true, position to right).
• aspect - plot aspect ratio "w:h" (default 16:9); XY charts have no data-driven height.
• limit - max points per facet panel, keeping the first rows in dataset order; 0 means unlimited.
• filter - optional AlaSQL WHERE fragment.
• chartTitle - optional title.
• scale - proportional font scaling, same semantics as the other charts (none, auto, or a fixed factor).
• selectedStyle - optional name of a ComponentStyle to apply; merged over the _system and _default styles.
• ruleset - optional name of a RuleSet to apply, or inherited-closest / inherited-page to inherit the surrounding layout’s rule set.

Example: Basic scattergram

---
apiVersion: bino.bi/v1alpha1
kind: ChartScatter
metadata:
  name: product_portfolio
spec:
  dataset: products
  chartTitle: "Product portfolio"
  x:
    measure: ac1
    label: "Margin"
    unit: "% of net sales"
    min: 0
    max: 40
  y:
    measure: ac2
    label: "Net sales"
    unit: "mUSD"
    highlight: { from: 30 }
  labels:
    points: auto
    max: 12

Example: Iso-lines with highlight

---
apiVersion: bino.bi/v1alpha1
kind: ChartScatter
metadata:
  name: gross_profit_scatter
spec:
  dataset: products
  x: { measure: ac1, label: "Margin", unit: "%", min: 0, max: 40 }
  y: { measure: ac2, label: "Net sales", unit: "mUSD", min: 0 }
  iso:
    values: [100, 200, 300]
    label: "Gross profit"
    unit: "mUSD"
    highlight: { from: 300 }

Example: Variance scatter with small multiples

---
apiVersion: bino.bi/v1alpha1
kind: ChartScatter
metadata:
  name: growth_vs_plan
spec:
  dataset: business_units
  x: { measure: drac1_pp1, label: "Growth", refLine: 0 }
  y: { measure: drac1_pl1, label: "Plan deviation", refLine: 0 }
  level: subcategory
  seriesLevel: category
  facet:
    level: rowgroup
    columns: 4

Attribute Reference

Common Metadata

Attribute	Type	Required	Default	Description
apiVersion	string	yes	-	Must be bino.bi/v1alpha1.
kind	string	yes	-	Must be ChartScatter.
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.dataset	string, object, or array	yes	-	Dataset reference: a name, an inline DataSet definition, or an array of either.	dataset: products
spec.x	string or object	yes	-	Horizontal axis measure mapping: a bare measure token or the object below. All plain scenario measures across x and y must share one scenario family. Maps to the x HTML attribute.	x: ac1
spec.x.measure	string	yes (object form)	-	Scenario slot (ac1-ac4, pp1-pp4, fc1-fc4, pl1-pl4) or a variance token (dac1_pp1, drac1_pl1). A dr token makes this a percent axis.	measure: ac1
spec.x.label	string	no	-	Axis title displayed next to the axis.	label: "Margin"
spec.x.unit	string	no	-	Unit suffix after the axis title. Values are drawn as delivered - scale in the DataSet SQL.	unit: "% of net sales"
spec.x.min	number	no	data minimum	Lower axis domain bound. Points outside an explicit domain are clipped with a warning.	min: 0
spec.x.max	number	no	data maximum	Upper axis domain bound. Must be greater than min or both overrides are dropped.	max: 40
spec.x.refLine	number	no	-	Draws a reference line perpendicular to this axis at the given value.	refLine: 20
spec.x.highlight	object	no	-	Shades a band of the plot along this axis.	highlight: { from: 30 }
spec.x.highlight.from	number	no	domain start	Band start value.	from: 30
spec.x.highlight.to	number	no	domain end	Band end value.	to: 40
spec.y	string or object	yes	-	Vertical axis measure mapping, same shape as spec.x. Maps to the y HTML attribute.	y: { measure: ac2, unit: "mEUR" }
spec.y.measure	string	yes (object form)	-	Scenario slot or variance token for the vertical axis. A dr token makes this a percent axis.	measure: ac2
spec.y.label	string	no	-	Axis title displayed next to the axis.	label: "Net sales"
spec.y.unit	string	no	-	Unit suffix after the axis title. Values are drawn as delivered - scale in the DataSet SQL.	unit: "mUSD"
spec.y.min	number	no	data minimum	Lower axis domain bound. Points outside an explicit domain are clipped with a warning.	min: 0
spec.y.max	number	no	data maximum	Upper axis domain bound. Must be greater than min or both overrides are dropped.	max: 100
spec.y.refLine	number	no	-	Draws a reference line perpendicular to this axis at the given value.	refLine: 20
spec.y.highlight	object	no	-	Shades a band of the plot along this axis.	highlight: { from: 30 }
spec.y.highlight.from	number	no	domain start	Band start value.	from: 30
spec.y.highlight.to	number	no	domain end	Band end value.	to: 60
spec.iso	object	no	-	Hyperbolic iso-lines x·y = k. Requires a strictly positive domain on both axes. Maps to the iso HTML attribute.	iso: { values: [100, 200] }
spec.iso.values	string or array of numbers	no	-	Iso-line constants: auto derives them from the data, or list explicit k values.	values: [100, 200, 300]
spec.iso.label	string	no	-	Caption of the derived measure, rendered at the iso-line exits.	label: "Gross profit"
spec.iso.unit	string	no	-	Unit suffix for the iso-line caption.	unit: "mUSD"
spec.iso.highlight	object	no	-	Shades the region where x·y >= from.	highlight: { from: 300 }
spec.iso.highlight.from	number	no	-	Iso value the shading starts at.	from: 300
spec.level	string	no	auto	Point identity level (one row = one point, duplicates are dropped with a warning). Values: auto, category, subcategory.	level: category
spec.seriesLevel	string	no	auto	Series/color level, strictly above the point level. Values: auto, rowgroup, category, none. Maps to the series-level HTML attribute.	seriesLevel: rowgroup
spec.facet	object	no	-	Small-multiple panels on a hierarchy level above the series level.	facet: { level: rowgroup }
spec.facet.level	string	yes (when facet is set)	-	Hierarchy level whose values become the facet panels. Values: rowgroup, category.	level: rowgroup
spec.facet.columns	integer	no	all panels in one row	Number of panels per row (≥ 1).	columns: 3
spec.labels	object	no	points: auto, values: false, max: 12	Point label configuration.	labels: { points: all }
spec.labels.points	string or array of strings	no	auto	Which points get a name label: auto picks up to max collision-free candidates, all labels every point, none disables labels, or list explicit point names.	points: none
spec.labels.values	boolean	no	false	Render the measure value with the label.	values: true
spec.labels.max	integer	no	12	Candidate cap when points is auto (≥ 1).	max: 8
spec.legend	object	no	show: true, position: right	Series legend configuration.	legend: { position: bottom }
spec.legend.show	boolean	no	true	Toggles the legend.	show: false
spec.legend.position	string	no	right	Legend placement. Values: right, bottom.	position: bottom
spec.aspect	string	no	16:9	Plot aspect ratio "w:h". XY charts have no data-driven height.	aspect: "21:9"
spec.limit	integer	no	0	Max points per facet panel (first rows in dataset order). 0 means unlimited.	limit: 50
spec.filter	string	no	""	AlaSQL WHERE clause fragment to filter rows.	filter: "category = 'New SBUs'"
spec.chartTitle	string	no	""	Custom chart title. Maps to the chart-title HTML attribute.	chartTitle: "Margin vs. net sales"
spec.scale	string or number	no	auto-scale with warning	Proportional scaling. "none": no scaling. "auto": auto-scale silently. Positive number: fixed factor.	scale: auto
spec.i18nNamespace	string	no	-	I18n namespace for this component’s labels; missing keys fall back to _system. Resolved at runtime from the nearest ancestor carrying one (card, page, tree, grid, or the artefact) when not set. Maps to the i18n-namespace HTML attribute.	i18nNamespace: sales
spec.selectedStyle	string	no	-	Name of a ComponentStyle manifest to apply. Maps to the selected-style HTML attribute.	selectedStyle: corporate-style
spec.ruleset	string	no	-	Name of a RuleSet manifest to apply, or inherited-closest / inherited-page. Maps to the ruleset HTML attribute.	ruleset: corporate-rules

See ChartBubble for the XY portfolio variant with a third size measure.