Dev:Syntactic Guidelines: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
[checked revision][checked revision]
(syntax)
m (deleted link to subversion)
 
(2 intermediate revisions by one other user not shown)
Line 1: Line 1:
== Newly created files ==
== Newly created files ==


=== Byte order mark (BOM) ===
=== Byte order mark (BOM) ===


<p>For more information about the "Byte Order Mark" see {{external|http://en.wikipedia.org/wiki/Byte_order_mark|Wikipedia: Byte Order Mark (BOM)}}</p>
<p>For more information about the "Byte Order Mark" see {{external|https://en.wikipedia.org/wiki/Byte_order_mark|Wikipedia: Byte Order Mark (BOM)}}</p>


<p>As recommended by the W3C, an UTF-8 encoded file should not start with an BOM for less troubles with editors and browsers, see also {{external|http://www.w3.org/International/questions/qa-byte-order-mark.en.php|W3C Recommandation about BOM}}</p>
<p>As recommended by the W3C, an UTF-8 encoded file should not start with an BOM for less troubles with editors and browsers, see also {{external|https://www.w3.org/International/questions/qa-byte-order-mark.en.php|W3C Recommandation about BOM}}</p>


<p>Visualization tip for BOM (command line tool): <tt>less $FILENAME$</tt></p>
<p>Visualization tip for BOM (command line tool): <tt>less $FILENAME$</tt></p>
<pre><U+FEFF><?xml version="1.0" encoding="UTF-8"?></pre>
<pre><U+FEFF><?xml version="1.0" encoding="UTF-8"?></pre>


=== Subversion properties and keywords ===
<p>see [[Dev:Subversion_Guidelines#Add_new_files|Subversion Guidelines for new files]]</p>


== Camel Case ==
== Camel Case ==
Line 54: Line 52:
<p>Each component has to be fully declared on one line without line breaks.</p>
<p>Each component has to be fully declared on one line without line breaks.</p>
<p>example:
<p>example:
<pre><xs:schema xmlns:rail="http://www.railml.org/schemas/2009" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:dc="http://purl.org/dc/elements/1.1/" targetNamespace="http://www.railml.org/schemas/2009" elementFormDefault="qualified" version="2.0"></pre>
<pre><xs:schema xmlns:rail="https://www.railml.org/schemas/2009" xmlns:xs="https://www.w3.org/2001/XMLSchema" xmlns:dc="https://purl.org/dc/elements/1.1/" targetNamespace="https://www.railml.org/schemas/2009" elementFormDefault="qualified" version="2.0"></pre>
</p>
</p>


Line 61: Line 59:
=== Empty elements and attributes ===
=== Empty elements and attributes ===


<p>see also: {{external|http://www.w3.org/TR/REC-xml/#NT-EmptyElemTag|W3C XML Recommendation "Tags for Empty Elements"}}</p>
<p>see also: {{external|https://www.w3.org/TR/REC-xml/#NT-EmptyElemTag|W3C XML Recommendation "Tags for Empty Elements"}}</p>
<p>Implementation with shortened syntax instead of extra closing tag</p>
<p>Implementation with shortened syntax instead of extra closing tag</p>
<p>example: <pre><xs:element ref="rail:infrastructure" minOccurs="0" /></pre></p>
<p>example: <pre><xs:element ref="rail:infrastructure" minOccurs="0" /></pre></p>
Line 69: Line 67:
=== Optional and required attributes ===
=== Optional and required attributes ===


<p>see also: {{external|http://www.w3.org/TR/xmlschema-1/#declare-attribute|W3C XML Schema Recommendation "XML Representation of Attribute Declaration Schema Components"}}</p>
<p>see also: {{external|https://www.w3.org/TR/xmlschema-1/#declare-attribute|W3C XML Schema Recommendation "XML Representation of Attribute Declaration Schema Components"}}</p>


==== Implementation without <code>use="optional"</code> ====
==== Implementation without <code>use="optional"</code> ====
Line 81: Line 79:
=== Elements with minimum 1 or maximum 1 occurrence ===
=== Elements with minimum 1 or maximum 1 occurrence ===


<p>see also: {{external|http://www.w3.org/TR/xmlschema-1/#declare-element|W3C XML Schema Recommendation "XML Representation of Element Declaration Schema Components"}}</p>
<p>see also: {{external|https://www.w3.org/TR/xmlschema-1/#declare-element|W3C XML Schema Recommendation "XML Representation of Element Declaration Schema Components"}}</p>


==== Implementation without <code>minOccurs="1"</code> ====
==== Implementation without <code>minOccurs="1"</code> ====
Line 108: Line 106:
=== Attribute <code>xsi:schemaLocation</code> ===
=== Attribute <code>xsi:schemaLocation</code> ===


<p>see also: {{external|http://www.w3.org/TR/xmlschema-1/#schema-loc|W3C XML Schema Recommendation "How schema definitions are located on the Web"}}</p>
<p>see also: {{external|https://www.w3.org/TR/xmlschema-1/#schema-loc|W3C XML Schema Recommendation "How schema definitions are located on the Web"}}</p>


==== Implementation with slashes, no backslashes permitted ====
==== Implementation with slashes, no backslashes permitted ====


<p>example:<pre><railml xmlns="http://www.railml.org/schemas/2009" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.railml.org/schemas/2009 ../schema/railML.xsd"></pre>
<p>example:<pre><railml xmlns="https://www.railml.org/schemas/2009" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://www.railml.org/schemas/2009 ../schema/railML.xsd"></pre>
</p>
</p>


[[Category:GeneralDescription]]
[[Category:GeneralDescription]]

Latest revision as of 09:51, 14 November 2023

Newly created files

Byte order mark (BOM)

For more information about the "Byte Order Mark" see Wikipedia: Byte Order Mark (BOM) (external link)

As recommended by the W3C, an UTF-8 encoded file should not start with an BOM for less troubles with editors and browsers, see also W3C Recommandation about BOM

Visualization tip for BOM (command line tool): less $FILENAME$

<U+FEFF><?xml version="1.0" encoding="UTF-8"?>


Camel Case

Always use camel case for all names. Don't mix with dashed naming schemas.

White spaces

Empty end-tags

Implementation with 1 space before closing empty end-tags

example:

<xs:restriction base="xs:ID" />

Indents

Implementation with 2 spaces

example:

<xs:element name="railml">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="metadata" type="dc:elementContainer" minOccurs="0" />
      <xs:element ref="rail:infrastructure" minOccurs="0" />

Line Breaks

Each component declaration must be followed by a line break.

example:

<xs:attributeGroup name="aPlaces">
  <xs:attribute name="category" type="rail:tPlaceCategory" use="required" />
  <xs:attribute name="count" type="rail:tCounter" use="required" />

There is no maximum line length

Outdated.png Part of the article content is outdated since version 2.0. As to avoid confusion, a current example should be used. Please update this article to reflect recent events or newly available information. Possibly, you will find further details on the discussion pageFerri Leberl (Diskussion) 14:10, 29. Jun. 2016 (CEST)

Each component has to be fully declared on one line without line breaks.

example:

<xs:schema xmlns:rail="https://www.railml.org/schemas/2009" xmlns:xs="https://www.w3.org/2001/XMLSchema" xmlns:dc="https://purl.org/dc/elements/1.1/" targetNamespace="https://www.railml.org/schemas/2009"	elementFormDefault="qualified" version="2.0">

XML Default Values

Empty elements and attributes

see also: W3C XML Recommendation "Tags for Empty Elements"

Implementation with shortened syntax instead of extra closing tag

example:

<xs:element ref="rail:infrastructure" minOccurs="0" />

XML Schema Default Values

Optional and required attributes

see also: W3C XML Schema Recommendation "XML Representation of Attribute Declaration Schema Components"

Implementation without use="optional"

example:

<xs:attribute name="description" type="rail:tElementDescription" />

Implementation with use="required"

example:

<xs:attribute name="id" type="rail:tGenericID" use="required" />

Elements with minimum 1 or maximum 1 occurrence

see also: W3C XML Schema Recommendation "XML Representation of Element Declaration Schema Components"

Implementation without minOccurs="1"

example:

<xs:element name="train" type="rail:eTrain" maxOccurs="unbounded" />

Implementation without maxOccurs="1"

example:

<xs:element ref="rail:timetable" minOccurs="0" />

Occurence restrictions into elements

If possible, all occurence restrictions have to go into element definitions.

xs:sequence should stand without the attributes minOccurs and/or maxOccurs.

example:

<xs:extension base="rail:tElementWithIDAndName">
  <xs:sequence>
    <xs:element name="metadata" type="dc:elementContainer" minOccurs="0" />
  </xs:sequence>

Pathes inside XML documents

Attribute xsi:schemaLocation

see also: W3C XML Schema Recommendation "How schema definitions are located on the Web"

Implementation with slashes, no backslashes permitted

example:

<railml xmlns="https://www.railml.org/schemas/2009" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://www.railml.org/schemas/2009 ../schema/railML.xsd">