Difference between revisions of "Metadata file"

From Railway Operation Simulator Wiki
Jump to navigation Jump to search
m
m (Undo rating for consistency)
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
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
Line 20: Line 20:
 
| <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)
Line 42: Line 42:
 
| <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 ===
Line 54: Line 94:
  
 
== Software Usage ==
 
== Software Usage ==
−
Metadata files are used in some ROS utilities including [[RailOSLauncher]] and [[RailOSPkgManager]]. These make use of the [[rostools]] libraries which contains variants for parsing the TOML data in Python, C++ and Java.
+
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.

Latest revision as of 18:35, 26 April 2023

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.

Retrieved from ‘https://wiki.railos.org/index.php?title=Metadata_file&oldid=4130’