Introducing the YAML Subject specification


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.


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


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
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
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
type Optional Type of the subject String Online
year Optional Academic year String 2014
term Optional Term of the subject String 2
web Optional Website of the subject String
assessment Optional Array of dictionaries containing the assessment marks Array More info below


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.


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
description Optional Name of the item Mid-Term Exam
Lab 3
weight Optional Float between 0 and 1 indicating the weight of this item over the overall subject mark 1 1
fullscale Optional Float that indicates the maximum mark of this item 10 10


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
  - 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