Dev:Identities: Difference between revisions

From railML 3 Wiki
Jump to navigation Jump to search
[unchecked revision][unchecked revision]
Line 1: Line 1:
= {{rml}} Identities =
= {{rml}} Identities =


Very many {{rml}} elements require an {{Attr|id}} attribute of the W3C-Type {{RailMLType|tGenericID}}.
Very many {{rml}} elements require an {{Attr|id}} attribute of the W3C-Type {{external|http://www.w3.org/TR/xmlschema-2/#ID|xs:ID}}.


This has to be provided in order to enable references, that are very much used within the {{rml}} schemas.
This has to be provided in order to enable references, that are very much used within the {{rml}} schemas.
Line 11: Line 11:
The general {{rml}} description states the following semantics for this attribute.
The general {{rml}} description states the following semantics for this attribute.


{{InheritId
* {{Attr|id}}: XML-file-wide unique, machine-interpretable identity, required for later referencing that element internally. For a detailed explanation see [[Dev:identities]].<br>{{deu|XML-Datei-weit eindeutige, maschineninterpretierbare Identität, die für die spätere interne Referenzierung dieses Elements erforderlich ist. Für eine detaillierte Erklärung siehe [[Dev:identities]].}} {{AddAnn|{{{id|}}}|{{{id_de|}}} }}
|id = {{{id|}}}
|id_de = {{{id_de|}}}
}}


== Constraints ==
== Constraints ==
Line 20: Line 17:
The general {{rml}} description states the following contraints.
The general {{rml}} description states the following contraints.


{{InheritIdConstraints}}
* {{Attr|id}}: {{external|http://www.w3.org/TR/xmlschema-2/#ID|xs:ID}}, required<br>a string, starting with a letter (a..zA..Z) or an underscore (_), <br>followed by a non-colonized and non-spaced string consisting of letters, digits, points (.), dashes (-) or underscores (_)


== Export of {{rml}} files ==
== Export of {{rml}} files ==

Revision as of 10:08, 14 August 2020

railML® Identities

Very many railML® elements require an id attribute of the W3C-Type xs:ID (external link).

This has to be provided in order to enable references, that are very much used within the railML® schemas.

On the other hand, software tools may refer to certain railML® elements, that are not referred to within the railML® file.

Semantics

The general railML® description states the following semantics for this attribute.

  • id: XML-file-wide unique, machine-interpretable identity, required for later referencing that element internally. For a detailed explanation see Dev:identities.
    XML-Datei-weit eindeutige, maschineninterpretierbare Identität, die für die spätere interne Referenzierung dieses Elements erforderlich ist. Für eine detaillierte Erklärung siehe Dev:identities.

Constraints

The general railML® description states the following contraints.

  • id: xs:ID (external link), required
    a string, starting with a letter (a..zA..Z) or an underscore (_),
    followed by a non-colonized and non-spaced string consisting of letters, digits, points (.), dashes (-) or underscores (_)

Export of railML® files

Software tools, which create railML® files, are free to define id values according to the above mentioned constraints.

Recommendation

railML® recommends using generic values, e.g.

<operationalPoint id="d2e717">...

or serial numbers with letter prefixes, e.g.

<operationalPoint id="op0002">...

or UUID's (Wiki banner.png), e.g.

<operationalPoint id="04b6f736-23f7-429c-be8a-e286172de2c1">...

Please note: a Nil UUID (Wiki banner.png) shall not be used; UUID's Version 4 (Wiki banner.png) is commonly used.

Bad style

Sometimes exporting software tools create id values, that contain semantic data, like names, designators, train numbers or vehicle family codes.

<operationalPoint id="op-TDM">
  <name name="Tidmouth" language="en-UK"/>
  <designator register="_NWR" entry="TDM"/>
  ...

Please use some more generic coding style in order to not invite the importing software to parse the id values!

Wrong style

If the semantic information is only included in the id, the importing software has to parse the id value in order to use it.
<operationalPoint id="op-TDM">...

This coding style hinders interoperability!

 

Please use a generic coding style for the id value. Look for appropriate railML® attributes in the element and put the semantics there. Otherwise use the xs:anyAttribute mechanism.

The use of this Wrong style prevents certification of the export interface.

Import of railML® files

Recommendation

Software tools, which consume railML® files, should take the id values only for referencing issues.

In case of valid railML® files, no problems will occur.

Good style

In case of consuming "good or bad styled" id values the importing software provides routines for getting the semantics from better fitting attributes.

In case of consuming "wrong styled" id values the importing software is required to parse the attribute content for getting the semantics.

That way, the most robust import interface is assured.

Wrong style

The importing software expects to parse the id value with a special regular expression in order to get the coded semantics.

That way, "good styled" id values can't be imported!

 


The use of this Wrong style prevents certification of the import interface.

Differentiation from other indications

Many elements that come with an attribute id will also have the child element <name>, with attributes name and description.

  • name: A short, human readable Identifier. Uniqueness is not required.
  • description: Human readable text that gives details. Uniqueness is not required.
💡 Please be aware that human-readable attributes are only intended to forward simple remarks/explanations from one end-user to another end-user. They are not to be used to contain computer-processable data, nor shall it be parsed by programmes in any way. In case of semantical overlaps or discrepancies to machine processable file contents, any machine processable contents have priority over possible human interpretable contents. However, these attributes may be used to transmit complementary details to machine processable parameters.

Bitte, berücksichtigen Sie, dass menschenlesbare Attribute nur für einfache Kommentare/Erklärungen von Endbenutzer zu Endbenutzer bestimmt sind. Sie sind nicht für maschineninterpretierbare Daten gedacht und werden nicht geparst. Im Falle semantischer Überschneidungen oder Widersprüche zu maschinenlesbaren Inhalten wird diesen der Vorzug gegenüber durch Menschen lesbaren gegeben. Allerdings können durch Menschen lesbare Felder für Ergänzungen zu maschinenlesbaren verwendet werden.