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

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

`_study.yml` provides study-level properties for a study directory --- the
study identifier, an optional description, and the standards and terminologies
applied in the study. Load it with `study_config()`, either directly or as the
`@study` property of `mighty_study()`. The file structure is defined by a
[JSON-schema](https://json-schema.org) accessible with:

```r
system.file("schema", "study.json", package = "mighty.metadata")
```

Below you can find a detailed description of the structure.

```{r echo=FALSE}
S7schema::document_schema(
  x = system.file("schema", "study.json", package = "mighty.metadata"),
  header_start_level = 1
)
```

# Standards and terminology

`standards` and `terminology` are optional lists describing the standards and
controlled terminologies applied in the study. Each entry requires an `id` and
a `version`:

```yaml
study_id: example_study

standards:
  - id: ADaM-IG
    version: '1.1'

terminology:
  - id: MedDRA
    version: '22.1'
  - id: WHODrug
    version: 2023 JAN
```

Omitting a field and supplying an empty list (`standards: []`) are equivalent
and mean that no entries are defined.

`version` must be a string. Since yaml infers types, unquoted values that look
like numbers (e.g. `version: 27.0`) are read as numbers and fail validation.
Quote them to keep the exact literal: `version: '27.0'`.

Only the structure is validated here --- presence, shape, and required fields.
Domain-semantic checks, such as whether a submitted version actually exists,
are the responsibility of the consuming package.