confirmed, superuser, Administrators
539
edits
Changes
Added schema and lengthened Metadata description
In [[Railway Operation Simulator]] (ROS) ''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 [[ROS 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 ROS 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.
{| class="wikitable"
|+ Metadata File Schema v1.1
|-
! Key !! Optional !! Description
|-
| <code>name</code> || ||title of the simulation project
|-
| <code>display_name</code>|| ☑️ || alternative name (name that would be used for display purposes)
|-
| <code>description</code>|| ☑️ || a brief line summary of the project
|-
| <code>rly_file<code>|| || <code>.rly</code> filename of the simulation itself
|-
| <code>ttb_files</code>|| || list of timetable <code>.ttb</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>img_files</code> || ☑️ || list of image files (see conventions)
|-
| <code>graphic_files</code> || ☑️ || list of graphic files (see conventions)
|-
| <code>country_code</code> || || if a factual simulation, the [https://www.iban.com/country-codes alpha-2 country code], else <code>FN</code>
|-
| <code>year</code> || ☑️ || year simulation takes place if applicable
|-
| <code>factual</code> || || is the simulation based on a real or fictional network (true/false)
|-
| <code>difficulty</code> || ☑️ || estimate of the simulation difficulty out of 5
|-
| <code>author</code> || || leading developer/author (must match ROS site author name)
|-
| <code>contributors</code> || ☑️|| other contributing authors as list (must match ROS site author names)
|-
| <code>version</code> || || semantic version of the form <code>MAJOR.MINOR.PATCH</code> (first release usually <code>1.0.0</code> but can be date <code>2021.12.1</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.
|}
Metadata files can be parsed using the [[rostools]] package, which includes Python, C++ and Java versions.
=== 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.
* 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.
* 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 [[ROSLauncher]] and [[ROSPkgManager]]. These make use of the [[rostools]] libraries which contain variants in Python, C++ and Java.