Getting started

About this example

This guide demonstrates the bundled survey form definition.

You will load the model, inspect its contents, and see how invalid definitions are reported.

This package checks form definitions. Submitted-data validation belongs to form.validation.

Load an installed example

library(form.model)
directory <- system.file("examples", package = "form.model")
m <- load_form_model("survey", directory)
m
#> <form_model> survey @ 2026.1 (schema 1.0.0)
#> 15 fields; 2 sheets

The example ships under inst/examples/, so it remains available after installation.

The name survey resolves to survey-form.yaml in that directory. This is the standard naming convention.

Choose the version directory explicitly; the loader never searches for a latest version.

read_form_model(path, package) remains available when you need to load an explicit filename.

What a model contains

A form_model is the checked definition itself, with an S3 class:

names(m)
#> [1] "schema_version" "form"           "references"     "sheets"

It directly contains the form identity, versions, references, and sheets.

Sheets use worksheet names, and their fields use local field names:

names(m$sheets)
#> [1] "Metadata"     "Observations"
names(m$sheets$Metadata$fields)
#> [1] "submission"    "date"          "contact_email" "comment"
m$sheets$Metadata$fields$submission[c("mandatory", "location", "type")]
#> $mandatory
#> [1] TRUE
#> 
#> $location
#> [1] "C2"
#> 
#> $type
#> [1] "string"

The YAML path is used in loading errors, then discarded after a successful load.

The S3 class selects the compact print() method shown above. It does not make the object immutable.

Diagnose a definition

d <- form_definition(m)
d$sheets[[2]]$fields[[1]]$reference <- "missing"
result <- check_form_model(d, resource = "my-definition.yaml")
result$diagnostics
#>             resource                                           path
#> 1 my-definition.yaml $.sheets.Observations.fields.station.reference
#>                      message
#> 1 unknown reference: missing
stopifnot(!result$valid)

as_form_model() and read_form_model() throw model_form_error when a definition is invalid.

error <- tryCatch(as_form_model(d, "my-definition.yaml"), model_form_error = identity)
error$path
#> [1] "$.sheets.Observations.fields.station.reference"
error$diagnostics
#>             resource                                           path
#> 1 my-definition.yaml $.sheets.Observations.fields.station.reference
#>                      message
#> 1 unknown reference: missing