Metadata file

In Railway Operation Simulator (RailOS) Metadata files are files included within a simulation as a means of providing further information and properties not retrievable from the railway and timetable files. Inclusion of such a file was first proposed in 2021 by the RailOS Development Team as an optional extension for projects and the decision made to use TOML as the syntax being both easily human and machine readable. The file is not strictly required but recommended, a starting version of this file is automatically generated via GitHub Actions when using the Template Repository provided by the Railway-Op-Sim GitHub Organisation. During installation of a simulation Metadata files should be placed within the Metadata directory in the Railway directory of the user's RailOS installation.

Schema

In order to ensure any consistency between projects a schema for the Metadata file has been proposed, there being mandatory information which the author should provide and optional additional information.

Metadata File Schema v1.1.1

Key	Optional	Description
name		title of the simulation project
display_name	☑️	alternative name (name that would be used for display purposes)
description	☑️	a brief line summary of the project
rly_file		.rly filename of the simulation itself
ttb_files		list of timetable .ttb files
ssn_files	☑️	list of session .ssn files
doc_files		list of documentation files (.md, .txt, .pdf)
img_files	☑️	list of image files (see conventions)
graphic_files	☑️	list of graphic files (see conventions)
country_code		if a factual simulation, the alpha-2 country code, else FN
year	☑️	year simulation takes place if applicable
factual		is the simulation based on a real or fictional network (true/false)
difficulty	☑️	estimate of the simulation difficulty out of 5
author		leading developer/author (must match ROS site author name)
contributors	☑️	other contributing authors as list (must match ROS site author names)
version		semantic version of the form MAJOR.MINOR.PATCH (first release usually 1.0.0 but can be date 2021.12.1)
release_date		release date in the form YYYY-MM-DD
minimum_required	☑️	minimum required version of RailOS, if simulation contains features not present in older releases.
signal_position	☑️	recommended signal position for the signal position setting in RailOS for this simulation, either "left" or "right" side of the track.

Example

The following example is taken from the Glasgow Suburban project:

rly_file = "Glasgow_Suburban.rly"

ttb_files = [ "Glasgow_Suburban_2022_MoFri_5am.ttb",]

ssn_files = [ "Glasgow_Suburban_2022_MoFri_5am.ssn",]

graphic_files = []

img_files = [ "GlasgowSuburban.bmp",]

doc_files = [ "README.md",]

release_date = "2022-02-22"

version = "1.0.1"

country_code = "GB"

description = "A simulation of the suburban rail network around the Scottish city of Glasgow, UK"

display_name = "Glasgow Suburban"

name = "Glasgow Suburban"

year = 2022

author = "Krizar"

contributors = []

factual = true

Conventions

• In order to be accessible across most systems Documentation is assumed to be either in markdown, plain text or a PDF. Using formatted file types like .docx adds difficulty for any Linux users.
• Definition of difficulty is still under discussion as there is no clear metric to measure it yet, it is recommended this key be ignored for now.
• Documentation is listed as mandatory as all simulations should be accompanied with some form of manual to help users.
• Version number has been made a requirement to cover cases where simulations are later patched or updated.
• You may add further keys to the file for information that does not fall under those provided, however attachment of personal contact information is advised against.
• Images and Graphics must be distinguished, in this context Graphics are objects placed within the simulation map itself, whereas Images covers any other miscellaneous images (e.g. route map screenshots) which, if removed, would not affect the simulation.

Software Usage

Metadata files are used in some ROS utilities including RailOSLauncher and RailOSPkgManager. These make use of the railostools libraries which contains variants for parsing the TOML data in Python, C++ and Java.