Introducing the YAML Subject specification

30 June, 2016 EN

The YAML Subject specification aims to define a simple file format that allows to store (and export) all the metadata of a given course subject for a student. In particular it was designed to store the assessment so a program can easily parse the file and compute the final mark and show all the available information of the subject.

Introduction

YAML Subject files are encoded in plain YAML, are identified with a double filename extension .subject.yaml and include all the metadata of a subject and its assessment. The main principles of the YAML Subject format are that it must be:

Simple
Human readable
Easy to modify
Extensible
Compatible

Structure

The following are the defined keys of a YAML Subject file. Each YAML Subject file describes a unique subject for one student, so each of these properties is about that particular subject and student:

Key	Required	Description	Type	Examples
`codename`	Required	Two or more capital letters that easily identify the subject	`String`	`CRYPTO` `MND` `SED`
`status`	Required	An integer describing the state of this subject	`Integer`	More info below
`name`	Optional	Full name of the subject	`String`	`Cryptography I` `Micro and Nano Electronic Design` `Sistemas electrónicos digitales`
`code`	Optional	Code of the subject	`String`	`G330923` `230646`
`course`	Optional	Course of the subject	`String`	`Cybersecurity Course` `Master in Electronic Engineering` `Grado en Ingeniería Electrónica`
`institution`	Optional	Institution teaching the subject	`String`	`Standford University` `Universitat Politècnica de Cat` `Universidade de Vigo`
`credits`	Optional	Number of credits of the subject	`Float`	`2.5` `6`
`type`	Optional	Type of the subject	`String`	`Online` `Core` `Obligatoria`
`year`	Optional	Academic year	`String`	`2014` `2015/16` `1999/2000`
`term`	Optional	Term of the subject	`String`	`2` `Spring`
`web`	Optional	Website of the subject	`String`	`coursera.org/learn/crypto` `atenea.upc.edu/31299`
`assessment`	Optional	Array of dictionaries containing the assessment marks	`Array`	More info below

Status

The status key of the subject is an integer that indicates the following:

Status Code	Meaning	Description	Color
`0`	Passed	The subject has been passed and now is archived	Green
`1`	Active	The subject is being taught in the actual course	Blue
`2`	Future	The subject will start in the future	Purple
`4`	Failed	The subject is failed	Red
Other	Unknown	The status of the subject is unknown	Grey

If you want to create a new proprietary status code you should use a code over 100. The colors are recommendations for any GUI.

Assessment

The assessment key is an array that includes all the marks of the subject needed to compute the final mark and a some other important information.

Each element of the array is a dictionary with the following keys:

Key	Required	Description	Default	Example
`mark`	Required	Mark of the item		`8` `68` `7.5`
`description`	Optional	Name of the item		`Mid-Term Exam` `Delivery` `Lab 3`
`weight`	Optional	Float between 0 and 1 indicating the weight of this item over the overall subject mark	`1`	`1` `0.2` `0.05`
`fullscale`	Optional	Float that indicates the maximum mark of this item	`10`	`10` `100` `2.5`

Example

Here is an example of a full YAML Subject file (AACT.subject.yaml):

course: Master in Electronic Engineering (MEE)
institution: Universitat Politècnica de Catalunya (UPC)
codename: AACT
name: Advanced Analog Circuit Techniques
code: 230642
credits: 5
type: Core
year: 2015/16
term: 2
status: 1
web: http://atenea.upc.edu/moodle/course/view.php?id=31281
assessment:
  - description: Deliveries
    mark: 7
    weight: 0.2
  - description: Mid-Term Exam
    mark: 8
    weight: 0.2
  - description: Final Exam
    mark: 76
    fullscale: 100
    weight: 0.6