Dev:Syntactic Guidelines: Difference between revisions
[checked revision] | [checked revision] |
({{mirror}}) |
m (deleted link to subversion) |
||
(One intermediate revision by one other user not shown) | |||
Line 1: | Line 1: | ||
{{ | |||
== Newly created files == | |||
=== Byte order mark (BOM) === | |||
<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|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> | |||
<pre><U+FEFF><?xml version="1.0" encoding="UTF-8"?></pre> | |||
== Camel Case == | |||
Always use camel case for all names. Don't mix with dashed naming schemas. | |||
== White spaces == | |||
=== Empty end-tags === | |||
<p>Implementation with 1 space before closing empty end-tags</p> | |||
<p>example: <pre><xs:restriction base="xs:ID" /></pre></p> | |||
=== Indents === | |||
<p>Implementation with 2 spaces</p> | |||
<p>example: | |||
<syntaxhighlight line lang="xml"> | |||
<xs:element name="railml"> | |||
<xs:complexType> | |||
<xs:sequence> | |||
<xs:element name="metadata" type="dc:elementContainer" minOccurs="0" /> | |||
<xs:element ref="rail:infrastructure" minOccurs="0" /> | |||
</syntaxhighlight> | |||
</p> | |||
== Line Breaks == | |||
=== Each component declaration must be followed by a line break. === | |||
<p>example: | |||
<syntaxhighlight line lang="xml"> | |||
<xs:attributeGroup name="aPlaces"> | |||
<xs:attribute name="category" type="rail:tPlaceCategory" use="required" /> | |||
<xs:attribute name="count" type="rail:tCounter" use="required" /> | |||
</syntaxhighlight> | |||
</p> | |||
=== There is no maximum line length === | |||
{{outdated|date=version 2.0|user=[[Benutzer:Ferri Leberl|Ferri Leberl]] ([[Benutzer Diskussion:Ferri Leberl|Diskussion]]) 14:10, 29. Jun. 2016 (CEST)|topic=As to avoid confusion, a current example should be used}} | |||
<p>Each component has to be fully declared on one line without line breaks.</p> | |||
<p>example: | |||
<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> | |||
== XML Default Values == | |||
=== Empty elements and attributes === | |||
<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>example: <pre><xs:element ref="rail:infrastructure" minOccurs="0" /></pre></p> | |||
== XML Schema Default Values == | |||
=== Optional and required attributes === | |||
<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> ==== | |||
<p>example: <pre><xs:attribute name="description" type="rail:tElementDescription" /></pre></p> | |||
==== Implementation with <code>use="required"</code> ==== | |||
<p>example: <pre><xs:attribute name="id" type="rail:tGenericID" use="required" /></pre></p> | |||
=== Elements with minimum 1 or maximum 1 occurrence === | |||
<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> ==== | |||
<p>example: <pre><xs:element name="train" type="rail:eTrain" maxOccurs="unbounded" /></pre></p> | |||
==== Implementation without <code>maxOccurs="1"</code> ==== | |||
<p>example: <pre><xs:element ref="rail:timetable" minOccurs="0" /></pre></p> | |||
=== Occurence restrictions into elements === | |||
<p>If possible, all occurence restrictions have to go into element definitions.</p> | |||
<p><code>xs:sequence</code> should stand without the attributes <code>minOccurs</code> and/or <code>maxOccurs</code>.</p> | |||
<p>example: | |||
<syntaxhighlight line lang="xml"> | |||
<xs:extension base="rail:tElementWithIDAndName"> | |||
<xs:sequence> | |||
<xs:element name="metadata" type="dc:elementContainer" minOccurs="0" /> | |||
</xs:sequence> | |||
</syntaxhighlight> | |||
</p> | |||
== Pathes inside XML documents == | |||
=== Attribute <code>xsi:schemaLocation</code> === | |||
<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 ==== | |||
<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> | |||
[[Category:GeneralDescription]] |
Latest revision as of 10: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
|
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">