Assessment

To get support by the Visual Studio Code extension, create a file with the name *.assessment.yml or *.assessment.yaml.

version: "0.1"
assessment:
  id: "my-assessment"
  title: "Assessment Title"
  questions: [...]
  scales: [...]

Root Structure

The top-level YAML structure.

Property	Type	Required	Description
version	string	Yes	Fixed to "0.1".
assessment	Assessment	Yes	The assessment definition.

Assessment

The assessment configuration object.

Property	Type	Required	Description
id	string	Yes	Unique identifier for the assessment.
title	string	Yes	Human-readable title of the assessment.
questions	array<Question>	No	List of Questions. Default: [].
scales	array<Scale>	No	List of Scales. Default: [].

Example

version: "0.1"
assessment:
  id: depression-screening
  title: Depression Screening
  questions: [...]
  scales: [...]

Questions

Defines the individual items to be presented to the user. A Question object is polymorphic based on its type property.

Property	Type	Required	Description
id	string	Yes	Unique identifier for the question.
title	string	Yes	The text/prompt of the question.
answer	Answer	No	Pre-filled answer (usually null).
type	string	Yes	Discriminator for the question type.
body	object	Yes	Configuration specific to the type.

Question Types

Type	Body Definition	Description
"scale"	LikertScaleBody	A numeric rating scale.
"textfield"	TextBody	Single-line text input.
"textarea"	TextBody	Multi-line text input.
"select"	SelectBody	Binary choice (Yes/No).
"single-choice"	EmptyBody	Single selection from a predefined option set.
"multi-choice"	MultiBody	Multiple selection from a predefined option set.

Answer

The user's response to a question. Can be one of:

• integer (uint8, 0–255)
• boolean
• string
• null (no answer provided)

Question Bodies

TextBody

Used for textfield and textarea.

Property	Type	Required	Description
placeholder	string	Yes	Placeholder text shown in the input field.

SelectBody

Used for select (binary choice: Yes/No).

Property	Type	Required	Description
yes	string	No	Label for true/yes option.
no	string	No	Label for false/no option.

MultiBody

Used for multi_choice.

Property	Type	Required	Description
options	array<string>	Yes	List of available options.

Example

id: depression-screening
title: Depression Screening
questions:
  - id: q1
    type: textfield
    body:
      placeholder: "Please enter your name"
    answer: null
scales: [...]

EmptyBody

Used for types that require no extra configuration (e.g., single_choice). Object with no properties.

Scales

Defines a scoring scale or sub-scale within the assessment.

Property	Type	Required	Description
id	string	Yes	Unique identifier for the scale.
title	string	Yes	Display title for the scale.
type	string	Yes	Must be "scale".
mode	Mode	Yes	Calculation mode for results ("sum" or "average").
items	array<Item>	Yes	List of Items included in this scale.
body	ScaleBody	Yes	Defines the numerical range and constraints for the scale.

Mode

String. Must be one of:

• "sum": Sum of item scores.
• "average": Average of item scores.

Item

References a question to include in a scale.

Property	Type	Required	Description
id	string	Yes	Must match a Question ID in the assessment.
reverse	boolean	No	If true, reverse-score this item (e.g., flip a 0-4 scale to 4-0). Default: false.

LikertScaleBody

Defines the range and constraints for a numeric scale (used in scale questions).

Property	Type	Required	Description
min	integer (uint8)	Yes	Minimum value (0–255).
max	integer (uint8)	Yes	Maximum value (0–255).
hint-min	string	No	Label for the minimum value (e.g., "Strongly Disagree").
hint-max	string	No	Label for the maximum value (e.g., "Strongly Agree").

ScaleBody

Defines the numerical range for a scale.

Property	Type	Required	Description
min	integer (uint32)	Yes	Minimum score value.
max	integer (uint32)	Yes	Maximum score value.

Example

version: "0.1"
assessment:
  id: depression-screening
  title: Depression Screening
  questions:
    - id: q1
      title: How often do you feel sad?
      type: scale
      body:
        min: 0
        max: 4
        hint-min: Never
        hint-max: Always
  scales:
    - id: depression-total
      title: Depression Score
      type: scale
      mode: sum
      items:
        - id: q1
      body:
        min: 0
        max: 4