as a way to specify CRF format.
1.0 (stable)
Dictionary
The dictionary block, which contains enumerable/categorical mappings, looks like this:
dictionary:
- name: <string> # required; must be unique among definitions
description: <string>
default: <text> # if default is supplied, it must match a value in 'map'
map:
# for each name/value pair, you need an entry in 'map'
- value: <text> # required; must be unique among values
label: <string> # required; must be unique among labels
description: <string>
Example
Here's an example of a dictionary block.
dictionary:
- name: money
description: some money types
map:
- value: Y
label: Yen
description: "Japan's currency"
- value: D
label: Dollar
description: "U.S. currency"
- value: E
label: Euro
description: "Europe's currency"
- name: color
description: some colors
default: 3
map:
- value: 1
label: Blue
description: like the sky
- value: 2
label: Yellow
description: like the sun
- value: 3
label: Green
description: like the grass
- value: 4
label: Orange
description: like an orange
- value: 5
label: Red
description: like an apple
---+++ Questions
The questions block should come after the dictionary block and look like this:
questions:
- name: <name>
prompt: <string>
description: <string>
unit: <string>
type: <string> # valid types: string, integer, float, number, text, boolean,
# date, time, datetime, dictionary
options:
cardinality: <range> # for type 'dictionary'; specifies how many answers you expect
# from a definition
soft range: <range> # usually for numeric types
hard range: <range> # usually for numeric types
definition: <name> # a name from the dictionary block; required if type is "dictionary"
pattern: <string> # a regular expression (to validate strings)
---++++!! Example
Here's an example of a questions block:
questions:
- name: age
prompt: "How old are you?"
description: age
unit: years
type: integer
options:
soft range: 13..80
hard range: 0..150
- name: favorite_penguin
prompt: "What's your favorite species of penguin?"
description: "penguin preference"
type: dictionary
options:
definition: penguin_species
cardinality: 1
---+++ Sections
Here's the sections block:
sections:
- name: <name>
description: <string>
header: <string>
footer: <string>
content:
- name: <name> # section or question name
repeated: <string> # only applicable for subsections
required: <boolean>
dependency:
question: <name> # name of the question
answer: <any> # answer required for this question/section to be displayed
---++++!! Example
Here's some YAML:
sections:
- name: penguins
header: start here
footer: end here
content:
- name: fond_of_penguins
required: yes
- name: favorite_penguin
dependency:
question: fond_of_penguins
answer: yes
- name: penguin_food
repeated: "1..10"
dependency:
question: fond_of_penguins
answer: yes
- name: person
description: personal information
header: some personal info
content:
- name: first_name # question
required: yes
- name: last_name # question
required: yes
- name: penguins # section
required: yes
---+++ Forms
Here's the forms block:
forms:
- name: <name>
description: <string>
header: <string>
footer: <string>
# ********** about the 'enrollment' field **********
# if you want a form to be the enrollment form for a study, set this field
# to 'true' or 'false'.
#
# NOTE: there can only be one enrollment form per study, and it must be simple and basic,
# containing only things like name, address, phone number, etc. sections are not
# allowed for enrollment forms
enrollment: <bool>
# ********** about the 'multiple' field **********
# if a form needs to be entered in multiple times (i.e. a checkup in a clinical trial),
# you can set 'multiple' to 'true'. the index field determines which question name the repeated
# form is indexed by (i.e. visit_number) and is used for sorting purposes. the index field cannot
# be a section name, and enrollment forms cannot have 'multiple'.
multiple: <bool>
index: <name>
options:
content:
- name: <name>
repeated: <string> # only valid for sections, repeated questions are illegal
required: <boolean>
dependency:
section: <name>
question: <name>
answer: <any>
---++++!! Example
YAML:
forms:
- name: enrollment
header: start of my enrollment form
footer: end of my enrollment form
enrollment: true
content: # this can only contain questions; no sections allowed in the enrollment form
- name: last_name
required: yes
- name: first_name
required: yes
- name: gender
required: yes
- name: birth_date
required: yes
- name: ssn
required: yes
- name: phone_number
- name: address
- name: medical_history
description: "patient's medical history"
content:
- name: broken_bones
- name: head_injuries
- name: hospital_visits
dependency:
section: broken_bones
question: number_of_broken_bones
answer: 1..Infinity
- name: drug_responses
description: "patient's response to various medications"
content:
- name: anesthesia_response
- name: penicillin_response
- name: morphine_response
---+++ [[http://www.kuwata-lab.com/kwalify/][Kwalify]] Specification
[[https://biostat.app.vumc.org/wiki/pub/Main/RhubarbYAML/crf_dtd.yaml][Here's the specification]] we've been working on for use with the [[http://www.kuwata-lab.com/kwalify/][Kwalify]] gem.
---+++ Changelog
* Main.JeremyStephens - 24 Oct 2006; removed primary key option, as this is now left up to the application to handle
* Main.JeremyStephens - 31 Jan 2007; added multiple/index fields to the forms block
---++ 1.1 (in development)
---+++ Dictionary changes
Shorthand is now allowed for maps for cases where you don't have any special options. For example, you could do this:
dictionary:
- name: money
description: some money types
map:
- Yen: Y
- Dollar: D
- Euro: E
The string on the left of the colon for each entry in the map is the label, and on the right is the value. To avoid confusion, don't use label names of *'label'* or *'value'*.
---+++ Question changes
The =definition= option that was in the =options= section is now on the top-level. Also, if you use a definition for a question, you don't have to specify that the question type is =dictionary= anymore. For example:
questions:
- name: favorite_penguin
prompt: "What's your favorite species of penguin?"
description: "penguin preference"
definition: penguin_species
#type: dictionary (no longer needed)
---+++ Section/Form changes
You can now use shorthand for a section's or form's content if you don't have any special options.
sections:
- name: penguins
header: start here
footer: end here
content:
- fond_of_penguins
- favorite_penguin
- penguin_food
Footer is now gone until someone asks to have it back. I can't see that it would be used very much.
---+++ New 'layout' portion
There is now a new portion of the specification called 'layout', which is used to specify which forms a project should have. There was previously no way to specify the use of a form that was defined elsewhere.
Example:
layout:
- name: foo
enrollment: true
- name: bar
---+++ Other changes
The option hashes are going to be done away with. Everything there will be moved to the top-level. Less typing FTW.