railtoolkit · kaat0 · Jan 2, 2025 · Jan 2, 2025 · Jan 3, 2025 · Jan 7, 2025
diff --git a/.gitignore b/.gitignore
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,17 +11,47 @@ Categories: Added, Changed, Deprecated, Removed, Fixed, and Security.
 ### Added
 * running path:
   * added `description` attribute (see Issue #5)
+  * added `track` to characteristic sections for grouping track sections
+  * added `groups` array to points_of_interest for categorizing points
+  * added comprehensive test suite with valid and invalid test cases
+  * added example file with block sections and signals
+* rolling stock:
+  * added `description` attribute to trains and vehicles (see Issue #5)
+  * added `hydraulic` and `misc` to power_type options
+  * added `non-revenue` to vehicle_type options
+  * added complete schema for `simplified_characteristics` with required fields and constraints
+  * added `coasting` parameter to simplified characteristics
+  * added `emergency_deceleration` to simplified characteristics
+  * added `model_fidelity` attribute on different levels
+  * added comprehensive brake model configuration with multiple fidelity levels
+  * added detailed brake types: eddy_current_brake, electrodynamic_brake, and friction_brake
+  * added brake timing parameters: reaction_time, response_time, threshold_time
+  * added new train types: snow_removal, construction, emergency
+  * added comprehensive documentation for all attributes and model fidelity levels
 
 ### Changed
 * running path:
   * running path arrays now contain named attributes (see Issue #4)
-  * when using `characteristic_sections` only one optional attribute (`speed` or `resistance`) must be specified
+  * characteristic sections now require at least one of `speed`, `resistance`, or `track` attributes
   * measures for `points_of_interest` can now take three values: "front", "middle", and "rear"
+* rolling stock:
+  * changed tractive_effort to require at least 3 unique pairs
+  * changed rotation_mass description to specify >= 1
+  * changed train requirements to need either `formation` or `simplified_characteristics`
+  * changed `train_type` to include comprehensive list of train service types
+  * changed brake modeling to support multiple fidelity levels
+  * changed model_fidelity to be required at top level and component levels
+  * refined train_type categories into passenger, freight, and special groups
+  * improved documentation with detailed explanations of model fidelity rationale
 
 ### Removed
 * running path:
   * removed `name` attribute (see Issue #5)
   * removed `UUID` attribute (see Issue #5)
+* rolling stock:
+  * removed `name` attribute from trains and vehicles (see Issue #5)
+  * removed `UUID` attribute from trains and vehicles (see Issue #5)
+  * removed `diesel` from power_type options
 
 ## Version [2022.05]
 
@@ -34,15 +64,12 @@ Categories: Added, Changed, Deprecated, Removed, Fixed, and Security.
   * renamed `train` into `trains` and changed type to array (see Issue #2)
   * renamed `path` into `paths` and changed type to array (see Issue #2)
 
-
 ## Version [2022.04]
 
 ### Added
-
   * initial rolling-stock schema
   * initial running-path Schema
 
-
 [Unreleased]: https://github.com/railtoolkit/schema/compare/2022.05...main
 [2022.05]: https://github.com/railtoolkit/schema/compare/2022.04...2022.05
 [2022.04]: https://github.com/railtoolkit/schema/releases/tag/2022.04
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,20 +5,35 @@ email, or any other method with the owners of this repository before making a ch
 
 Please note we have a code of conduct, please follow it in all your interactions with the project.
 
-# Pull Request Process
+## Pull Request Process
 
-## Minor Changes and Fixes
+### Minor Changes and Fixes
 
-TODO: DESCRIPTION
+For minor changes and fixes:
+1. Ensure your code follows the existing style and conventions
+2. Update the documentation if necessary
+3. Add tests for any new functionality
+4. Make sure all tests pass locally
+5. Create a Pull Request with a clear description of the changes
 
-## Breaking Changes
+### Breaking Changes
 
-TODO: DESCRIPTION
+For breaking changes:
+1. Open an issue first to discuss the proposed changes
+2. Document all breaking changes clearly in your Pull Request
+3. Update all relevant documentation
+4. Add or update tests to cover the changes
+5. Update the version number according to [Calendar Versioning](https://calver.org)
+6. Provide migration instructions if applicable
 
 ## Roadmap
 
-  * include breaking model in rolling-stock schema
-  * fallback with constant acceleration and deceleration
+Current development priorities:
+* test braking model in rolling-stock schema
+* improve braking model in rolling-stock schema
+* add model for interlocking
+* add model for topology
+* add model for timetbling and blocking times
 
 ## Add yourself as a contributor
 

diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2022, Martin Scheidt \<m.scheidt@tu-bs.de\>
+Copyright (c) 2022 - 2025, Martin Scheidt (orcid.org/0000-0002-9384-8945)
 
 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.
 

diff --git a/README.md b/README.md
@@ -1,54 +1,93 @@
-# RailToolKit Schema
+# RailToolKit/schema
 
 [![License: ISC][license-img]][license-url] [![DOI][zenodo-img]][zenodo-url] [![Build Status][ci-img]][ci-url] [![All Contributors][Contributors-img]][Contributors-url]
 
 ------------
 
 ## About
 
-  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).
+The RailToolkit/schema provides JSON schemas for railway operations data, offering a lightweight alternative to RailML. It focuses on two main aspects:
+
+1. Rolling Stock Schema
+   - Defines train and vehicle characteristics
+   - Supports both simplified and detailed modeling approaches
+   - Includes parameters like speed, mass, resistance, and tractive effort
+
+2. Running Path Schema
+   - Describes railway paths with speed limits and track resistance
+   - Supports points of interest (signals, platforms, etc.)
+   - Enables precise position-based path descriptions
+
+The schemas use standardized railway units and can be validated using standard JSON schema tools. They are designed to support railway simulation and planning tools while maintaining simplicity and ease of use.
 
 ## Prerequisite
 
-  You will need a validator to validate the schema against data. This package provides a helper script that uses the [Ajv JSON schema validator](https://ajv.js.org).
-  Ajv rquires to have [node](https://nodejs.org/) installed.
+You will need a validator to validate the schema against data. This package provides a helper script that uses the [Ajv JSON schema validator](https://ajv.js.org).
+Ajv requires to have [node](https://nodejs.org/) installed.
 
-  ```bash
-  $ node --version # test if node is installed
-  ```
+```bash
+$ node --version # test if node is installed
+```
 
 ## 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
-  ```
-
-  Install all project dependencies:
-  ```bash
-  $ npm install
-  ```
-
-  You can now validate if the data follows the schema:
-  ```bash
-  $ npm run validate:rolling-stock doc/rolling-stock.example.yaml
-  ```
-  This will return:
-  ```bash
-  $ doc/rolling-stock.example.yaml valid
-  ```
-  Or:
-  ```bash
-  $ npm run validate:running-path doc/running-path.example.yaml
-  ```
-  This will return:
-  ```bash
-  $ doc/running-path.example.yaml valid
-  ```
+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
+```
+
+Install all project dependencies:
+```bash
+$ npm install
+```
+
+You can validate if the data follows the schema:
+```bash
+$ npm run validate:rolling-stock doc/rolling-stock.example.yaml
+$ npm run validate:running-path doc/running-path.example.yaml
+```
+
+## Testing
+
+The repository includes comprehensive test suites for both schemas:
+
+```bash
+$ npm run test          # Run all tests
+$ npm run test:stock    # Run rolling-stock tests only
+$ npm run test:paths    # Run running-path tests only
+```
+
+Each test suite includes:
+- Example file validation
+- Valid test cases
+- Invalid test cases
 
 ## 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.
+### Sub schemas
+
+See 
+* [Rolling-Stock.md](doc/Rolling-Stock.md) and 
+* [Running-Path.md](doc/Running-Path.md)
+
+for information about the used attributes in the sub schemas.
+
+### Units
+
+The schema uses common railway units for all numerical values:
+
+| Quantity         | Unit | Description |
+|------------------|------|-------------|
+| Speed            | km/h | Kilometers per hour |
+| Mass             | t    | Metric tons |
+| Length           | m    | Meters |
+| Time             | s    | Seconds |
+| Force            | kN   | Kilonewton |
+| Power            | kW   | Kilowatt |
+| Acceleration     | m/s² | Meters per second squared |
+| Resistance       | ‰    | Per mille (mm/m) |
+| Unit-less        | -    | Dimensionless values |
+
 
 ## Contributors
 
@@ -64,21 +103,19 @@
     </tr>
   </tbody>
 </table>
-
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
-
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
-See [CONTRIBUTING.md](https://github.com/railtoolkit/schema/blob/main/CONTRIBUTING.md) file if you are interested to contribute.
+See [CONTRIBUTING.md](CONTRIBUTING.md) file if you are interested to contribute.
 
 ------------
 
 # License
 
   [![Open Source Initiative Approved License logo](https://149753425.v2.pressablecdn.com/wp-content/uploads/2009/06/OSIApproved_100X125.png "Open Source Initiative Approved License logo")](https://opensource.org)
 
-  Copyright (c) 2022, Martin Scheidt \<m.scheidt@tu-bs.de\> (ISC License)
+  Copyright (c) 2022 - 2025, Martin Scheidt (orcid.org/0000-0002-9384-8945) (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.