A chart in an ODT file is a separate small document stored in the package, shown in
the text through a frame (see frames,
images and objects). The chart document has its own content.xml whose
body is office:chart, and that holds one chart:chart. This page
covers chapter 11 of OpenDocument 1.3 part 3 and the chart: attributes of
chapter 19. How a chart looks (colours, labels, tick marks, symbols, 3D) is set by
chart styles; those properties are on the
chart formatting
page.
The chart document
office:chart is the body of a chart document. It has no attributes.
Its children are chart:chart and, because a chart can get its data from
a table of its own, the table-related elements a spreadsheet also uses:
table:calculation-settings, table:consolidation,
table:content-validations, table:data-pilot-tables,
table:database-ranges, table:dde-links,
table:label-ranges, table:named-expressions,
text:alphabetical-index-auto-mark-file,
text:dde-connection-decls, text:sequence-decls,
text:user-field-decls and text:variable-decls.
chart:chart is the chart itself. Attributes: chart:class,
chart:style-name, svg:width, svg:height,
xlink:href, xlink:type, xml:id and the
deprecated chart:column-mapping and chart:row-mapping.
Children: chart:title, chart:subtitle,
chart:footer, chart:legend, chart:plot-area,
a table:table holding the chart’s own data, and any drawing shapes
(draw:a, draw:caption, draw:circle,
draw:connector, draw:control,
draw:custom-shape, draw:ellipse, draw:frame,
draw:g, draw:line, draw:measure,
draw:page-thumbnail, draw:path, draw:polygon,
draw:polyline, draw:rect,
draw:regular-polygon, dr3d:scene).
Chart elements
| Element | Inside | Meaning | Attributes | Children |
|---|---|---|---|---|
chart:title | chart:chart, chart:axis | A title. Its text is a child text:p or comes from table:cell-range; if both are present the cell range wins. Inside an axis it is shown beside that axis. | chart:style-name, svg:x, svg:y, table:cell-range | text:p |
chart:subtitle | chart:chart | A subtitle; same text rules as the title. | same four | text:p |
chart:footer | chart:chart | A footer below the plot area; same text rules. | same four | text:p |
chart:legend | chart:chart | The legend. With no element there is no legend. An optional text:p is the legend’s title. | chart:legend-align, chart:legend-position, chart:style-name, style:legend-expansion, style:legend-expansion-aspect-ratio, svg:x, svg:y, svg:width, svg:height | text:p |
chart:plot-area | chart:chart | A coordinate system in which data is plotted, with its axes. May be drawn as a 3D scene. | chart:style-name, chart:data-source-has-labels (deprecated), table:cell-range-address (deprecated), svg:x, svg:y, svg:width, svg:height, xml:id, and the 3D scene attributes dr3d:ambient-color, dr3d:distance, dr3d:focal-length, dr3d:lighting-mode, dr3d:projection, dr3d:shade-mode, dr3d:shadow-slant, dr3d:transform, dr3d:vpn, dr3d:vrp, dr3d:vup | chart:axis, chart:coordinate-region, chart:floor, chart:series, chart:stock-gain-marker, chart:stock-loss-marker, chart:stock-range-line, chart:wall, dr3d:light |
chart:coordinate-region | chart:plot-area | A positioning rectangle for the coordinate system, used instead of the plot area’s own position and size. | svg:x, svg:y, svg:width, svg:height | none |
chart:wall | chart:plot-area | The wall. In 2D it spans the plot area; in 3D it is two perpendicular rectangles and svg:width is their thickness. | chart:style-name, svg:width | none |
chart:floor | chart:plot-area | The floor. In 3D charts it must be present as well as the wall; svg:width is its thickness. | chart:style-name, svg:width | none |
chart:axis | chart:plot-area | An axis. | chart:dimension, chart:name, chart:style-name | chart:categories, chart:grid, chart:title |
chart:categories | chart:axis | Labels shown on a category axis. If the element or its attribute is missing, chart:data-source-has-labels on the plot area is used. | table:cell-range-address | none |
chart:grid | chart:axis | A grid for the axis. | chart:class, chart:style-name | none |
chart:series | chart:plot-area | One data series. Scatter and bubble charts need chart:domain children for the extra data. | chart:attached-axis, chart:class, chart:label-cell-address, chart:style-name, chart:values-cell-range-address, xml:id | chart:data-label, chart:data-point, chart:domain, chart:error-indicator, chart:mean-value, chart:regression-curve |
chart:domain | chart:series | Extra coordinate values for some chart types (see Domains). | table:cell-range-address | none |
chart:data-point | chart:series | A style for one data point, or for a run of points with the same style, typically a point with a distinct appearance. | chart:repeated, chart:style-name, xml:id | chart:data-label |
chart:data-label | chart:data-point, chart:series | The label of a data point. In a series it is the default for all its points. | chart:style-name, svg:x, svg:y | text:p |
chart:mean-value | chart:series | The style of the mean-value line. | chart:style-name | none |
chart:error-indicator | chart:series | The style of error indicators, for the given dimension. | chart:dimension, chart:style-name | none |
chart:regression-curve | chart:series | A regression curve and its properties. | chart:style-name | chart:equation |
chart:equation | chart:regression-curve | The equation shown for a regression curve. | chart:automatic-content, chart:display-equation, chart:display-r-square, chart:style-name, svg:x, svg:y | text:p |
chart:stock-gain-marker | chart:plot-area | Style of candlestick bars in a stock chart whose closing value is higher than the opening value. | chart:style-name | none |
chart:stock-loss-marker | chart:plot-area | Style of candlestick bars whose closing value is lower than the opening value. | chart:style-name | none |
chart:stock-range-line | chart:plot-area | Style of the line joining the minimum and maximum value in a stock chart. | chart:style-name | none |
chart:style-name names a chart style (a style:style of family
chart) and can be set on every element above except
chart:categories, chart:coordinate-region and
chart:domain. chart:plot-area may also hold
dr3d:light elements, as a dr3d:scene does.
Position, size and the plot area
svg:x, svg:y, svg:width and
svg:height on the plot area form a positioning rectangle. If a
chart:coordinate-region is present, its values are used instead. If the
chart style of the plot area has chart:auto-position and
chart:auto-size both true, every positioning attribute, including those
on the coordinate region, is ignored.
For a chart with a 2D Cartesian system, the intervals in use on the axes span a
rectangle, the coordinate region; axis labels, tick marks, axis titles and data labels
are not counted. The system is scaled so the region matches the rectangle. For the
classes chart:radar, chart:filled-radar,
chart:circle and chart:ring there is no Cartesian system:
the smallest bounding circle (ignoring labels, tick marks and titles) is used, its
bounding box is the region, and the circle is scaled uniformly to the largest size
that fits, centred in the rectangle. A chart:pie-offset on a single data
point does not enlarge the region (a pulled-out segment may stick out); on a series it
does. Producers should give a square rectangle for those classes. The behaviour for
3D charts follows the 3D scene rules: scaling is uniform and the projection is
centred in the rectangle; for 3D circle and ring charts the extruded bounding box is
used, for 3D Cartesian charts the cuboid generated by the axis intervals. Other cases
are implementation-defined.
Chart classes
chart:class names the chart type. Its value is a namespaced token; the
predefined types are in the chart namespace
(urn:oasis:names:tc:opendocument:xmlns:chart:1.0), and other types may
use another namespace. A chart:class on a chart:series
overrides the one on the whole chart. Below, “line attributes” are
draw:stroke, draw:stroke-dash,
draw:stroke-linejoin, svg:stroke-color,
svg:stroke-width and svg:stroke-opacity of the chart style;
“fill attributes” are draw:fill, draw:fill-color,
draw:fill-gradient-name, draw:gradient-step-count,
draw:fill-hatch-name, draw:fill-hatch-solid,
draw:fill-image-height, draw:fill-image-name,
draw:fill-image-width, draw:fill-image-ref-point (and
-x, -y), draw:opacity,
draw:opacity-name, draw:tile-repeat-offset and
style:repeat.
| Value | How the series values are read |
|---|---|
chart:area | y-values in a Cartesian system; x-values are the positions 1, 2, 3 … in the sequence; chart:categories labels the x-axis. The area between the points and the x-axis (see chart:origin) is filled; with chart:stacked it is the area between a series and the previous one. 3D (chart:three-dimensional) uses a left-handed system, and with chart:deep the z-values are the series order, labelled with the series names. |
chart:bar | y-values as for area. A bar is drawn per data point from the x-axis (or from the previous series when stacked) to the y-value. Width and position are affected by chart:gap-width, chart:group-bars-per-axis, chart:overlap, chart:percentage and chart:stacked. In 3D the shape comes from chart:solid-type. chart:vertical swaps the axes (horizontal bars). |
chart:bubble | Circles of different sizes; the series values are the relative bubble areas. The first chart:domain gives the y-coordinates, the second the x-coordinates. |
chart:circle | A pie chart; only one series is shown. Each value’s sector angle is its relative weight. Sectors run counter-clockwise from 12 o’clock; chart:reverse-direction on the y-axis makes them clockwise; chart:angle-offset rotates the pie. Categories come from the x-axis. |
chart:filled-radar | Radius values in a counter-clockwise polar system starting at 12 o’clock. The y-axis is the radius axis, the x-axis the angle axis; x-values are the positions 1, 2, 3 …. The area enclosed by the points is filled (or the area between series when stacked). |
chart:gantt | Two series of this class give the start and end values, in this order, on the y-axis. For each x position a bar runs from start to end. If end is not smaller than start the first series’ style is used, otherwise the second’s. |
chart:line | y-values as for area. In 2D the points are joined by a line (solid by default), with symbols if chart:symbol-type says so, filled with the line colour by default; if no line colour is given but a fill colour is, the line uses the fill colour. In 3D no symbols are shown and the line is extruded in z. chart:interpolation on the plot area chooses how points are joined. |
chart:radar | As filled radar, but the points are joined by a line and may have symbols. |
chart:ring | Each series is one ring of a doughnut chart, divided like a pie. Direction and angle as for circle. By default the first series is the innermost ring; chart:reverse-direction on the x-axis reverses that. chart:hole-size sets the inner hole. |
chart:scatter | y-values; the x-values come from the first chart:domain. Lines and symbols as for line; 3D as for line. |
chart:stock | Up to four series: opening, minimum, maximum, closing, in this order; with three series, minimum, maximum, closing. For each x the minimum and maximum are joined by a line (chart:stock-range-line). With chart:japanese-candle-stick false (the default) opening and closing are tick lines left and right; with true a bar is drawn from opening to closing, styled by chart:stock-gain-marker or chart:stock-loss-marker. |
chart:surface | Two forms, depending on the first series’ range. A range with more than one row and column: the value in column i, row j is the altitude at x=i, y=j (or the values from two chart:domain elements); 3D uses a right-handed system with the altitude on the z-axis; 2D draws a contour plot with a z-axis element (chart:dimension="z") giving the range and major interval. A range with one row or column: several series are read as altitudes at grid positions; 3D is left-handed with altitude on y and chart:deep true; 2D is a contour plot with the series order on the y-axis. chart:data-point elements give different fills and lines to different altitude intervals; the legend shows each interval. |
The specification’s own table of example images (a line, area, circle, ring, scatter, radar, bar, stock, bubble, surface and gantt chart built from the data 1;2;3;4 and 1;4;9;16 with the labels a;b;c;d) is not reproduced here.
On a chart:grid, chart:class instead takes
major (the default: major tick marks extend to grid lines) or
minor (minor tick marks do).
Domains and data ranges
- Series values:
chart:values-cell-range-addressis the cell range list holding the values;chart:label-cell-addressthe range holding the series name. The data can live in the chart’s owntable:tableor in the container document. - Scatter: exactly one
chart:domain, its range the x-values. - Bubble: two
chart:domainelements; the first gives the y-coordinates, the second the x-coordinates. - Surface: up to two; the first gives y, the second x (for the multi-row, multi-column form, the jth value of the first applies to row j, the ith of the second to column i).
- At least one series of a given class must carry the needed domains; other series of the same class may leave them out and reuse the earlier ones.
- Categories:
table:cell-range-addressonchart:categories. - Titles:
table:cell-range(title, subtitle, footer). - Deprecated:
table:cell-range-addresson the plot area gives the whole data range; it has no effect where series carry their ownchart:values-cell-range-address.
Chart attributes
| Attribute | On | Values and meaning |
|---|---|---|
chart:attached-axis | chart:series | String: the chart:name of the axis the series uses. |
chart:automatic-content | chart:equation | Boolean, default true. true: the equation is calculated and shown; false: the text in text:p is shown. With no text:p it is taken as true. |
chart:class | chart:chart, chart:series, chart:grid | Namespaced token; see Chart classes. On a grid: major or minor. |
chart:column-mapping (deprecated) | chart:chart | String: list of series indexes (from 1) that reorders data coming from a container document; ascending 1, 2, 3 … does nothing; to swap two series, swap their numbers. Not to be used with chart:row-mapping. Reorder the chart:series elements instead. |
chart:row-mapping (deprecated) | chart:chart | The same, for rows. |
chart:data-source-has-labels (deprecated) | chart:plot-area | none (default), row, column or both: whether the first row, the first column, both or neither of the source range hold labels. |
chart:dimension | chart:axis, chart:error-indicator | x, y or z. Charts with fewer than three axes use x and y only. |
chart:display-equation | chart:equation | Boolean, default true; read only when chart:automatic-content is true. |
chart:display-r-square | chart:equation | Boolean, default false; read only when chart:automatic-content is true. |
chart:label-cell-address | chart:series | Cell range list holding the series name. |
chart:legend-align | chart:legend | start (left or top), center, end (right or bottom) of the plot area. Used when the position is start, end, top or bottom. |
chart:legend-position | chart:legend | Next to the plot area: top, bottom, start (left), end (right). In a corner outside it: top-start, top-end, bottom-start, bottom-end. Absolute svg:x/svg:y may also be given; if both are present this attribute wins. |
chart:name | chart:axis | String name of an axis, used by chart:attached-axis. |
chart:repeated | chart:data-point | Positive integer: how many consecutive points share the style. |
chart:style-name | see above | Name of a chart style. |
chart:values-cell-range-address | chart:series | Cell range list holding the series values. |
style:legend-expansion | chart:legend | high (grows vertically), wide (horizontally), balanced (both), custom (by style:legend-expansion-aspect-ratio). |
style:legend-expansion-aspect-ratio | chart:legend | Double: width to height ratio for custom. |
table:cell-range | title, subtitle, footer | Cell range list the text is taken from. |
table:cell-range-address | categories, domain, plot area | Cell range list; see Domains. |
The legend shows one entry per series (a key plus the series name), with extra entries for regression curves and mean-value lines. For circle and ring charts each entry is a data point of the first series, labelled with its category; for surface charts each entry is an altitude interval and its value range.
Source
OpenDocument Version 1.3, OASIS Standard, 27 April 2021, part 3 (schema), section 3.8
(office:chart), chapter 11 (chart content), and the chart:,
table:cell-range and style:legend-expansion attributes in
chapter 19; read in full for this page. Not reproduced: the example pictures of
19.15.1.