---
title: "Authoring model definitions"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Authoring model definitions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## 1. Copy the example

```{r example-download, echo=FALSE, results="asis"}
# Offer a relative website download or the installed resource path.
if (identical(Sys.getenv("IN_PKGDOWN"), "true")) {
  # Render the relative download link.
  cat("[Download the survey YAML](../examples/survey/form.yaml)\n")
} else {
  # Point readers to the bundled YAML definition.
  cat("Find the YAML with `form_resource(\"examples/survey/form.yaml\", \"form.model\")`.\n")
}
```
and save it as `my-form.yaml`.


```{r, results='asis', echo=FALSE}
# Display the bundled definition as a YAML example.
cat("```yaml\n", paste(readLines(form.model::form_resource("examples/survey/form.yaml", "form.model")), collapse="\n"), "\n```\n", sep="")
```

## 2. Edit your fields

For example, a required count and an optional length with its unit:

```yaml
count: {mandatory: true, type: integer, minimum: 0}
length: {type: number, minimum: 0}
unit: {type: string, required_field: length, enum: [cm, m]}
```

For table sheets, field order is column order. The column count is derived from the fields; omit `column_count`.

## 3. Check your model

```r
# Load the edited definition and report any model errors.
form.model::read_form_model("my-form.yaml")
```

A valid file returns a model summary; an invalid file reports the problem.

See [Model specification](model-specification.html) for field types, constraints and layouts.