User:RailML Coord Documentation/TT:annotation

From railML 2 Wiki
Jump to navigation Jump to search
đŸ—’ïž this is a preview of page TT:annotation as to circumvent Template:Unlock. The preview is made with Template:Frame.

Is anymething missing?
purge this page.
purge the framed page.



annotation
 


Scheme description / Schemenbeschreibung

Position of annotation in the XML-Tree / Position von annotation im XML-Baum

Multiplicity / Anzahl

[1..∞]

Semantics / Bedeutung

(introduced with version 2.2) The Element <annotation> element contains texts and messages dedicated for a passenger information system.
(introduced with version 2.5) Extended with version 2.5: annotation may also encode images and symbols. Additionally meta-information regarding the annotation may be provided, allowing apart from categorization to distinguish between the different use cases that can be supported by this element.

(introduced with version 2.2) Das Element <annotation> enthĂ€lt Texte und Nachrichten zur Übermittlung an ein Fahrgastinformationssystem.
(introduced with version 2.5) Erweitert mit Version 2.5: auch Bilder und Symbole können mit annotation kodiert werden. ZusĂ€tzlich können Meta-Informationen angegeben werden, die neben einer Klassifizierung auch eine Unterscheidung der Informationen fĂŒr die verschiedenen Use Cases die durch dieses Element unterstĂŒtzt werden, erlauben.

Attributes of annotation / Attribute von annotation

  • 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.
  • code (introduced with version 2.1): Machine-interpretable string (e.g. an abbreviation) used for identification of the object across exchange partners, usecase specific uniqueness constraints may apply. Please see our description of the differences between id, code and human-readable identifiers.
    Maschineninterpretierbare Zeichenkette (z.B. AbkĂŒrzung), die zur Identifizierung des Objekts auch bei Austauschpartnern verwendet wird, wobei spezifische EindeutigkeitsbeschrĂ€nkungen gelten können. Bitte beachten Sie unsere ErlĂ€uterung zu den Unterschieden zwischen id, code and menschenlesbaren Kennzeichnungen.
  • name: Established, human-readable short string, giving the object a name. Not intended for machine interpretation, please see our notice on human interpretable data fields.
    Etablierte, menschenlesbare kurze Zeichenkette, die das Objekt benennt. Nicht zur maschinellen Interpretation bestimmt, siehe Hinweise zu menschenlesbaren Datenfeldern.
  • description: Human-readable, more detailed description as addition to the name. It should give additional explanations or hints to the contents of this element. Not intended for machine interpretation, please see our notice on human interpretable data fields.
    Menschenlesbare, detailliertere Beschreibung als ErgÀnzung zu name. Sie soll zusÀtzliche ErlÀuterungen oder Hinweise auf den Inhalt dieses Elements geben. Nicht zur maschinellen Interpretation bestimmt, siehe Hinweise zu menschenlesbaren Datenfeldern.
  • xml:lang (introduced with version 2.1): This is a unique identifier of language. It uses basically the language standard IETF BCP 47 (external link) which may be different to ISO 639-1 (external link) or ISO 639-2 (external link). For mapping hints see relation to other standards (external link).
    This defines the language used for name and description. Use Template:Ra:Tag to provide a name and/or description in other languages.
  • type (introduced with version 2.5): Enumeration of:
    • text annotation encodes textual information
    • symbol annotation encodes a symbol, e.g. bicycle symbol for trains allowing transport of bicycles or restaurant symbol for trains that include a restaurant car.
    • image annotation encodes an image, e.g. a logo for the train of some kind

Syntactic Constraints / Syntaktische BeschrÀnkungen

  • 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 (_)
  • code: xs:string, optional
  • name: xs:string, optional
  • description: xs:string, optional
  • xml:lang: xs:language, language identification, optional
  • type: tAnnotationType (xs:string, generic type for annotation types: enumeration text, symbol, image); default: text; optional

Best practice & Examples / Empfohlene Anwendung & Beispiele

How to use code with <annotation> of type image

Starting with version 2.5 it is possible to also describe images as annotations. To do so the type of an <annotation> is set to image. In order to communicate which image is actually meant with the annotation the attribute code may be used. As with all usages of code the exact handling is not standardized by railML¼ and thus needs to be discussed between producer and consumer of the railML¼ document. However there are two “Best practice” ways of using them.

Reference by file

The first way of using code here is by specifying a relative file path. This is most useful when shipping the railMLÂź document as a zip archive. In this case the image resource can be provided along with the actual document.

Reference by key

If the above approach is not suitable there is another way is to provide a key value as code that can be resolved in the consuming system. In order to do that of course the key values need to be synchronized between producer and consumer.

Below both ways of referencing an image are shown as an example: 

<timetable id="tt01">
  ...
  <annotations>
    <annotation 
      id="annotationWithCodeContainingRelativePath" 
      type="image" 
      name="image for childrens play area" 
      code="./images/ChildrensPlayArea.png"/>
    <annotation 
      id="annotationWithCodeContainingKey" 
      type="image" 
      name="image for restaurant car" 
      code="IMG-RESTAURANT"/>
  </annotations>
  ...
</timetable>

Usage of subelement <text>

If the attribute @type is specified with the value text it is possible to specify the related strings per language with the available sub element <text>. Doing so will help reading programs to easily understand what needs to be done if a reference to such <annotation>is detected. No further clarification between producer and consumer of the data is needed.
It is however also possible to omit specifying the texts in question but rather indicate to the reading system via the attribute @code which text resources to use when encountering a reference to this <annotation>. Of course, this requires further discussion between producer and consumer so that the used codes are understood and kept in sync between the involved systems.

Notes / Anmerkungen

Not yet described. / Noch nicht beschrieben.

Open issues / Offene Punkte/Pendenzen

Not yet described. / Noch nicht beschrieben.

Retrieved from "https://wiki2.railml.org/index.php?title=User:RailML_Coord_Documentation/TT:annotation&oldid=14432"