Neutral Versioned Form Definitions and Workbook Layouts

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.

form.model

About this project

form.model gives R packages a shared definition of the Excel forms they work with.

Read the Terminology for the concepts used throughout this documentation.

A form is an Excel workbook used to collect data. Its form model describes the expected structure and rules in YAML.

A form model defines:

• The sheets, their order, and the positions of fixed cells or repeated data rows.
• The fields, their types, required values and constraints.
• The keys that identify records and connect related sheets.
• The catalogue tables and named lookups required by reference fields.

The package loads these definitions, checks their consistency, and exposes them through a common R API.

A form model has an identity and version, so applications can explicitly select the definition for a particular form.

Consumers share the form model instead of each maintaining their own description of the form.

The package is independent of any domain. Concrete forms and reference catalogues belong to the packages using it.

Form model checks verify the definition itself. The related packages below use it to work with forms and submitted data.

Related packages

• form.references loads reference catalogues and resolves form model lookups.
• form.validation validates submitted data against form models and references.
• form.tools splits forms using form model layouts and keys.

Installation

Install the latest version available on CRAN:

# Install form.model from CRAN.
install.packages("form.model")

Alternatively, install the latest GitHub release:

# Install the package installer once.
install.packages("pak")
# Install the latest released form.model package.
pak::pak("ultreia-io/form.model@*release")

pak downloads the package and installs its dependencies automatically.

For the development version:

# Install form.model from the development branch.
pak::pak("ultreia-io/form.model@develop")

Getting started

Follow the Getting started guide to load a form model, inspect its fields and diagnose invalid definitions.

The guide includes downloads of the YAML definition, populated form and empty form.

Guides

• Model authoring and schema dialect
• Downstream package integration
• API reference
• Contributing and maintenance

License

LGPL-2.1. See LICENSE.