Documentation for YAPC Survey YAML file
NAME
YAPC-Survey-spec - Specification for YAML documents containing questions for a conference survey.
SYNOPSIS
--- #YAML:1.0
name: YAPC::Europe 2013 Survey
version: 0.01
abstract: Survey for Perl Conference events.
license: Public Domain
sections:
- label: Demographics (required)
tag: demographics
results: survey
preamble: These questions will help us understand who our attendees are.
questions:
- label: "Age Band:"
mandatory: yes
type: select
options:
- key: under 20
value: 1
- key: 20 - 39
value: 2
- key: 40 - 59
value: 3
- key: 60 and over
value: 4
- label: "Sex:"
status: hidden
mandatory: yes
type: select
options:
- key: Male
value: M
- key: Female
value: F
- key: Decline to state
value: D
- label: "Job Type:"
mandatory: yes
multipart:
- type: select
options:
- key: The Boss
value: 1
- key: Underling
value: 2
- key: Newbie
value: 3
- key: Other
value: 3
- type: text
preamble: "If 'Other' please enter your professional job title:"
meta-spec:
version: 1.2
DESCRIPTION
This document describes version 1.2 of the YAPC Survey YAML file specification.
The SURVEY.yml file describes the content for a survey, consisting of sections, questions and options. This file is intended to be used to create a set of questions for a specific conference event. The surveys are implemented via the Labyrinth website framework, which provides a parser to convert the YAML into a data structure. The internal data structure can then be used to display the survey to a respondant, or to reference the recorded results submitted by the respondant.
FORMAT
TERMINOLOGY
respondant
The person expected to take part in the survey.
survey
A collection of sections, questions and options.
section
One or more sections, which split the survey into manageable chunks for a respondant to read.
HEADER
The first line of a SURVEY.yml file should be a valid YAML document header like "--- #YAML:1.0".
FIELDS
The remainder of the SURVEY.yml file is a single YAML mapping whose keys are described here. However, the fields are split into two groups. The Informational Fields provide information regarding the survey or the SURVEY.yml file. The Content Fields are those that contain the sections and questions relating to the survey itself.
Informational Fields
meta-spec
Example:
meta-spec:
version: 1.2
(Spec 1.0) [required] {URL} This field indicates the location of the version of the SURVEY.yml specification used.
name
Example:
name: YAPC::Europe 2013 Survey
(Spec 1.0) [required] {string} The name of the survey.
version
Example:
version: 0.01
(Spec 1.0) [required] {version} The version of the survey to which the SURVEY.yml file refers.
abstract
Example:
abstract: Survey for YAPC::Europe 2013 Perl Conference.
(Spec 1.0) [required] {string} A short description of the purpose of the survey.
author
Example:
author:
- Barbie <barbie@cpan.org>
(Spec 1.0) [optional] {list of strings} A YAML sequence indicating the author(s) of the survey. The prefered form is author-name <email-address>.
license
Example:
license: Public Domain
(Spec 1.0) [required] {string} The license under which this distribution may be used and redistributed.
Section Fields
The main field here is sections, which is the container for all survey content. Within this, there are section fields, question fields and the question type fields, which are described within each sub heading.
sections
Example:
sections:
- label: Section 1
- label: Section 2
(Spec 1.0) [required] {list} This field defines the sections that make up the survey. There must be at least one.
Sections
label
Example:
label: Section 1
(Spec 1.0) [optional] {string} The section heading that will be displayed prior to the section content.
tag
Example:
tag: thistag
(Spec 1.1) [optional] {string} A shorthand description of the section, that is used internally to unqiuely identify the section.
results
Example:
results: survey,feedback,tpf
(Spec 1.1) [optional] {string} Used to identify the output filter to be used. Currently only 3 formats are available, but more could be added in the future. Can be attributed to a section or question. If set as 'survey' at the section level, associated questions are assumed to use the same result type, unless explicity set for the question.
preamble
Example:
preamble: blah blah blah
(Spec 1.0) [optional] {string} Text that will appear before the section.
footnote
Example:
footnote: blah blah blah
(Spec 1.0) [optional] {string} Text that will appear after the section
questions
Example:
questions:
- label: Question 1
- label: Question 2
(Spec 1.0) [required] {list} A set of questions within the current section.
Question Fields
The main field here is 'questions', which is the container for all question content. Within this, there are question fields and the question type fields, which are described within each sub heading.
label
Example:
label: "Age Band:"
(Spec 1.0) [optional] {string} The question text. This can be optional, if the previous question is a continuation. Note that it is advisable to include in quotes if special characters (e.g. ':') are to be included in the question text.
hidden
Example:
hidden: yes
(Spec 1.0) [optional] {string} If used, should only be set to yes to indicate the question is to be ignored.
mandatory
Example:
mandatory: yes
(Spec 1.0) [optional] {string} If used, should only be set to yes to indicate the question is required.
type
Example:
type: select
(Spec 1.0) [optional] {string} Determines the type of form input to be used. Values can be select, radio, checkbox, text, textarea, matrix, count and currency.
preamble
Example:
preamble: blah blah blah
(Spec 1.0) [optional] {string} Text that will appear after the question label, but before the question options/input.
footnote
Example:
footnote: blah blah blah
(Spec 1.0) [optional] {string} Text that will appear after the question.
collate
Example:
collate: yes
(Spec 1.0) [optional] {string} If used, should only be set to yes to indicate the question is to be tied to other collated questions. Future revisions will allow gouping.
multipart
Example:
multipart:
- type: checkbox
options:
- key: This was my first YAPC
value: 1
(Spec 1.0) [optional] {list} Used when multiple questions are to be tied together as one related question. The contents of a multipart set are the same question fields available to normal questions, except the 'multipart' field.
group
Example:
group: YAPCs
(Spec 1.0) [optional] {string} Used with multipart questions to tie the related questions together.
options
Example:
options:
- key: under 20
value: 1
- key: 20 - 39
value: 2
- key: 40 - 59
value: 3
- key: 60 and over
value: 4
(Spec 1.0) [optional] {list} Used when 'type' is set to select, radio or checkbox, to list the options to be displayed for that question.
Options Fields
key
Example:
key: under 20
(Spec 1.0) [required] {string} If options have been specified, at least one key/value pair is required. Value is the text that will be displayed.
value
Example:
value: 1
(Spec 1.0) [required] {string} If options have been specified, at least one key/value pair is required. Value is the value that should be return for the form field.
SEE ALSO
HISTORY
2014-08-03
* Created version 1.2 of this document.
* URL links amended to yapc-surveys.org.
* Various description and typo fixes.
* Changed HISTORY date formats to meet W3CDTF standards.
2013-05-26
* Created version 1.1 of this document.
* Added tag and results fields.
2010-10-10
* Created version 1.0 of this document.