# User documentation

This page provides some basic user documentation for the templates generated by the tool.

## How to use the template

1. Start by entering data in the first row in the main worksheet and then complete any other [worksheets](#worksheets) that are relevant to your dataset.
1. Use the [field information](#field-information) to understand what data to enter into each column and how to format it.
1. Use [identifiers](#identifiers) to relate data entered across multiple worksheets.
1. Make sure that you complete all of the required fields for each worksheet to which you add data.

## How to customise the template

You can hide worksheets and columns that are not relevant to your datasets. However, you must ensure that you complete all of the required fields for each worksheet to which you add data.

## Frequently asked questions

### What does the '0' refer to in the field names?

It indicates that each row under that field path should be interpreted as an item in an array, e.g. under `path/to/array/0/id` the first row will be interpreted as the `id` of the first item in the `path/to/array` array and the second row will be interpreted as the `id` of the second item.

## Reference

### Worksheets

The template consists of several worksheets, reflecting the structure of the schema. The `main` worksheet represents the top-level object in the schema and the other worksheets in the template represent arrays in the schema, with rows representing items in the arrays.

### Identifiers

Identifiers are used to relate data entered across multiple worksheets, allowing the possibility of one-to-many relationships. Rows in child worksheets are related to rows in parent worksheets using the parent object’s `id` field.

### Field information

Each column in the template represents a field in the schema. The following information is provided for each field:

* `path`: A JSON pointer that identifies the field represented by the column. This information is used to convert data from spreadsheet format to JSON format. For more information, refer to the [Flatten Tool JSON pointer documentation](https://flatten-tool.readthedocs.io/en/latest/unflatten/#understanding-json-pointer-and-how-flatten-tool-uses-it).
* `title`: The title of the field.
* `description`: The description of the field. You must ensure that the data you enter into each column conforms to the field's description.
* `required`: Whether the field is required (mandatory). You must populate required fields unless no other fields in the worksheet are populated.
* `type`: The data type of the field, from the schema. The possible types are:
  * string (text)
  * number (decimal)
  * integer (whole number)
  * boolean (true/false)
  * array (list of values).
* `values`: If the field references a closed, the permitted values. If the value of the field must conform to a particular [string format](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats), the name of the format. The possible formats are:
  * date (YYYY-MM-DD)
  * email
  * iri (web address)
* `codelist`: If the field references a codelist, the name of the codelist. To view the title and description of each code, open the link.
* `input guidance`: Guidance on how to enter data in spreadsheet format.