Rhubarb YAML Specification

This page details the YAML specification intended for use with Rhubarb 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.
---++ Naming Conventions Try to use descriptive names for things instead of abbreviations wherever possible. If you have question/section/form names that have multiple words, seperate each word with an underscore. ---++ To Do * Add option in dictionary for "other", where someone can fill in another type if it's not listed * Add support for conditional forms (forms that are only available if there's a certain answer in a question in another form) * Add a "display" option for sections that determines how it should be rendered (*NOTE*: this should probably not be in the specification; this sort of thing probably belongs in the application itself). Here's some ideas for display types: * table * inline (question and input field on same line) * indented (question on one line, input field on the next line and indented)
Topic attachments
I Attachment Action Size Date WhoSorted ascending Comment
form_dtd.yamlyaml form_dtd.yaml manage 4.7 K 31 Jan 2007 - 13:05 JeremyStephens Rhubarb YAML DTD
remembrall.ymlyml remembrall.yml manage 8.8 K 31 Jan 2007 - 13:06 JeremyStephens an example specification
Topic revision: r35 - 17 Dec 2007, JeremyStephens
 

This site is powered by FoswikiCopyright © 2013-2022 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Vanderbilt Biostatistics Wiki? Send feedback