confirmed, superuser, Administrators
1,577
edits
Changes
no edit summary
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 ROS Development Team as an optional extension for projects and the decision made to use [https://toml.io/en/ 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 [https://github.com/Railway-Op-Sim/UN-Template Template Repository] provided by the [[Developer_GitHub_Organisation|Railway-Op-Sim GitHub Organisation]]. During installation of a simulation Metadata files should be placed within the <code>Metadata</code> directory in the <code>Railway</code> directory of the user's RailOS installation.
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 [https://toml.io/en/ 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 [https://github.com/Railway-Op-Sim/UN-Template Template Repository] provided by the [[Developer_GitHub_Organisation|Railway-Op-Sim GitHub Organisation]]. During installation of a simulation Metadata files should be placed within the <code>Metadata</code> directory in the <code>Railway</code> directory of the user's RailOS installation.
== Schema ==
== 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.
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.
{| class="wikitable"
{| class="wikitable"
|+ Metadata File Schema v1.1
|+ Metadata File Schema v1.1.1
|-
|-
! Key !! Optional !! Description
! Key !! Optional !! Description
| <code>ssn_files</code>|| ☑️ || list of session <code>.ssn</code> files
| <code>ssn_files</code>|| ☑️ || list of session <code>.ssn</code> files
|-
|-
| <code>doc_files</code>|| || list of documentation files (</code>.md</code>, </code>.txt</code>, </code>.pdf</code>)
| <code>doc_files</code>|| || list of documentation files (.md, .txt, .pdf)
|-
|-
| <code>img_files</code> || ☑️ || list of image files (see conventions)
| <code>img_files</code> || ☑️ || list of image files (see conventions)
| <code>release_date</code> || || release date in the form <code>YYYY-MM-DD</code>
| <code>release_date</code> || || release date in the form <code>YYYY-MM-DD</code>
|-
|-
| <code>minimum_required</code> || ☑️ || minimum required version of ROS, if simulation contains features not present in older releases.
| <code>minimum_required</code> || ☑️ || minimum required version of RailOS, if simulation contains features not present in older releases.
|-
| <code>signal_position</code> || ☑️ || 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:
<pre>
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
</pre>
=== Conventions ===
=== 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 <code>.docx</code> adds difficulty for any Linux users.
* Metadata files are assumed to be in <code>.toml</code> format.
* Definition of <code>difficulty</code> is still under discussion as there is no clear metric to measure it yet, it is recommended this key be ignored for now.
* Definition of <code>difficulty</code> 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.
* Documentation is listed as mandatory as all simulations should be accompanied with some form of manual to help users.