Dev:identities: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[checked revision][checked revision]
(→‎Recommendation: Limitation in railML 2 added.)
(→‎Recommendation: sharpened)
(18 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= railML Identities =
= {{rml}} Identities =


Very much railML 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 {{RailMLType|tGenericID}}.


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


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


== Semantics ==
== Semantics ==


The general railML description states the following semantics for this attribute.
The general {{rml}} description states the following semantics for this attribute.


{{InheritId
{{InheritId
Line 18: Line 18:
== Constraints ==
== Constraints ==


The general railML description states the following contraints.
The general {{rml}} description states the following contraints.


{{InheritIdConstraints}}
{{InheritIdConstraints}}


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


Software tools, which create railML files, are free to define {{Attr|id}} values according to the above mentioned constraints.
Software tools, which create {{rml}} files, are free to define {{Attr|id}} values according to the above mentioned constraints.


=== Recommendation ===
=== Recommendation ===


railML recommends using generic values, e.g.
{{rml}} recommends using generic values, e.g.


<pre><formation id="d2e717" name="TGV-ICE3">...</pre>
<pre><formation id="d2e717" name="TGV-ICE3">...</pre>


or serial numbers with letter prefixes, e.g.
=== Other workable methods ===
;serial numbers with letter prefixes
e.g.
<pre><formation id="rsf0002" name="TGV-ICE3">...</pre>
<pre><formation id="rsf0002" name="TGV-ICE3">...</pre>


or [https://en.wikipedia.org/wiki/Universally_unique_identifier UUID]'s, e.g.
;UUID's
<pre><formation id="f36014b1-055d-4171-91a4-2a32a3210f28" name="TGV-ICE3">...</pre>.''(Please note: a [https://en.wikipedia.org/wiki/Universally_unique_identifier#Nil_UUID Nil UUID] shall not be used; [https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random) UUID's Version 4] is commonly used. Due to the limitations of the ID type by www.w3.org in {{rml}} 2 the ID shall begin with a letter!)''
(see {{wiki|Universally_unique_identifier|UUID}}), e.g.
<pre><formation id="_f36014b1-055d-4171-91a4-2a32a3210f28" name="TGV-ICE3">...</pre>''Please note: a {{external|https://en.wikipedia.org/wiki/Universally_unique_identifier#Nil_UUID|Nil UUID}} shall not be used; {{external|https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)|UUID's Version 4}} is commonly used. Due to the limitations of the ID type by www.w3.org in {{rml}} 2 the ID shall begin with a letter. <!--Since this is not the case for all UUIDs, some tools are adding the prefix "_" before the UUID to fufil the constraints.''
 
-->Since UUIDs can start as well with letters as with numbers and in railML 2.x IDs are XML IDs (which, according to the specification, must not start with numbers), the UUIDs in railML 2.x had to be started with an underscore. In railML 3, the ID was defined differently so that this necessity no longer exists.
 
{{deu|Da UUIDs sowohl mit Buchstaben als mit Zahlen beginnen können und in railML 2.x IDs XML-IDs sind (die laut Spezifikation nicht mit Zahlen beginnen dürfen) mussten die UUIDs in railML 2.x mit einem Unterstrich begonnen werden. In railML 3 wurde die ID anders definiert, sodass diese Notwendigkeit nicht mehr besteht.}}


=== Bad style ===
=== Bad style ===


Sometimes exporting software tools create {{Attr|id}} values, that contain semantic data, like train numbers or vehicle family codes.
Sometimes exporting software tools create {{Attr|id}} values, that contain semantic data, like train numbers or vehicle family codes.
Only if this semantic information is repeated in separate attributes of the same element, the importing software is not required to parse this {{Attr|id}} value.


<pre><formation id="fTGV-ICE3" name="TGV-ICE3">...</pre>
<pre><formation id="fTGV-ICE3" name="TGV-ICE3">...</pre>
Line 49: Line 54:


=== Wrong style ===
=== Wrong style ===
{{note|If the semantic information is not separated, the importing software has to parse the {{Attr|id}} value in order to use it.
{{note|If the semantic information is only included in the {{Attr|id}}, the importing software would have to parse the {{Attr|id}} value in order to use it.


<pre><formation id="fTGV-ICE3">...</pre>
<pre><formation id="fTGV-ICE3">...</pre>
Line 55: Line 60:
This coding style hinders interoperability!
This coding style hinders interoperability!
|error}}
|error}}
Please use a generic coding style for the {{Attr|id}} value. Look for appropriate railML attributes in the element and put the semantics there. Otherwise use the [[CO:usingAny#New_attributes_.28Use_of_xs:anyAttribute.29|xs:anyAttribute mechanism]].
Please use a generic coding style for the {{Attr|id}} value. Look for appropriate {{rml}} attributes in the element and put the semantics there. Otherwise use the [[CO:usingAny#New_attributes_.28Use_of_xs:anyAttribute.29|xs:anyAttribute mechanism]].


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


== Import of railML files ==
== Import of {{rml}} files ==


=== Recommendation ===
=== Recommendation ===


Software tools, which consume railML files, should take the {{Attr|id}} values only for referencing issues.
Software tools, which consume {{rml}} files, should use the {{Attr|id}} values only for cross-referencing between elements in the imported file. When UUIDs are used, the {{Attr|id}}s can also provide valid references across files and data sources.


In case of valid railML files, no problems will occur.
In case of valid {{rml}} files, no problems will occur.


=== Good style ===
=== Good style ===
Line 71: Line 76:
In case of consuming "good or bad styled" {{Attr|id}} values the importing software provides routines for getting the semantics from better fitting attributes.
In case of consuming "good or bad styled" {{Attr|id}} values the importing software provides routines for getting the semantics from better fitting attributes.


In case of consuming "wrong styled" {{Attr|id}} values the importing software is required to parse the attribute content for getting the semantics.
In case of consuming "wrong styled" {{Attr|id}} values the importing software is not required to extract semantics encoded in the {{Attr|id}} value.
 
That way, the most robust import interface is assured.


=== Wrong style ===
=== Wrong style ===
{{note
{{note
|The importing software expects to parse the {{Attr|id}} value with a special regular expression in order to get the coded semantics.
|The importing software expects to parse the {{Attr|id}} value, e.g. with a special regular expression, in order to get the coded semantics, and fails when such information is not present in the {{Attr|id}}.
 
That way, "good styled" {{Attr|id}} values can't be imported!
|error}}
|error}}


The use of this '''Wrong style''' prevents certification of the import interface.
The use of this '''Wrong style''' prevents certification of the import interface.
= Differentiation from other indications =
Many elements that have the {{attr|id}} attribute will also support the attributes {{attr|code}}, {{attr|name}} and {{attr|description}}. Each of these attributes has a separate purpose.
* {{attr|code}}: Like {{attr|id}} it is a machine readable identifier, but while an {{attr|id}} only identifies an element within a single {{rml}} file, so that it can be referenced from other elements in the same file, a {{attr|code}} is designed for interoperability between data exchange partners. An {{attr|id}} ''is not'' a stable reference: the same physical object will likely have different {{attr|id}}s in different files (unless you are using [[#Export_of_railML.C2.AE_files|UUIDs]]). A {{attr|code}} ''is'' a stable identifier for a given element across files. While an {{attr|id}} is syntactically required to be unique within a file, there is no such syntactical constraint on a {{attr|code}}. However, as it is an identifier, a {{attr|code}} should help the data exchange partners correctly and unambiguously identify an object. As a consequence, use case specific uniqueness requirements may be agreed between exchange partners. As an example, a {{attr|code}} may be valid and unique within a national network.
* {{attr|name}}: A short, human readable identifier. Uniqueness is not required. Its value should help a human reader separate the object from other (similar) objects. For instance, it can be displayed as a label to the user of a graphical software tool, a header in printed information or as a column in tabular representations.
* {{attr|description}}: Human readable text that gives additional details not given by the {{attr|name}}. Uniqueness is not required. It may contain remarks, explanations and hints about the contents of the object.
{{note|Please be aware that human-readable attributes are only intended to forward displayable names and simple remarks/explanations from one end-user to another end-user. They are not to be used to contain computer-processable data. Software can display the contents of these attributes to the user without modification, e.g. as a label on an object, but must never parse or interpret the contents in any way. Note that this means that, in case of discrepancies between machine processable and human readable 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.
{{deu|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.}}|reminder}}


[[Category:GeneralDescription]]
[[Category:GeneralDescription]]
[[category:Common Concept]]
[[category:Common Concept]]
{{interwiki}}

Revision as of 14:37, 18 July 2022

railML® Identities

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

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, 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.

<formation id="d2e717" name="TGV-ICE3">...

Other workable methods

serial numbers with letter prefixes

e.g.

<formation id="rsf0002" name="TGV-ICE3">...
UUID's

(see UUID (Wiki banner.png)), e.g.

<formation id="_f36014b1-055d-4171-91a4-2a32a3210f28" name="TGV-ICE3">...

Please note: a Nil UUID (external link) shall not be used; UUID's Version 4 (external link) is commonly used. Due to the limitations of the ID type by www.w3.org in railML® 2 the ID shall begin with a letter. Since UUIDs can start as well with letters as with numbers and in railML 2.x IDs are XML IDs (which, according to the specification, must not start with numbers), the UUIDs in railML 2.x had to be started with an underscore. In railML 3, the ID was defined differently so that this necessity no longer exists.

Da UUIDs sowohl mit Buchstaben als mit Zahlen beginnen können und in railML 2.x IDs XML-IDs sind (die laut Spezifikation nicht mit Zahlen beginnen dürfen) mussten die UUIDs in railML 2.x mit einem Unterstrich begonnen werden. In railML 3 wurde die ID anders definiert, sodass diese Notwendigkeit nicht mehr besteht.

Bad style

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

<formation id="fTGV-ICE3" name="TGV-ICE3">...

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 would have to parse the id value in order to use it.
<formation id="fTGV-ICE3">...

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 use the id values only for cross-referencing between elements in the imported file. When UUIDs are used, the ids can also provide valid references across files and data sources.

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 not required to extract semantics encoded in the id value.

Wrong style

The importing software expects to parse the id value, e.g. with a special regular expression, in order to get the coded semantics, and fails when such information is not present in the id.


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

Differentiation from other indications

Many elements that have the id attribute will also support the attributes code, name and description. Each of these attributes has a separate purpose.

  • code: Like id it is a machine readable identifier, but while an id only identifies an element within a single railML® file, so that it can be referenced from other elements in the same file, a code is designed for interoperability between data exchange partners. An id is not a stable reference: the same physical object will likely have different ids in different files (unless you are using UUIDs). A code is a stable identifier for a given element across files. While an id is syntactically required to be unique within a file, there is no such syntactical constraint on a code. However, as it is an identifier, a code should help the data exchange partners correctly and unambiguously identify an object. As a consequence, use case specific uniqueness requirements may be agreed between exchange partners. As an example, a code may be valid and unique within a national network.
  • name: A short, human readable identifier. Uniqueness is not required. Its value should help a human reader separate the object from other (similar) objects. For instance, it can be displayed as a label to the user of a graphical software tool, a header in printed information or as a column in tabular representations.
  • description: Human readable text that gives additional details not given by the name. Uniqueness is not required. It may contain remarks, explanations and hints about the contents of the object.
💡 Please be aware that human-readable attributes are only intended to forward displayable names and simple remarks/explanations from one end-user to another end-user. They are not to be used to contain computer-processable data. Software can display the contents of these attributes to the user without modification, e.g. as a label on an object, but must never parse or interpret the contents in any way. Note that this means that, in case of discrepancies between machine processable and human readable 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.