Template Guide

What is a template

A .yaml file defines your survey projects, which consists of sections and variables. To create one, you can directly write a .yaml file or use the Template Builder.

A minimal template structure

  1. Define your Project metadata
  2. Within project, define Sections
  3. Within each section, define Variables
Name: Minimal
UUID: e852c3b6-707b-474e-8520-9f31a85385db
Description: "some description"
Version: 1
Sections:
  Site:
    Weight: 0
    StableId: site
    Variables:
      Date:
        StableId: date
        Type: Date
        AutoNow: True
        Required: True
      Name:
        StableId: vid-name
        Type: Option
        Weight: 1
        Overview: True
        Required: True
        Options:
          - Site A
          - Site B
          - Site C
        Expandable: True
        Default: Site A
        ...
  Observation:
    Weight: 1
    StableId: observation
    Parent: Site
    Variables:
      Name:
        Type: Option
        Default: A
        Options:
          - A
          - B
          - C
    ...

Project

name: Minimal
UUID: e852c3b6-707b-474e-8520-9f31a85385db
Description: "some description"
Version: 1
Key Purpose
name Display name of the project
UUID Standard UUID
Description Markdown text - no length limit
Version Integer (start from 1) - bump to push updates to importers
Sections Defines the sections of this project

Sections

Sections:
  Site:
    Weight: 0
    StableId: site
    Variables:
      ...
  Observation:
    Weight: 1
    StableId: observation
    Parent: Site
    Variables:
      ...
Key Purpose
<Section Name> Display name of the section
StableId String - Links existing data, never change.
Weight Integer (-128 to 128) - Display order, the lower appears first
Parent Parent section name - must match an existing <Section Name>; omit for root sections
OnMap See Map Overview below.
TitleVar See Parent Label below.
SpawnChild See Inline Child Records below.
Variables Defines the variables within this section

Variables

...
    Variables:
      Date:
        StableId: date
        Type: Date
        AutoNow: True
        Required: True
      Name:
        StableId: vid-name
        Type: Option
        Weight: 1
        Overview: True
        Required: True
        Options:
          - Site A
          - Site B
          - Site C
        Expandable: True
        Default: Site A
      ...
Key Purpose
<Variable Name> The displayed variable name
StableId Links existing data — never change
Type See Variable Types below.
Weight Display order, the lower appears first
Default Pre-filled value for new record - must match the variable type
Tip Multi-line helper text, rendered as Markdown
Overview True / (omit) - show in overview table
Required True / (omit) - blocks save until filled
AutoFillLast See Quick Capture below

Each variable type may accept additional arguments, see Variable Types below.

Variable Types

Type Description
String Single-line text
Markdown Multi-line text, rendered as Markdown
Int Whole number
Float Decimal number
Boolean Yes / No toggle
Date Date picker
Time Time picker
DateTime Date and time picker
Option Pick from predefined list
OptionCount A number for each option in the list
LocationMap Single GPS point on map
PathMap A path (> 2 GPS points) on map
PolygonMap A polygon (> 3 GPS points) on map
Photo Attach one or more photos

New variable types may be added in future versions!

Time (Date, Time, DateTime)

  Variables:
    Start:
      Type: DateTime
      Required: True
      AutoNow: True
    Done:
      Type: Time
      Required: True

Set AutoNow: True to to pre-fill the value the current time.

Number (Int, Float)

  Variables:
    DistanceToShore(m):
      Type: Int
      Required: True
      AutoFillLastIncrement: True
      Min: 0
      Max: 5000
      Step: 100
    FlowSpeed:
      Type: Float
      Required: True
      Min: 0
      Max: 10.0
      NumValues: 4
      NumDigits: 2
Key Purpose
AutoFillLastIncrement See Quick Capture below
Min Minimum value for this variable
Max Maximum value for this variable
Step Controls how much the +/- buttons increment or decrement the value (Int Only)
NumValues See Rapid Machine Readings below
NumDigits See Rapid Machine Readings below

Option / OptionCount

  Variables:
    Surveyors:
      Type: Option
      Multiple: True
      Options:
        - Mary
        - John
        - Tom
        - Peter
      Expandable: True
      Default: Mary,John # <- Comma separated Option
      Required: True
    FishCommunity:
      Type: OptionCount
      Options:
        - FishA
        - FishB
        - FishC
        - FishD
        - FishE
        - FishF
        - FishG
        - FishH
      Expandable: True
      Default: "FishA:1,FishD:5" # <- should rarely need default here, but this is the sample format
Key Purpose
Options List of predefined choices
Expandable True / (omit) - allow expanding existing options
Multiple True / (omit) - allow picking multiple options (Option) only

Media

  Variables:
    Photo:
      Type: Photo
      Multiple: True # allow attaching multiple photos

By default, only one photo per variable. Set Multiple: True to allow more.

Special Features

Map Overview

Sections:
  Site:
    OnMap: Region
    Variables:
      Region:
        Type: PolygonMap
        Required: True
        ...
      ...

Set OnMap to the name of a LocationMap, PathMap, or PolygonMap variable in the same section. This adds a map toggle button to the overview table — see all your records plotted as points, paths, or polygons at a glance.

Parent Label

When working in a child section, it’s easy to lose track of which parent record the data belongs to. Set TitleVar to a variable from the parent section — its value appears as a subtitle in the child overview, keeping the context visible at all times.

Sections:
  Site:
    Variables:
      Name:
        Type: Option
        Options:
          - Site A
          - Site B
          - Site C
          - Site D
        Tip: Site name
        Required: True
        Default: Site A
      Weather:
        Type: Option
        ...
  Observations:
    Parent: Site
    TitleVar: Name  # <- a variable in parent (Site)
    Variables:
      ...

Inline Child Record

Sections:
  SurveyPath:
    SpawnChild: True
    Variables:
      Name:
        Type: String
      Path:
        Type: PathMap
      Community:
        Type: OptionCount
        ...
      ...
  SpecialIndividual:
    Parent: SurveyPath
    TitleVar: Name
    Variables:
      Species:
        Type: Option
      Photo:
        Type: Photo
      Note:
        Type: Markdown
        Tip: Why it's special?
      ...

When a site record contains an exceptional find that needs its own dedicated section, SpawnChild adds a shortcut directly in the record — no need to navigate back to the overview and locate the child section manually. For example, record species counts at this level, then jump straight to a detailed individual observation and back, without losing your place.

Quick Capture

Variables:
  Species:
    Type: Option
    AutoFillLast: True
    Options:
      - A
      - B
      - C
      - D
  Distance:
    Type: Float
    AutoFillLastIncrement: True
    Step: 20

When collecting a batch of similar records using Save & Next, AutoFillLast carries the previous value into the next record so you only type what changed. AutoFillLastIncrement (Int and Float only) does the same but adds Step (default 1) each time.

Rapid Machine Readings

Variables:
  FlowSpeed1:
    Type: Float
    Required: True
    NumValues: 4
    NumDigits: 3
  FlowSpeed2:
    Type: Float
    Required: True
    NumValues: 4
    NumDigits: 3
  FlowSpeed3:
    Type: Float
    Required: True
    NumValues: 4
    NumDigits: 3

When recording from instruments that display multiple fixed-format readings — for example 1.203 0.203 2.301 -0.203 0.001 — set NumValues to the number of readings (4 here) and NumDigits to the number of digits after the decimal point (3 here). Just type the digits one by one — the decimal point appears at the right position automatically, and focus jumps to the next variable after all digits are entered.

Sharing & Updating templates

Sharing

Host your .yaml on Google Drive and set sharing to “anyone with the link.” Paste the share URL directly. For any other host, use a direct-download URL.

# Google
https://drive.google.com/file/d/1jWhGfJ2BvyU_LZWE48RzUmvVJTsW4BWM/view?usp=drive_link

# Direct url from my server
https://pufstudio.net/dl/Generic_Ecology_Survey.yaml

# Direct url from my repo
https://codeberg.org/even311379/FieldSurvey/raw/branch/master/app/src/main/assets/tour.yaml

Updating

Once someone has imported your template via URL, you can push updates to all of them: edit the .yaml, increment Version, and update to the same URL. Anyone can easily update their project easily.

Never change these after publishing:

  • UUID
  • StableId of any section or variable