Package {form.model}

Title: Neutral Versioned Form Definitions and Workbook Layouts
Version: 0.3.2
Description: Loads explicit YAML resources describing versioned forms, fields, declarative constraints, reference requirements, and workbook layouts. Checks model definitions against an installed YAML schema and consistency rules, and provides value-like inspection APIs. Does not validate submitted data or connect to external services.
License: LGPL-2.1
URL: https://ultreia-io.github.io/form.model/, https://github.com/ultreia-io/form.model
BugReports: https://github.com/ultreia-io/form.model/issues
Encoding: UTF-8
Depends: R (≥ 4.1.0)
Imports: yaml (≥ 2.3.10)
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
Config/Needs/coverage: covr, xml2
Config/Needs/website: pkgdown, covr, htmltools, xml2
Config/roxygen2/version: 8.1.1
NeedsCompilation: no
Packaged: 2026-10-23 05:23:05 UTC; tchemit
Author: Tony Chemit [aut, cre]
Maintainer: Tony Chemit <dev@tchemit.fr>
Repository: CRAN
Date/Publication: 2026-11-06 16:40:21 UTC

Neutral versioned form definitions

Description

Load explicit YAML resources and check their definitions. This package never validates submitted workbooks, evaluates rules, or supplies reference data.

Author(s)

Maintainer: Tony Chemit tchemit@users.noreply.github.com

Authors:

See Also

Useful links:

Signal a model error

Description

Signal a model error

Usage

abort_model(resource, path, message, diagnostics = NULL)

Arguments

resource

Source label.

path

Location within the source.

message

Error message.

diagnostics

Optional definition diagnostics.

Value

Raises model_form_error carrying the supplied context.

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))

Decode a checked cell location

Description

Decode a checked cell location

Usage

cell_coordinates(location)

Arguments

location

Uppercase A1-style address already checked by the schema.

Value

List with one-based numeric row and column coordinates.

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("contact@example.org", "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)

Check a model argument's shape

Description

Check a model argument's shape

Usage

model_arg(model)

Arguments

model

Object passed to an accessor.

Value

Returns silently for a form_model with required top-level properties; otherwise raises model_form_error. Does not recheck the definition.

Check value attributes

Description

Check value attributes

Usage

plain(x)

Arguments

x

Any R object.

Value

Whether attributes are absent or limited to names.

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)

Read restricted YAML as data

Description

Read restricted YAML as data

Usage

read_yaml_data(path)

Arguments

path

UTF-8 YAML file.

Details

Uses YAML 1.1 types without expression evaluation. Invalid syntax, non-string keys and parser warnings raise model_form_error.

Value

Parsed data: named lists for mappings and unnamed lists for sequences.

Check a schema scalar type

Description

Check a schema scalar type

Usage

scalar_type(x, type)

Arguments

x

Value to check without coercion.

type

string, boolean, number, integer, or scalar.

Value

Whether x is one nonmissing, unclassed value of the requested type. Numbers must be finite; scalar accepts text, logicals and numbers.

Collect schema diagnostics

Description

Collect schema diagnostics

Usage

schema_check(x, node, definitions, path, add)

Arguments

x

Definition value.

node

Schema node.

definitions

Schema definitions for resolving references.

path

Diagnostic location.

add

Callback receiving ⁠(path, message)⁠.

Value

Invisible NULL; diagnostics are passed to add.

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")

Collect model consistency diagnostics

Description

Collect model consistency diagnostics

Usage

semantic_check(d, add)

Arguments

d

Definition that has passed schema checking.

add

Callback receiving ⁠(path, message)⁠.

Value

Diagnostics for references, constraints, dependencies and layouts, passed to add.

Require a nonempty string

Description

Require a nonempty string

Usage

text_arg(x, name)

Arguments

x

Value to check; whitespace is not trimmed.

name

Argument name for errors.

Value

Returns silently on success; raises model_form_error otherwise.

Check restricted YAML syntax

Description

Check restricted YAML syntax

Usage

yaml_profile(text, resource)

Arguments

text

YAML source text.

resource

Source label for errors.

Details

Rejects tags, anchors, aliases, merges, directives and document markers outside quoted strings, comments and block scalars. Parsing happens separately.

Value

Returns silently on success; raises model_form_error otherwise.