Difference between revisions of "Metadata file"

From Railway Operation Simulator Wiki
Jump to navigation Jump to search
(Created page with "A '''metadata file''' is an optional file that can be included in a community project to pass information about the project to external programs....")
Tags: Mobile web edit Mobile edit Advanced mobile edit
 
(Added schema and lengthened Metadata description)
Line 1: Line 1:
−
A '''metadata file''' is an optional file that can be included in a community project to pass information about the project to [[List of External Programs|external programs]]. The metadata file is generally placed in a "Metadata" folder which is placed in the root directory.
+
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.
  
−
The metadata file is a yaml file, and the standard structure is defined in the [[ROS GitHub Organisation]].
+
== 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.

Revision as of 23:24, 21 February 2022

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 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 ROS GitHub Organisation. During installation of a simulation Metadata files should be placed within the Metadata directory in the Railway 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.

Metadata File Schema v1.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 ROS, if simulation contains features not present in older releases.

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 ROSLauncher and ROSPkgManager. These make use of the rostools libraries which contain variants in Python, C++ and Java.

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