Integration of a UML visualization into the railML 3 wiki
The railML schemas are all defined from the needs of all partners. While from 2008 to 2020 railML 2 was defined directly in XML Schema Definition (XSD), railML 3 was from the beginning defined in the Unified Modeling Language (UML) and the XSD was derived from it. The now in railML 3 wiki integrated UML visualizations can be found here.
Putting XML, XSD and UML in a context
XML stands for eXtensible Markup Language and is a text-based data format – Thus, XML data is human-readable. There are various XML dialects – one of them is railML – which each describe an own structure. That technically readable description of the structure of a particular XML dialect is an XSD. Even though it looks quite similar with the text within angle brackets, the key difference between XML and XSD is that XML is a markup language that is a flexible method of creating and sharing data over incompatible systems while XSD is used to define the structure and the content of an XML document.
UML is a set of standardized diagram types that can be used to describe the behaviour and structure of software. There are, for example, the so-called class diagrams, which can describe the structure of software or sequence diagrams, which describe what is processed in a software in which way or Use Case diagrams that describe the general requirements of a software.
To sum this up, XML is defined by XSD, which in turn is derived from UML.
For example, here an XSD of a track can be see, whereas this is a corresponding UML.
UML in railML’s wiki
The railML 3 wiki is still primarily dedicated to documenting the XSD schema, since this continues to be the authoritative standard in which data can be exchanged via railML. With a catchy image of a school, it could be explained like this: A principal could take a large sheet of paper and create the students timetable on it - This case can be compared to the direct definition of railML 2 in XSD. However, the principal could also create the timetable with a suitable program, in which he enters the conditions (number of teachers, number of classes, subjects, legal framework), and the program generates a timetable. This is then printed out and is binding in the printed form. This case can be prepared with the indirect definition of the scheme via UML. If the program would have printed a slightly different timetable, which also fulfils the conditions, then this timetable would be binding.
So, although it makes sense to continue documenting the XSD representation in the wiki instead of the UML representation, a user might be interested in the underlying UML to better understand the intent and relationships in case of any questions or problems. We have now taken this into account.
And what is all this for?
It was a lot of work, but so far, the UML visualizations for the railML 3 subschemas Common, Interlocking and Infrastructure, as well as the corresponding RailTopoModel and Geography Markup Language are available in the wiki3. This helps one to be able to understand the modelling, but also to create own databases, so that the incoming data fit the database.
As mentioned above, when railML 2 was modelled, it was done directly in XSD, but later on for some parts regarding railDAX the UML was created – If the community thinks that it can be helpful to have other parts in UML, as well, this can be realized.
All UML visualizations can be accessed via https://wiki3.railml.org/wiki/Dev:UML.