---
title: "Getting started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(form.model)
```


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

```{r}
library(form.model)
directory <- system.file("examples", package = "form.model")
m <- load_form_model("survey", directory)
m
```

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:

```{r}
names(m)
```

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

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

```{r}
names(m$sheets)
names(m$sheets$Metadata$fields)
m$sheets$Metadata$fields$submission[c("mandatory", "location", "type")]
```

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

```{r}
d <- form_definition(m)
d$sheets[[2]]$fields[[1]]$reference <- "missing"
result <- check_form_model(d, resource = "my-definition.yaml")
result$diagnostics
stopifnot(!result$valid)
```

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

```{r}
error <- tryCatch(as_form_model(d, "my-definition.yaml"), model_form_error = identity)
error$path
error$diagnostics
```

## Read next

- [Authoring model definitions](model-authoring.html): create your own form.
- [Model specification](model-specification.html): field types, constraints and layouts.
- [Distributing models](downstream-packages.html): use models in another package.
- [Function reference](https://ultreia-io.github.io/form.model/reference/index.html): API details.