first schemas with Rolling Stock and Running Path

.github/workflows/release.yaml

@@ -0,0 +1,97 @@
+### github action to make and publish a release
+##
+name: release
+
+## Controls when the workflow will run
+on:
+  ## Triggers the workflow on push or pull request events but only for the master branch
+  push:
+    tags:
+      - "[0-9][0-9][0-9][0-9].[0-1][0-9]" # match calendar versioning
+
+## A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  create_package:
+    name: "create a snapshot package"
+    outputs:
+      version: ${{ steps.tag.outputs.tag }}
+    runs-on: ubuntu-latest
+    steps:
+      # 1. get varibale tag and put it in ${{ steps.tag.outputs.tag }}
+      - name: "get tag"
+        id: tag
+        uses: dawidd6/action-get-tag@v1
+        with:
+          # Optionally strip `v` prefix
+          strip_v: false
+
+      # 2. checkout the repo
+      - name: "checkout"
+        uses: actions/checkout@v2
+
+      # 3. create release notes
+      - name: "create release notes"
+        run: |
+          TOP=$(grep -n "Version \[${{ steps.tag.outputs.tag }}\]" CHANGELOG.md | cut -d: -f1)
+          awk "NR>$TOP" CHANGELOG.md > release-note.tmp.md
+          BOTTOM=$(grep -n -m 1 "## Version\|[Unreleased]:" release-note.tmp.md | cut -d: -f1)
+          BOTTOM=$(( $TOP + $BOTTOM ))
+          BOTTOM=$(( $BOTTOM - 2 ))
+          TOP=$(( $TOP + 1 ))
+          awk "NR>$TOP&&NR<$BOTTOM" CHANGELOG.md > release-note-${{ steps.tag.outputs.tag }}.md
+          sed -i -- "s/###/##/g" release-note-${{ steps.tag.outputs.tag }}.md
+          rm release-note.tmp.md
+
+      # 3. create release archive
+      - uses: papeloto/action-zip@v1
+        with:
+          files: src/ doc/ README.md
+          dest: railtoolkit-schema-${{ steps.tag.outputs.tag }}.zip
+
+      # 5. upload artifact to share it with other jobs
+      - uses: actions/upload-artifact@v3
+        with:
+          path: |
+            release-note-${{ steps.tag.outputs.tag }}.md
+            railtoolkit-schema-${{ steps.tag.outputs.tag }}.zip
+          if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn`
+
+  publish_github:
+    needs: create_package
+    name: "publish on github"
+    runs-on: ubuntu-latest
+    steps:
+      # 1. download artifact in folder artifact/
+      - uses: actions/download-artifact@v3
+
+      # 2. creating a new release
+      - name: "create release"
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+          body_path: artifact/release-note-${{needs.create_package.outputs.version}}.md
+          draft: false
+          prerelease: false
+
+      # 3. upload package to new release
+      - name: "upload release asset"
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: artifact/railtoolkit-schema-${{needs.create_package.outputs.version}}.zip
+          asset_name: railtoolkit-schema-${{needs.create_package.outputs.version}}.zip
+          asset_content_type: application/zip
+
+      # 4. publish release on github
+      - name: "publish release"
+        uses: StuYarrow/publish-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          id: ${{ steps.create_release.outputs.id }}

.github/workflows/testing.yaml

@@ -0,0 +1,35 @@
+# This is a basic workflow to help you get started with Actions
+
+name: "continuous integration test"
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push or pull request events but only for the master branch
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  test:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      - name: "checkout"
+        # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+        uses: actions/checkout@v2
+
+      - name: "install Ajv JSON schema validator"
+        run: npm install -g ajv-cli && npm install -g ajv-formats
+
+      - name: "testing provided examples"
+        run: |
+          ajv test --spec=draft2020 -c ajv-formats -s src/rolling-stock.json -d doc/rolling-stock.example.yaml --valid
+          ajv test --spec=draft2020 -c ajv-formats -s src/running-path.json  -d doc/running-path.example.yaml  --valid

CHANGELOG.md

@@ -2,22 +2,21 @@
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+and this project adheres to [Calendar Versioning](https://calver.org) with YYYY.0M.
 
 Categories: Added, Changed, Deprecated, Removed, Fixed, and Security.
 
 ## [Unreleased]
 
-### Added
-
-  Message
+  * see roadmap in README.md
 
-## Version [0.1.0] - ISO-DATE
+## Version [2022.04]
 
 ### Added
 
-  Message
+  * initial rolling-stock schema
+  * initial running-path Schema
 
 
-[Unreleased]: https://github.com/railtoolkit/PROJEKT/compare/v0.1.0...master
-[0.1.0]: https://github.com/railtoolkit/PROJEKT/releases/tag/v0.1.0
+[Unreleased]: https://github.com/railtoolkit/schema/compare/2022.04...master
+[2022.04]: https://github.com/railtoolkit/schema/releases/tag/2022.04

CITATION.cff

@@ -1,16 +1,23 @@
 # YAML 1.2
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
 ---
 cff-version: 1.2.0
-title: PROJEKT
-message: 'If you use this project, please cite it using these metadata.'
-type: dataset
+title: railtoolkit/schema
+message: >-
+  If you use this software, please cite it using
+  these metadata.
+type: software
 authors:
   - given-names: Martin
     family-names: Scheidt
     email: [email protected]
-    orcid: 'https://orcid.org/0000-0002-9384-8945'
     affiliation: TU Braunschweig
-repository: 'https://github.com/railtoolkit/PROJEKT'
-url: 'https://www.railtoolkit.org/projects/PROJEKT'
+    orcid: 'https://orcid.org/0000-0002-9384-8945'
+abstract: >-
+  This repo collects the descriptions of the
+  structure and the validation constraints of tools
+  in the railtoolkit in JSON schemas. It is,
+  therefore, an alternative to
+  [RailML](https://www.railml.org/).
 license: ISC
-version: v0.1.0

CONTRIBUTING.md

@@ -7,4 +7,10 @@ Please note we have a code of conduct, please follow it in all your interactions
 
 # Pull Request Process
 
-DESCRIPTION
+## Minor Changes and Fixes
+
+TODO: DESCRIPTION
+
+## Breaking Changes
+
+TODO: DESCRIPTION

LICENSE

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) YEAR, NAME \<E-MAIL\>
+Copyright (c) 2022, Martin Scheidt \<[email protected]\>
 
 Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
 

README.md

@@ -1,27 +1,65 @@
-# Projekt
+# RailToolKit Schema
 
 [![License: ISC](https://img.shields.io/badge/license-ISC-green.svg)](https://opensource.org/licenses/ISC)
 
 ------------
 
 # About
 
-TODO
+  This repo collects the descriptions of the structure and the validation constraints of tools in the railtoolkit in JSON schemas. It is, therefore, an alternative to [RailML](https://www.railml.org/). The JSON schemas enable the validation of YAML files in [TrainRun.jl](https://github.com/railtoolkit/TrainRun.jl.git) and [rolling-stock](https://github.com/railtoolkit/rolling-stock.git).
 
-# Minimal working example
+# Prerequisite
 
-TODO
+  You will need a validator to validate the schema against data. This example uses the [Ajv JSON schema validator](https://ajv.js.org).
+  ```bash
+  $ npm install -g ajv-cli && npm install -g ajv-formats
+  ```
+
+# Usage
+
+  You will need the schema and some data. The repo contains among others the rolling-stock schema and example data:
+  ```bash
+  $ git clone https://github.com/railtoolkit/schema.git && cd schema
+  ```
+
+  You can now validate if the data follows the schema:
+  ```bash
+  $ ajv --spec=draft2020 -c ajv-formats -s src/rolling-stock.json -d doc/rolling-stock.example.yaml
+  ```
+  This will return:
+  ```bash
+  $ doc/rolling-stock.example.yaml valid
+  ```
+  Or:
+  ```bash
+  $ ajv --spec=draft2020 -c ajv-formats -s src/running-path.json -d doc/running-path.example.yaml
+  ```
+  This will return:
+  ```bash
+  $ doc/running-path.example.yaml valid
+  ```
+
+# Documentation
+
+  see [Rolling-Stock.md](https://github.com/railtoolkit/schema/blob/main/doc/Rolling-Stock.md) and [Running-Path.md](https://github.com/railtoolkit/schema/blob/main/doc/Running-Path.md) for information about the used attributes.
 
 # Contributing
 
-TODO
+  see [CONTRIBUTING.md](https://github.com/railtoolkit/schema/blob/main/CONTRIBUTING.md) file
+
+# Roadmap
+
+  * include breaking model in rolling-stock schema
+  * add tests for continuous integration
 
 ------------
 
 # License
 
   [![Open Source Initiative Approved License logo](https://opensource.org/files/OSIApproved_100X125.png "Open Source Initiative Approved License logo")](https://opensource.org)
 
-  Copyright (c) YEAR, NAME \<E-MAIL\> (ISC License)
+  Copyright (c) 2022, Martin Scheidt \<[email protected]\> (ISC License)
+
+  Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
 
-  see LICENSE file
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

doc/Rolling-Stock.md

@@ -0,0 +1,33 @@
+# Rolling Stock Schema
+
+------------
+
+# Specification
+
+All attributes for a train are collected under the mapping `train` in alphabetical order:
+| Attributes           | Necessity | Description |
+| -------------------- | --------- | ----------- |
+| `id`                 | required  | Identifier of the train. |
+| `name`               | required  | Name of the train. |
+| `UUID`               | optional  | The unique identifier of the train. |
+| `vehicles`           | required  | A Collection of vehicles that form the train referenced by vehicle `id`. |
+
+All attributes for a single vehicle are collected under the mapping `vehicle` in alphabetical order:
+| Attributes           | Necessity | Description |
+| -------------------- | --------- | ----------- |
+| `air_resistance`     | optional  | Coefficient for air resistance in permil. |
+| `base_resistance`    | optional  | Coefficient for basic resistance  in permil. |
+| `id`                 | required  | Identifier of the vehicle. |
+| `length`             | required  | The length of the vehicle in meter. |
+| `load_limit`         | optional  | The maximum permitted load of the vehicle in metric ton. |
+| `mass_traction`      | optional  | The mass on the powered axles of the vehicle in metric ton. |
+| `mass`               | required  | The empty mass of the vehicle in metric ton. |
+| `name`               | required  | Name of the vehicle. |
+| `picture`            | optional  | A [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) with a picture for humans. | 
+| `power_type`         | optional  | Type of propulsion; values: `diesel`, `electric`, or `steam`. |
+| `rolling_resistance` | optional  | Coefficient for resistance of rolling axles in permil. |
+| `rotation_mass`      | optional  | Factor for rotating mass; larger then 1. |
+| `speed_limit`        | optional  | Maximum permitted speed in kilometers per hour. |
+| `tractive_effort`    | optional  | Tractive effort as pairs of speed in kilometers per hour and tractive force in newton. |
+| `UUID`               | optional  | The unique identifier for a vehicle. |
+| `vehicle_type`       | required  | Type of vehicle; values: `traction unit`, `freight`, `passenger`, or `multiple unit`. |

doc/Running-Path.md

@@ -0,0 +1,14 @@
+# Running Path Schema
+
+------------
+
+# Specification
+
+All attributes for a train are collected under the mapping `path` in alphabetical order:
+| Attributes                | Necessity | Description |
+| ------------------------- | --------- | ----------- |
+| `characteristic_sections` | required  | An array of triplets with a station in meter, speed limit in kilometers per hour, and resistance in permil. |
+| `id`                      | required  | Identifier of the path. |
+| `name`                    | required  | Name of the path. |
+| `points_of_interest`      | optional  | An array of triplets with a station in meter, a name for the point, and if the point applies to the `front` or `rear` of a train. |
+| `UUID`                    | optional  | The unique identifier of the path. |

doc/rolling-stock.example.yaml

@@ -0,0 +1,42 @@
+%YAML 1.2
+---
+vehicle:
+  name: Siemens Desiro Classic # (source: https://de.wikipedia.org/wiki/Siemens_Desiro_Classic)
+  id: BR642
+  UUID: bb53ecc8-35ff-4c63-b480-a342f99e973b
+  picture: https://commons.wikimedia.org/wiki/File:Liesel_28-11-10_642_055-8_im_Bahnhof_Scharfenstein.JPG
+  vehicle_type: multiple unit  # "freight", "passenger", "traction unit" or "multiple unit"
+  power_type: diesel           # "diesel", "electric", or "steam"
+
+  ## main attributes
+  length: 41.7            # in m
+  mass: 68.0              # in t
+  load_limit: 20.0        # in t
+  mass_traction: 52.8     # in t # mass on driving axles of the traction unit
+  speed_limit: 120        # in km/h
+  a_braking: -0.4253      # in m/s^2 # TODO see Roadmap in README.md
+
+  ## coefficients for the vehicle resistance
+  rotation_mass: 1.08     # without dimension
+  base_resistance: 3.0    # in ‰ # coefficient for basic resistance
+  rolling_resistance: 1.4 # in ‰ # coefficient for resistance of rolling axles
+  air_resistance: 0.003   # in ‰ # coefficient for air resistance
+
+  ## tractive effort as pairs of speed and tractive force
+  tractive_effort:        # [v in km/h, F_T in N]
+    - [0.0, 94400]
+    - [10.0, 80000]
+    - [20.0, 61330]
+    - [30.0, 42630]
+    - [40.0, 35600]
+    - [50.0, 32220]
+    - [60.0, 25540]
+    - [70.0, 22990]
+    - [80.0, 19400]
+    - [100.0, 14810]
+    - [120.0, 13380]
+
+train:
+  name: Regional Train
+  id: RB50-1
+  vehicles: [BR642,BR642]