Configuration by convention
This page details the approach that csvcubed takes to configuring cubes by convention. This makes it possible to generate a valid CSV-W cube without writing a qube-config.json at all. For an introduction to this topic, see the quick start on designing your CSV.
Minimum requirements
The configuration by conventional approach in csvcubed requires that:
- Your data set must be in the standard shape. If your data set is in the pivoted shape, you must provide a qube-config.json.
- The data CSV's column titles use conventional column names for measure columns, unit columns and observed value columns.
Adhering to the conventional column names is important since csvcubed uses those to understand what each column in your data set contains.
Inferred configuration
In order to generate a cube, csvcubed needs some additional metadata and makes a few inferences to ensure it has all of the information it needs:
- The title of the cube is the name of the CSV file in title case with underscores or dashes replaced by spaces.
- Every column which does not use a conventional name is interpreted as a dimension.
- The title of each dimension is the title case version of the column header with any underscores or dashes replaced by spaces.
- A code list is generated for each dimension column. This code list is generated from the unique values present in the data CSV column.
- Observation values are decimal values.
- New measures are created using the unique values in the measures column unless a URI is present, where that URI is assumed to point to an existing measure.
- New units are created using the unique values in the units column unless a URI is present, where that URI is assumed to point to an existing unit.
Conventional column names
The following table defines the conventional column names understood by csvcubed:
| Component type | Reserved names | Resulting configuration |
|---|---|---|
| Dimension | none | A new dimension with the label of the CSV column as its title |
| Measure Column | Measure, measures, measures column, measure column, measure type, measure types | A new measure column with the values within the measure column as new measures unless the values are URIs, when csvcubed will assume these are existing measures |
| Observation Column | Observations, obs, values, value, val, vals | A new observations column with the values in this column; the data type of this column must be numeric and is assumed to be of type xsd:decimal. |
| Unit Column | Unit, units, units column, unit column, unit type, unit types | A new unit column with the values within the unit column as new units unless the values are URIs, when csvcubed will assume these are existing units |
A valid configuration by convention cube must have a column of each component type to be valid. It is possible to override the default configuration of a conventional column by writing a column definition in a qube-config.json file.