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.
| 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. |
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
.docxadds difficulty for any Linux users. - Definition of
difficultyis 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.