Dev:Syntactic Guidelines

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"?>

Subversion properties and keywords

see Subversion Guidelines for new files

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

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 page. Ferri 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">