The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.