Package 'form.model'

Construct a checked model

Description

Construct a checked model

Usage

as_form_model(definition, resource = "<list>")

Arguments

definition	Named list following form_schema(); sequences are unnamed lists.
resource	Source label for diagnostics.

Value

The definition as a form_model list, without the source label. Invalid definitions raise model_form_error with diagnostics.

Examples

model <- read_form_model("examples/survey-form.yaml", "form.model")
as_form_model(form_definition(model))

---

Check a form definition

Description

Check a form definition

Usage

check_form_model(definition, resource = "<list>")

Arguments

definition	Named list following form_schema(); sequences are unnamed lists.
resource	Source label for diagnostics.

Details

Checks schema structure, then model consistency if structure passes. Invalid definitions return diagnostics; invalid arguments raise model_form_error. Submitted data is not checked.

Value

A form_model_check with valid and a diagnostics data frame containing resource, path and message columns.

Examples

model <- read_form_model("examples/survey-form.yaml", "form.model")
check_form_model(form_definition(model))

---

Get the complete definition

Description

Get the complete definition

Usage

form_definition(model)

Arguments

model

A checked form_model from read_form_model() or as_form_model().

Details

Accessors preserve declaration order and do not revalidate models. Treat checked models as read-only. Invalid model arguments raise model_form_error.

Value

An ordinary list with schema_version, form, references and sheets.

Examples

model <- read_form_model("examples/survey-form.yaml", "form.model")
form_definition(model)$form

---

Get one field

Description

Get one field

Usage

form_field(model, id)

Arguments

model	A checked form_model from read_form_model() or as_form_model().
id	Exact ⁠<sheet>.<field>⁠ identifier.

Value

One definition as returned by form_fields(). Unknown IDs raise model_form_error.

Examples

model <- read_form_model("examples/survey-form.yaml", "form.model")
form_field(model, "Observations.unit")$enum

---

Get fields in declaration order

Description

Get fields in declaration order

Usage

form_fields(model, sheet = NULL)

Arguments

model	A checked form_model from read_form_model() or as_form_model().
sheet	Exact worksheet name, or NULL for all sheets.

Details

Adds field IDs, names, sheet names and numeric coordinates. Omitted mandatory becomes FALSE; reference shorthand becomes a mapping with severity "error" when omitted. Other undeclared properties stay absent. Use form_definition() for the original declarations.

Value

Field definitions named ⁠<sheet>.<field>⁠. Unknown sheets raise model_form_error.

Examples

model <- read_form_model("examples/survey-form.yaml", "form.model")
form_fields(model, sheet = "Observations")

---

Get a sheet layout

Description

Get a sheet layout

Usage

form_layout(model, id)

Arguments

model	A checked form_model from read_form_model() or as_form_model().
id	Exact worksheet name.

Value

The effective layout (cells or table), with table column_count derived from the fields. Unknown sheets raise model_form_error.

Examples

model <- read_form_model("examples/survey-form.yaml", "form.model")
form_layout(model, "Observations")

---

Get form identity and versions

Description

Get form identity and versions

Usage

form_metadata(model)

Arguments

model

A checked form_model from read_form_model() or as_form_model().

Value

A list with form and schema_version.

Examples

model <- read_form_model("examples/survey-form.yaml", "form.model")
form_metadata(model)

---

Get reference requirements

Description

Get reference requirements

Usage

form_references(model)

Arguments

model

A checked form_model from read_form_model() or as_form_model().

Value

Declared reference names. Reference data is not loaded.

Examples

model <- read_form_model("examples/survey-form.yaml", "form.model")
form_references(model)

---

Locate an installed resource

Description

Locate an installed resource

Usage

form_resource(path, package)

Arguments

path	File path relative to the package directory.
package	Installed package name.

Value

Absolute file path. Missing files and paths escaping the package raise model_form_error.

Examples

form_resource("examples/survey-form.yaml", "form.model")

---

Read the model-definition schema

Description

Read the model-definition schema

Usage

form_schema(version = "1.0.0")

Arguments

version

Schema version; currently "1.0.0".

Details

Uses the package's form.model/schema/1 dialect, not JSON Schema.

Value

The schema as a nested list. Unsupported versions raise model_form_error.

Examples

form_schema()$contract_version

---

Get sheet definitions

Description

Get sheet definitions

Usage

form_sheets(model)

Arguments

model

A checked form_model from read_form_model() or as_form_model().

Details

Table layouts include column_count derived from the ordered fields. Use form_definition() for the original declarations.

Value

Sheets in declaration order, named by worksheet, each with fields and layout.

Examples

model <- read_form_model("examples/survey-form.yaml", "form.model")
names(form_sheets(model))

---

Check a scalar against a form field type

Description

Share field-type checks between model definitions and validation consumers. Requiredness and other field constraints are handled by the caller.

Usage

form_value_matches_type(x, type)

Arguments

x	Scalar value to check, without coercion.
type	One of string, email, integer, number, boolean, latitude, longitude, date, or datetime.

Details

Dates require YYYY-MM-DD; datetimes require YYYY-MM-DDTHH:MM:SSZ. Both must parse and format back to the identical string, using UTC for datetimes. Emails require nonempty local and domain parts, a domain dot, and no whitespace or additional at signs. Mailbox existence is not checked. Numeric values must be finite; integers must have no fractional part. Coordinates are decimal degrees: latitude is in ⁠[-90, 90]⁠ and longitude in ⁠[-180, 180]⁠, including both endpoints. Numeric text is not coerced.

Value

One logical value; FALSE for missing or incompatible values, unsupported types, or classed values such as factors, Date, and POSIXct.

Examples

form_value_matches_type("[email protected]", "email")
form_value_matches_type("2026-10-18T12:00:00Z", "datetime")

---

Load a model by filename prefix

Description

Load a model by filename prefix

Usage

load_form_model(name, directory)

Arguments

name	Prefix of ⁠<name>-form.yaml⁠, starting with a letter and containing only letters, digits, underscores, dots or hyphens.
directory	Directory containing the file.

Value

A checked form_model; see read_form_model() for errors.

Examples

directory <- system.file("examples", package = "form.model")
load_form_model("survey", directory)

---

Print a model summary

Description

Print a model summary

Usage

## S3 method for class 'form_model'
print(x, ...)

Arguments

x	A checked form_model.
...	Unused.

Value

x, invisibly; prints identity, versions, and field and sheet counts.

---

Print definition check results

Description

Print definition check results

Usage

## S3 method for class 'form_model_check'
print(x, ...)

Arguments

x	A form_model_check from check_form_model().
...	Unused.

Value

x, invisibly; prints validity and any diagnostics.

---

Read and check a YAML form model

Description

Read and check a YAML form model

Usage

read_form_model(path, package = NULL)

Arguments

path	File path, or package-relative path when package is supplied.
package	Optional installed package name.

Details

Uses YAML 1.1 types: quote versions and codes; use true/false for booleans. Tags, anchors, aliases, merges, directives and document markers are unsupported. The source path is not stored in the model.

Value

A checked form_model list. Invalid YAML or definitions raise model_form_error with source context and available diagnostics.

Examples

model <- read_form_model("examples/survey-form.yaml", "form.model")
form_metadata(model)

---

Select an exact model version

Description

Select an exact model version

Usage

select_form_model(paths, id, version, package = NULL)

Arguments

paths	Nonempty character vector of YAML file paths.
id	Exact form identifier.
version	Exact form version.
package	Optional installed package containing the relative paths.

Value

The matching form_model. All files are checked; invalid files or anything other than one match raise model_form_error.

Examples

select_form_model("examples/survey-form.yaml", "survey", "2026.1",
                  package = "form.model")

---