Full-text indexing: The full string value is indexed as-is.
Data types
Every Data type in your project is declared in the Custom data definition table. Among all the settings available there, the Data type column is the most consequential: it tells the app what a column's raw cell values mean in your data sheet - how to parse them, how to render and filter them and much more.
The simplest data type is text - a plain string with an optional categorical filter. But the right type for your data can do much more: a measurement column declared as number or interval becomes range-filterable with automatic unit scaling; a distribution data column declared as mapregions renders as both an inline geographic region list and a dynamic choropleth map; a description field declared as markdown supports headings, links, and bibliography citations. Some types also shape how your spreadsheet is structured - taxon, geopoint, and media types like image can span two sub-columns to capture additional data (e.g. .name/.authority, .lat/.long). The companion value list explained in Data type reference is not a data type itself but controls how array or structured root paths join their sub-items for display.
Choosing the right data type is therefore less about formatting and more about telling the app what your data is.
text
Plain text string. No formatting.
Filter: Categorical multi-select Details pane: Text tab
When to use: Any short label or any free-form text that does not need Markdown formatting (see markdown) or category-based formatting (see category).
Filter behaviour: Shows a searchable dropdown of all unique values present in the data. Users tick one or more values.
Data entry formats
Single cell: Any string value. Leading and trailing whitespace is trimmed. Empty cells are skipped.
| specimenStateNote |
|---|
fair |
... |
frass found, schedule fumigation |
Compilation notes for
Output: Plain text value as appearing in the cell.
Usage with
column: directive- plain (
column: textColumnName) exports raw cell value
markdown
Markdown-formatted rich text. Renders headings, bold, italic, lists, links, images, blockquotes, code, and bibliography @citekey references. See Markdown syntax guide at commonmark.org.
Not filterable Details pane: Text tab
When to use: Long descriptions, field notes, habitat descriptions, species accounts - any text requiring rich formatting or external links.
Full-text indexing: Markdown syntax is stripped and plain text is indexed.
Data entry formats
Single cell - inline Markdown: Any valid Markdown string. Bibliography @citekey references (see Bibliography) and database shortcodes @code:ID (see Database shortcodes) are also processed.
| description | comment |
|---|---|
A large green tree frog. See [@smith2020]. | This renders: A large green tree frog. See (Smith et al. 2020). |
F:species_accounts/litoria.md | This renders the content of |
F: directive (external file): F:path/to/file.md - the file is fetched from usercontent/ at compile time and its content is substituted.
Compilation notes for
Output: Rendered text (without HTML markup). Bibliography @citekey references are resolved to their citation text and so are Database shortcodes. E.g. markdown string: A **large** beetle reported on [EntomoSmith](http://smith.example) and published in [@smith2020]. renders to A large beetle reported on EntomoSmith and published in (Smith et al. 2020). in the DwC output.
Usage with
column: directive- plain (
column: markdownColumnName) exports rendered plain text
TIP
For very long texts or content reused across many taxa, store the Markdown in a separate file in usercontent/ and reference it with F: directive. Set placement to details for encyclopaedia-style species articles that would otherwise clutter the taxon card. See External text files.
category
A categorical value from a fixed or controlled vocabulary. Rendered optionally with a human-readable label and colored badge appearance.
Filter: Categorical multi-select
When to use: Any column with a small, fixed set of categorical values that benefit from color coding or code-to-label mapping - Red List categories, presence/origin status, life-form codes, etc.
Filter behaviour: Shows a searchable dropdown of all unique values present in the data. Users tick one or more values.
Full-text indexing: The display label resolved from Category display is indexed; if no matching label is defined, the raw string value is indexed.
Data entry formats
Single cell: Any string value. The raw cell value is matched against the Raw value column using case-insensitive wildcard patterns (* matches any sequence of characters); the first matching row wins and supplies the label and badge colors.
| redlist |
|---|
LC |
EN |
CR |
Compilation notes for
Output: The original cell value. Intentionally no label substitution by Category display to keep the original intended codes intact.
Usage with
column: directive- plain (
column: categoryColumnName) exports raw cell value
WARNING
The Category display table must be populated for this type to show colored badges or human-readable label substitutions. Setting the Data type to category alone does nothing visual without corresponding category display definitions.
number
Numeric value (integer or decimal). Non-numeric cells are skipped.
Filter: Numeric range
When to use: Measurements, counts, scores, percentages, elevation, or any column that users may want to filter by numeric range.
Filter behaviour: Shows a range control with operations: equal to, less than, less than or equal, greater than, greater than or equal, between (two bounds), and around (value ± margin).
Full-text indexing: The number's string representation is indexed.
Data entry formats
Single cell - plain number: An integer or decimal number. No units or symbols - add those via the Template column.
| wingLength |
|---|
12.5 |
8.3 |
0 |
Compilation notes for
Output: numeric value as is. Non-numeric values are skipped.
Usage with
column: directive- plain (
column: numberColumnName) exports Numeric value of the cell
WARNING
Store bare numbers in data cells formatted as numbers - no units, no symbols. Use the Template column with {{unit "m"}} (see also unit template) to add units at display time. Entering 5 m in a cell turns the value into text and disables numeric filtering.
interval
A numeric range representing minimum and maximum values, both inclusive. Rendered as from - to (e.g. 10 - 15); if both endpoints are equal, shown as a single value.
Filter: Numeric range (interval)
When to use: Typical ranges of physical dimensions (length, wingspan, weight), altitude limits or precision range, depth ranges, or any numeric attribute with a minimum and maximum boundary.
Filter behaviour: Shows a range control with range operations: contains, overlaps and fully inside. Matches if any part of its [from, to] interval satisfies the chosen operation.
Full-text indexing: The rendered range string (e.g. 10 - 15) is indexed as a single token.
Data entry formats
Format 1: Two columns (.from and .to): [columnname].from and [columnname].to, each a single number, use numeric format for both.
| length.from | length.to | comment |
|---|---|---|
10.5 | 15 | |
-5 | 0 | |
42 | If both endpoints are the same, you can put the value in either column and leave the other empty. |
Format 2: Single column - pipe-separated: from | to. Both . and , are valid decimal separators.
| length | comment |
|---|---|
10.6 | 15 | |
42 | If both endpoints are the same, just enter a single value. |
Format 3: Single column - dash-separated: 15.6 - 18.1 or 15.6-18.1. Handles negatives: -10--5.
| length |
|---|
15.6 - 18.1 |
-10--5 |
Compilation notes for
Output: numeric value of either chosen endpoint.
Usage with
column: directive- with
.from(column: intervalColumnName.from) exports the lower endpoint numeric value - with
.to(column: intervalColumnName.to) exports the upper endpoint numeric value
WARNING
Store bare numbers in data cells - no units, no symbols. Enter 5 - 6, not 5 m - 6 m. Use the Template column with {{unit "m"}} (see also unit template) to add units at display time. Entering 5 m - 6 m in a cell would be interpreted as text and not parse correctly.
TIP
When the unit template is configured (e.g. {{unit "cm"}}), it is applied to each endpoint independently, data 10 - 15 producing 10 cm - 15 cm.
date
Date value. Format your data cells as dates, not text. Rendered according to the Date format setting in Customization.
Filter: Date range
When to use: Collection dates, publication dates, observation dates, any date-stamped field.
Filter behaviour: Shows a date range control with a list of dates and operations equal, before date, after date, and between dates (all are inclusive). Match if year, month and day match.
Full-text indexing: The formatted date string (using the active Date format setting in Customization) is indexed.
Data entry formats
Single cell - date format:: cells formated as date in your spreadsheet, only year, month and day are preserved and time is stripped. Also can parse ISO 8601 (2024-01-15) and technically any date parseable by day.js.
| collectionDate |
|---|
2024-01-15 |
1978-06-14 |
2003-08-02 |
Compilation notes for
Output: ISO 8601 date string (YYYY-MM-DD) its numeric components.
Usage with
column: directive- with
.ymd(column: dateColumnName.ymd) exports Date in YYYY-MM-DD format - with
.year(column: dateColumnName.year) exports Year as a 4-digit number - with
.month(column: dateColumnName.month) exports Month as a number (1-12) - with
.day(column: dateColumnName.day) exports Day of month as a number (1-31)
TIP
Configure the display format in Customization → Date format using day.js format tokens. Different formats can be set per language.
months
For storing months of year regardless to the date, like phenological data - which months of the year a taxon is active, flowering, migrating, breeding, etc. Rendered compactly with December-January wraparound support.
Filter: Categorical multi-select (month names)
When to use: Flowering periods, breeding seasons, flight periods, activity windows - any phenological attribute expressed as a set of months.
Filter behaviour: Shows month names as checkboxes. A taxon matches if it is active in any of the selected months.
Full-text indexing: Individual month names are indexed even if they are displayed compactly as a range. Text-search for February will match February, February-March as well as January-April.
Data entry formats
Format 1: Per-month columns: Columns named [columnname].jan, …, [columnname].dec. Any non-empty cell activates that month.
| species | flowers.jan | flowers.feb | ... | flowers.dec | comment |
|---|---|---|---|---|---|
Helleborus niger | x | x | ... | x | Renders as |
Galanthus nivalis | x | x | ... | Renders as |
Format 2: Inline cell - three-letter codes or 1-based numbers: Three-letter codes (jan, feb) or 1-based numbers, pipe/comma-separated, with optional dash ranges. Wraparound (e.g. nov-feb) is supported.
| flowering |
|---|
jan-feb|dec |
12-2 |
jan, mar-oct, dec |
1, 3-10, 12 |
Compilation notes for
Output: compact months range or full list of months.
Usage with
column: directive- with
.compact(column: monthsColumnName.compact) exports Dash-and-comma separated ranges, e.g. January-March, July - with
.full(column: monthsColumnName.full) exports Full list of months, e.g. January, February, March, July
TIP
Customise displayed month names in Customization → Month names with a comma-separated list of 12 names in January-December order.
taxon
A taxon name, rendered as a clickable link. Shows the Taxon details upon click with external search engines if configured in Search online. If the taxon is part of the taxa in this project, a search icon is shown and clicking it will filter the checklist for that taxon.
Filter: Categorical multi-select
When to use: Basionyms, synonyms, type species, host plants, common pests, and other indications of inter-organism relationships ...
Filter behaviour: Shows a searchable dropdown of all unique values present in the data. Users tick one or more values.
Full-text indexing: Both taxon.name and taxon.authority are indexed for full-text search.
Data entry formats
Two columns (name + authority): [columnname].name and [columnname].authority as separate columns.
| basionym.name | basionym.authority |
|---|---|
Rana aurea | Lesson, 1829 |
Single column - pipe-separated: Name|Authority in one cell.
| basionym |
|---|
Rana aurea|Lesson, 1829 |
Single column - name only: Just the taxon name with no authority.
Note we are using here an 'array' to allow for multiple pests for the same taxon in data sheet. This would suppose the Custom data definition contains a row for commonPests# with Data type set to taxon.
| commonPests1 | commonPests2 |
|---|---|
Helicoverpa armigera | Plutella xylostella |
Tetranychus urticae |
Two columns: The same data as above, but written with name and authority in separate columns.
| commonPests1.name | commonPests1.authority | commonPests2.name | commonPests2.authority |
|---|---|---|---|
Helicoverpa armigera | (Hübner, 1805) | Plutella xylostella | (Linnaeus, 1758) |
Tetranychus urticae | Koch, 1836 |
Compilation notes for
Output:
Usage with
column: directive- plain (
column: taxonColumnName) exports name part of the taxon, e.g. 'Myzomela cardinalis' - with
.name(column: taxonColumnName.name) exports name part of the taxon, e.g. 'Myzomela cardinalis' - with
.authority(column: taxonColumnName.authority) exports authority part of the taxon, e.g. '(Gmelin, JF, 1788)' - with
.lastNamePart(column: taxonColumnName.lastNamePart) exports the last whitespace-delimited token of the name, e.g. 'cardinalis', or nothing if the name is a single token
image
An image file, displayed as a clickable thumbnail in the taxon card or with a title caption in the Details pane. Supports relative paths (resolved from usercontent/) and absolute URLs.
Filter: Categorical multi-select Details pane: Media tab
When to use: Species photographs, illustrations, habitat photos, specimen images, ...
Filter behaviour: Shows a searchable dropdown of all unique values present in the data. Users tick one or more values.
Full-text indexing: The image title is indexed for full-text search.
Data entry formats
Two columns (source + title): [columnname].source and [columnname].title as separate columns.
| photo.source | photo.title |
|---|---|
images/litoria.jpg | Green tree frog |
https://example.org/pic.jpg | External photo |
Single column - pipe-separated: source|title in one cell.
| photo |
|---|
images/litoria.jpg|Green tree frog |
Single column - no title: source is the entire content of the cell.
| photo |
|---|
images/litoria.jpg |
Compilation notes for
Output: not accessible through column names, use media: directive in DwC export for media files, see Value source
TIP
Arrays of images work with numbered columns: photo1.source, photo1.title, photo2.source, referenced as photo# in the Custom data definition table. Use a Template to avoid repeating a shared directory path - e.g. images/{{value}}.jpg inside Template lets you enter just the base filename in each cell, assuming those files are in the usercontent/ directory.
sound
An audio file, rendered as a minimal inline audio player with a play button and title.
Filter: Categorical multi-select Details pane: Media tab
When to use: Bird calls, animal vocalisations, insect sounds, or any audio recording associated.
Filter behaviour: Shows a searchable dropdown of all unique values present in the data. Users tick one or more values.
Full-text indexing: The sound title is indexed for full-text search.
Data entry formats
Two columns (source + title): [columnname].source and [columnname].title as separate columns.
| call.source | call.title |
|---|---|
sounds/litoria_call.mp3 | Advertisement call |
Single column - pipe-separated: source|title in one cell.
| call |
|---|
sounds/litoria_call.mp3|Advertisement call |
Compilation notes for
Output: not accessible through column names, use media: directive in DwC export for media files, see Value source
TIP
Supported formats are whatever the user's browser supports natively - typically MP3, OGG, WAV, AAC. Use a Template such as sounds/{{value}}.mp3 to enter only the base filename in each cell and avoid repeating a shared directory path (see Template column).
map
A static map image (JPG, PNG, SVG, etc.) displayed as a clickable thumbnail. For interactive SVG region maps generated directly from your data use mapregions instead.
Filter: Categorical multi-select Details pane: Map tab
When to use: Scanned range maps, hand-drawn distribution maps, or any static image that represents geographic information.
Filter behaviour: Shows a searchable dropdown of all unique values present in the data. Users tick one or more values.
Full-text indexing: The map title is indexed for full-text search.
Data entry formats
Two columns (source + title): [columnname].source and [columnname].title as separate columns.
| rangemap.source | rangemap.title |
|---|---|
maps/litoria_range.png | Known range |
Single column - pipe-separated: source|title in one cell.
| rangemap |
|---|
maps/litoria_range.png|Known range |
Compilation notes for
Output: not accessible through column names, use media: directive in DwC export for media files, see Value source
TIP
Use a Template to avoid repeating a shared directory path - e.g. maps/{{value}}.jpg inside Template lets you enter just the base filename in each cell, assuming those files are in the usercontent/ directory.
mapregions
Encodes geographic distribution as a set of region / status / note (optional) tuples. Renders in two ways: as a color-coded SVG choropleth map in the Details pane and as an annotated inline text list of region names in the taxon card. The two outputs can be used independently or together.
Filter: Categorical multi-select (region names) + optional status filter Details pane: Map tab
When to use: Any geographic distribution data where you want a colored choropleth map, a filterable region list, or both. Works equally well for simple presence/absence, named qualitative statuses (native / introduced / extirpated), and numeric data (counts, scores, measurements) rendered as a gradient or binned color ramp.
Three things are needed together:
- Region codes and status values (with optional notes) in the data sheet
- A row per region code in the Map regions information table
- Color rules in the Map regions legend table. The Template column in Custom Data Definition must hold the SVG file path (e.g.
maps/europe.svg) for the choropleth map to appear - without it, only the inline text list renders.
See Distribution maps with mapregions for the full mental model, SVG authoring guidance, and worked examples.
Filter behaviour: Shows region names as checkboxes, resolved from the Map regions information table. An optional status sub-filter (categorical or numeric range) is shown when the column's Map regions legend contains status codes.
Full-text indexing: Region names (resolved from the Map regions information table) are indexed for full-text search. Categorical and numerical status values as well as individual occurrence notes are indexed as text
Data entry formats
Format 1: Inline (single cell): All regions in one cell, separated by |. Each region entry: RegionCode:Status#Note1#Note2. Status and notes are optional and can contain Markdown and @citekeys from Bibliography as well as shortcodes from Database shortcodes. Escape a literal # inside a note as \#. This is very compact and potentially less readable, the best use case is when your data is generated from an external database.
| distribution | comment |
|---|---|
fr:native#verified in 2021 by @smith2022 | de:introduced | This could render: France *(native, verified in 2021 by Smith et al., 2022)*, Germany *(introduced)* |
Format 2: Per-column: Each region has its own column [columnname].[regioncode]. Cell content: Status#Note. An empty cell means no data from this region. Auto-detected: if sub-columns exist the per-column format is used; otherwise the single-cell inline format is used.
This is equivalent to the previous example (note the distribution.gb with no data), but more readable and easier to edit manually:
| distribution.fr | distribution.de | distribution.gb |
|---|---|---|
native # verified in 2021 by @smith2022 | introduced |
Compilation notes for
Output: none, the mapregions doesn't map to any DwC fields.
TIP
The Template column must specify the SVG file path for the Details pane map to appear - e.g. maps/world.svg. Without a Template value, only the inline region name list is rendered. The world SVG shipped with NaturaList is ready to use; you can also place your own SVG maps in usercontent/maps/.
TIP
For the world SVG map, the special codes fr, nl, and cn are automatically remapped to frx, nlx, and cnx to handle overseas territories correctly. Your data sheet and Map regions information table continue to use fr, nl, cn - only the SVG element class attributes need to carry frx, nlx, cnx. This remapping applies only to filenames ending in world.svg.
geopoint
A geographic point coordinate (latitude/longitude). Rendered as a clickable link showing the original coordinate text; clicking opens a configurable online map URL (external page) at those coordinates.
Not filterable
When to use: Collection localities, observation coordinates, occurrence origins - any geographic point coordinate that users should open on an online map.
Full-text indexing: Geographic coordinates are not indexed for full-text search.
Data entry formats
Format 1: Two columns (.lat and .long): [columnname].lat and [columnname].long. Each accepts DD, DDM, DMS, hemisphere letters (N/S/E/W) as prefix or suffix.
| collectedAt.lat | collectedAt.long |
|---|---|
48.8566 | 2.3522 |
51°30'N | 0°7'W |
Format 2: Single column - pipe-separated: lat|long in one cell.
| collectedAt |
|---|
48.8566|2.3522 |
Format 3: Single cell - auto-parsed: DD, DDM, DMS, ISO 6709, hemisphere letters, French decimal commas.
| collectedAt |
|---|
48.8566, 2.3522 |
N 48°51'23.76" E 2°21'7.92" |
Compilation notes for
Output: selected coordinate component or verbatim coordinate string
Usage with
column: directive- with
.lat(column: geopointColumnName.lat) exports decimal latitude numeric value, e.g. 45.1234 - with
.long(column: geopointColumnName.long) exports decimal longitude numeric value, e.g. -120.5678 - with
.verbatim(column: geopointColumnName.verbatim) exports verbatim coordinate string as entered in the cell, e.g. `45°7'24"N 120°34'4"W`
TIP
The Template column must specify the map URL using {{lat}} and {{long}} - e.g. https://www.openstreetmap.org/?mlat={{lat}}&mlon={{long}}. Without a template the field falls back to a Google Maps URL.