Skip to content

Commit a94e5e1

Browse files
TuThoThaithbar
TuThoThai
and
thbar
authored
Update readme (#993)
* update readme Revamp of the readme to better reflect new management of branches and versions. Also includes a longer part on how people can contribute. * Apply typo corrections Based on review by @thbar Co-authored-by: Thibaut Barrère <thibaut.barrere@gmail.com> * Improving new features details Based on review by @trurlurl * Improve branch details Addition of maintenance status & notes * Releases - Text improvement Addtion "v" to release numbers & notes --------- Co-authored-by: Thibaut Barrère <thibaut.barrere@gmail.com>
1 parent b74f985 commit a94e5e1

File tree

1 file changed

+100
-53
lines changed

1 file changed

+100
-53
lines changed

‎README.md‎

Lines changed: 100 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,87 +1,134 @@
11
# NeTEx (Network Timetable EXchange) XML schema
2-
**(C) 2009-2024 NeTEx, CEN, Crown Copyright**
2+
**(C) 2009-2026 NeTEx, CEN, Crown Copyright**
33

4-
## Schemas for:
54

6-
- Core
7-
- Part 1 (Network)
8-
- Part 2 (Timetables)
9-
- Part 3 (Fares)
10-
- Part 5 (New Modes)
5+
## Overview 🔍
116

12-
### Overview
7+
NeTEx is CEN Technical Specification (CEN/TS); it is published as a series referenced as CEN/TS 16614. It is dedicated to the exchange of scheduled data (network, timetable and fare information). It is based on Transmodel V6.2 (EN 12896 series) and SIRI (CEN/TS 15531-4/-5 and EN 15531-1/-2/-3) and supports the exchange of information of relevance for passenger information about public transport services and also for running Automated Vehicle Monitoring Systems (AVMS).
138

14-
- NeTEx (Network Timetable EXchange) XML schema is a standardized format for exchanging network timetable data.
9+
Although the data exchanges targeted by NeTEx are predominantly oriented towards provisioning passenger information systems and AVMS with data from public transport scheduling systems, it is not restricted to this purpose. NeTEx can also provide an effective solution to many other use cases for transport data exchange.
1510

16-
### Folder structure 📁
11+
_Note : Many NeTEx concepts are taken directly from Transmodel. The definitions and explanation of these concepts are extracted directly from the respective standard and reused in NeTEx, sometimes with adaptions in order to fit the NeTEx context._
1712

18-
The individual XML files are organized hierarchically in folders, following the same structure as the UML model and documentation. The architecture is:
13+
### Repository content 📚
1914

20-
- **Main Folder for Each Part**: There is a main folder for each part of the schema (e.g., Core, Part 1, Part 2, etc.).
21-
- **Subfolders for Functional Areas**: Within each main folder, there are subfolders for each NeTEx functional area, keeping the schema well-structured.
15+
This repository contains the XML Schemas (XSD) for:
16+
- The core part of NeTEx
17+
- NeTEx Part 1 (Network topology)
18+
- NeTEx Part 2 (Scheduled Timetables)
19+
- NeTEx Part 3 (Fare information)
20+
- NeTEx Part 5 (Alternative modes )
2221

23-
You can find more information about the directory's structure on the [wiki](https://github.com/ITxPT/NeTEx/wiki/Structure-And-Compatibility#netex-directory-structure)
24-
### UML models
22+
### Respository structure 📁
2523

26-
- You can refer to the NeTEx UML Physical and Conceptual models (note that NeTEx Conceptual model is Transmodel) for a detailed UML view of the schema packages.
27-
- These models are available in electronic format.
28-
29-
## Getting started 🚀
24+
In each branch, we have:
25+
- The folder `xsd` in which all the XML schemas can be found,
26+
- The folder `examples` in which all examples can be found,
27+
- At the root folder, `Siri.spp` which is the project for XMLSpy and `Siri.xpr` for Oxygen.
3028

31-
### Main root schemas
29+
The `xsd` folder is sub-divided as follow:
30+
- `gml` for all geometry-related elements,
31+
- `netex_framlework` for all shared components and frames,
32+
- one sub-folder per NeTEx Part (from 1 to 5),
33+
- other complementary sub-folders.
34+
At the root of the `xsd` folder, the file `NeTEx_publication.xsd` should be used as the main one for production and validation purposes. It includes references to all the other XSD.
3235

33-
1. **netex_publication**
36+
### Branches 🌿
37+
38+
| Branch Name | Description | Maintenance status | Link |
39+
| ----------- | ------------------------------------------------------- | ----------------------------------------------- |-----------------------------------------------
40+
| v2.0 | The last stable branch of the XML Schema, result of the NeTEx revision made during 2022-2026 | Bug fixes only | [Direct link](https://github.com/NeTEx-CEN/NeTEx) |
41+
| v1.3 | The previous branch of the XML Schema that was published prior to the 2026 revision of NeTEx, it matches the state of the XSD at the date of the publication of Part 6 (CEN/TS 16614-6:2024) with the correction of bugs and typos -- **Important note**: this branch is not longer maintained | Not maintained | [Direct link](https://github.com/NeTEx-CEN/NeTEx/tree/v1.3) |
42+
| v2.1-wip | All the upcoming work to improve v2.0 | In development | [GitHub](https://github.com/NeTEx-CEN/NeTEx/tree/v2.1-wip) |
43+
| v3.0-wip | All the upcoming work preparing the migration from CEN/TS to CEN/EN for the entire NeTEx series | In development | [GitHub](https://github.com/NeTEx-CEN/NeTEx/tree/v3.0-wip) |
44+
45+
All other branches are considered as feature branches, meaning that they are used for development only and are to be deleted once a Pull Request is merged. See below for more details on contributions.
46+
47+
**Important notes:**
48+
- Any branch marked `wip` is a non-stable branch.
49+
- For a specific XML Schema matching a published CEN document, use `releases`.
50+
51+
----
52+
53+
## Getting started 🛠️
54+
55+
### Main root schemas
56+
57+
1. **netex_publication.xsd**
3458
- Embeds NeTEx XML model elements in a bulk output file format for use in asynchronous publication.
3559
- The intended content scope can be indicated by a filter object.
36-
- **netex_publication_noConstraint**: same as **netex_publication** but without all the XSD constraint that is convenient to speed up the work in development phases (but at the price of a much weaker validation).
60+
- It should be used as the main XSD for production and validation purposes.
61+
62+
Note: `netex_publication_noConstraint.xsd` is the same as `netex_publication.xsd` but without all the XSD constraints (e.g., unicity of attributes). It is convenient to speed up the work in development phases, but at the price of a much weaker validation.
3763

3864
2. **netex_siri.xsd**
3965
- Embeds NeTEx XML model elements in the SIRI protocol for dynamic exchange of elements between servers.
4066
- Supports both request/response and publish/subscribe.
4167

42-
### Additional information
43-
44-
- **nx.xsd**
68+
3. **nx.xsd**
4569
- Embeds NeTeX XML model elements within a simple thematic organisation to facilitate browsing and inspection of NeTEx.
4670
- The NX schema is not intended for actual use.
4771

72+
### How to navigate the schemas
73+
74+
The schema is systematically divided into small modular files. Generally, for each functional package in the design model there are two XML schema files:
75+
76+
- **netex_xxxx_version.xsd**: Contains the definitions of each element or group,
77+
- **netex_xxxx_suppport.xsd**: Contains the data type, reference structures and values for enumerations.
78+
4879
### XML examples
4980

50-
- Explore XML examples of the use of both protocols in the */examples* subdirectory.
81+
1. **Functions**
5182

52-
Further information on the examples is available on the [wiki](https://github.com/ITxPT/NeTEx/wiki/Using-NeTEx#how-to-use-example-files)
53-
### Support for XML editors
83+
The folder contains snippets of XML files focused on a specific function or element of Public transport services (e.g., timetable, stop places, fares, etc.). They are meant to illustrate how to use NeTEx to model part of the public transport service.
5484

55-
- **Altova XMLSpy Project**: Find an organized view of the schema and examples in the root directory.
56-
- Project file: NeTEx.spp
85+
2. **Standards**
5786

58-
- **Oxygen Project File**:
59-
- Project file: NeTEx.xpr
87+
The folder contains more comprehensive NeTEx files that aim to represent either an entire dataset as commonly found in other specifications, domains or Member States. They are meant to illustrate several parts of one public transport service. They should be used as an ensemble rather than single files.
6088

6189
----
6290

63-
### Note on the schema
91+
## How to contribute 🖊️
92+
93+
### Starting a discussion 💬
94+
95+
Either for a modelling question or a request for change, please start a discussion using the [GitHub issues](https://github.com/NeTEx-CEN/NeTEx/issues).
96+
In your issue, make sure that:
97+
- The title is a clear summary of your question / requst for change,
98+
- The content sufficiently details:
99+
- The context,
100+
- The elements / features you want to discuss,
101+
- If relevant, include extracts of your NeTEx file.
102+
103+
### Making a change 🚀
64104

65-
The schema is systematically divided into small modular files. Generally, for each functional package in the design model (See UML Model), there are two XML schema files:
105+
1. Identify which branch you need to target:
106+
- v2.1-wip for all changes that will apply to NeTEx v2.0 (e.g., bug fixes, typos, improvement of certain features without breaking changes, etc.)
107+
- v3.0-wip for all changes that will apply when NeTEx migrates to EN (e.g., deprecation of features, refactor of certain elements, breaking changes including new features, etc.)
108+
2. Create a feature branch with a clear name (e.g., bugfix_vehicletype)
109+
3. Work on the changes and do the Pull Request
66110

67-
- **netex_xxxx_suppport.xsd**: Contains data type and ref structure definitions.
68-
- **netex_xxxx_version.xsd**: Contains the element definitions.
111+
For new features, the decision between targetting v2.1-wip or v3.0-wip will be made by the group.
112+
113+
_Upcoming: templates for Pull Request_
69114

70115
----
71-
## Branches 🌿
72-
73-
| Branch Name | Description | Link |
74-
| ----------- | ------------------------------------------------------- | ----------------------------------------------- |
75-
| `master` | Current head of the project | [GitHub](https://github.com/NeTEx-CEN/NeTEx) |
76-
| `next` | Work for the next release | [GitHub](https://github.com/NeTEx-CEN/NeTEx/tree/next) |
77-
78-
# Change Log
79-
## Releases
80-
| Release Number | Release Date | Description | Link | Release Notes |
81-
| -------------- | ------------- | ---------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------- |
82-
| 1.2 | March 2022 | Latest productive version before new modes merge | [Code](https://github.com/NeTEx-CEN/NeTEx/releases/tag/v1.2) | [Release Notes](https://github.com/NeTEx-CEN/NeTEx/blob/v1.2/README.md) |
83-
| 1.2.2 | August 2023 | First version of new modes | [Code](https://github.com/NeTEx-CEN/NeTEx/releases/tag/v1.2.2) | [Release Notes](https://github.com/NeTEx-CEN/NeTEx/blob/v1.2.2/README.md) |
84-
| 1.3.1 | May 2024 | European Passenger Information Accessibility Profile (EPIAP) | [Code](https://github.com/NeTEx-CEN/NeTEx/releases/tag/v1.3.1) | [Release Notes](https://github.com/NeTEx-CEN/NeTEx/blob/v1.3.1/README.md) |
85-
| 2.0 | 2024 | Upcoming release ⏳ | N/A | N/A |
86-
## Full Version History 📚
87-
The comprehensive versions history is available in [change_log.md](https://github.com/ITxPT/NeTEx/blob/NeTEx/change_log.md)
116+
117+
## Change log 📰
118+
119+
### Releases
120+
| Release Number | Release Date | Description | Link |
121+
| -------------- | ------------- | ---------------------------------------------- | ------------- |
122+
| v1.2 | March 2022 | Before the extension to alternative modes of operation | [Code](https://github.com/NeTEx-CEN/NeTEx/releases/tag/v1.2) |
123+
| v1.2.2 | August 2023 | With the inclusion of NeTEx Part 5 (Alternative modes) | [Code](https://github.com/NeTEx-CEN/NeTEx/releases/tag/v1.2.2) |
124+
| v1.2.3 | May 2024 | Improvement on the v1.2.2 before the release of NeTEx Part 6 (EPIAP) | [Code](https://github.com/NeTEx-CEN/NeTEx/releases/tag/v1.2.3) |
125+
| v1.3.1 | May 2024 | Release of NeTex Part 6, the European Passenger Information Accessibility Profile (EPIAP) | [Code](https://github.com/NeTEx-CEN/NeTEx/releases/tag/v1.3.1) |
126+
| v2.0.0 | February 2026 | Matches the CEN documentation published in February 2026 for NeTEx Parts 1, 2, 3 and 5. Considered as the latest version of NeTEx to be used for production. | [Code](https://github.com/NeTEx-CEN/NeTEx/releases/tag/v2.0.0) |
127+
128+
**Important notes:**
129+
- Releases (and their tags) are a snapshot of the corresponding working branch in time.
130+
- For any official reference to a NeTEx version, it is recommended to point to a 2-digit version (e.g., v1.3, v2.0).
131+
- For any development work, it is recommended to use the latest 3-digit version of NeTEx XML Schema.
132+
133+
### Comprehensive version history
134+
The comprehensive versions history is available in [change_log.md](https://github.com/NeTEx-CEN/NeTEx/blob/v2.0/change_log.md)

0 commit comments

Comments
 (0)