Difference between revisions of "XMLValidation"

From Sumo
Jump to navigation Jump to search
(schema declarations)
Line 1: Line 1:
 
= Validation of XML inputs =
 
= Validation of XML inputs =
 +
All [[Sumo_at_a_Glance#Included_Applications|SUMO applications]] support XML validation for their inputs. To enable this, the following options can be used:
 +
 +
{| class="wikitable" style="width:90%"
 +
|-
 +
! style="background:#ddffdd; vertical-align:top; width:350px" | Option
 +
! style="background:#ddffdd; vertical-align:top" | Description
 +
|-
 +
| style="vertical-align:top" | {{Option|-X {{DT_STR}}}}<br/> {{Option|--xml-validation {{DT_STR}}}}
 +
| style="vertical-align:top" | Set schema validation scheme of XML inputs ("never", "auto" or "always"); ''default: '''auto'''''
 +
|-
 +
| style="vertical-align:top" | {{Option|--xml-validation.net {{DT_STR}}}}
 +
| style="vertical-align:top" | Set schema validation scheme of SUMO network inputs ("never", "auto" or "always"); ''default: '''never'''''
 +
|-
 +
|}
 +
 +
Validation is performed by activating [https://xerces.apache.org/xerces-c/schema-3.html XML schema processing] in the XML parser.
 +
This catches many common input errors such as spelling mistakes and attributes which should have been placed within another element.
 +
 +
Another prerequisite for validation is a schema deceleration within the root element of the input file such as 
  
The [[XMLValidation|XML validation]] options enable [https://xerces.apache.org/xerces-c/schema-3.html XML schema processing] in the XML parser. This performs a basic validation of the input and is highly recommended especially for beginners because it easily finds spelling mistakes in the input which otherwise might be silently ignored. Be sure that your input files have a header like
 
 
<pre class="xml">
 
<pre class="xml">
 
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://sumo.dlr.de/xsd/routes_file.xsd">
 
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://sumo.dlr.de/xsd/routes_file.xsd">
 
</pre>
 
</pre>
because only if the schema is mentioned explicitly validation will occur (unless you enforce it using the "always" mode). For details see [[XMLValidation]]
+
 
 +
When setting the validation options to ''always'' it is an error to omit this declaration.
  
 
Schema validation may slowdown XML parsing considerably and is therefore disabled for the network input by default (because networks should not be edited by hand and therefore be valid anyway). If you have large auto-generated inputs you may consider disabling schema validation altogether. See also [[FAQ#What.27s_the_deal_with_schema_resolution_warnings_.2F_errors.3F|this FAQ]].
 
Schema validation may slowdown XML parsing considerably and is therefore disabled for the network input by default (because networks should not be edited by hand and therefore be valid anyway). If you have large auto-generated inputs you may consider disabling schema validation altogether. See also [[FAQ#What.27s_the_deal_with_schema_resolution_warnings_.2F_errors.3F|this FAQ]].
  
== Adding a schema declaration manually ==
+
== Adding a schema declaration ==
 +
Files that are written by one of the SUMO applications automatically receive the appropriate schema declaration.
 +
When writing an input file from scratch the schema declaration must be added manually to the root element as follows:
 +
<pre class="xml">
 +
<ROOT_ELEMENT xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 +
    xsi:noNamespaceSchemaLocation="http://sumo.dlr.de/xsd/SCHEMA_TYPE.xsd">
 +
</pre>
 +
 
 +
where ''ROOT_ELEMENT'' and ''SCHEMA_TYPE'' should be set according to the following table:
 +
 
 +
{| class="wikitable" style="width:90%"
 +
|-
 +
! style="background:#ddffdd; vertical-align:top; width:350px" | Application Option
 +
! style="background:#ddffdd; vertical-align:top" | ROOT_ELEMENT
 +
! style="background:#ddffdd; vertical-align:top" | SCHEMA_TYPE
 +
|-
 +
| style="vertical-align:top" | {{Option|--route-files {{DT_STR}}}}, {{Option|--trip-files {{DT_STR}}}}, , {{Option|--flow-files {{DT_STR}}}}
 +
| style="vertical-align:top" | routes
 +
| style="vertical-align:top" | routes_file
 +
|-
 +
|}
 +
 
 +
{{Note|The value of ''ROOT_ELEMENT'' is a matter of convention and may take an arbitrary value.}}

Revision as of 11:28, 4 November 2015

Validation of XML inputs

All SUMO applications support XML validation for their inputs. To enable this, the following options can be used:

Option Description
-X <STRING>
--xml-validation <STRING>
Set schema validation scheme of XML inputs ("never", "auto" or "always"); default: auto
--xml-validation.net <STRING> Set schema validation scheme of SUMO network inputs ("never", "auto" or "always"); default: never

Validation is performed by activating XML schema processing in the XML parser. This catches many common input errors such as spelling mistakes and attributes which should have been placed within another element.

Another prerequisite for validation is a schema deceleration within the root element of the input file such as

<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://sumo.dlr.de/xsd/routes_file.xsd">

When setting the validation options to always it is an error to omit this declaration.

Schema validation may slowdown XML parsing considerably and is therefore disabled for the network input by default (because networks should not be edited by hand and therefore be valid anyway). If you have large auto-generated inputs you may consider disabling schema validation altogether. See also this FAQ.

Adding a schema declaration

Files that are written by one of the SUMO applications automatically receive the appropriate schema declaration. When writing an input file from scratch the schema declaration must be added manually to the root element as follows:

<ROOT_ELEMENT xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:noNamespaceSchemaLocation="http://sumo.dlr.de/xsd/SCHEMA_TYPE.xsd">

where ROOT_ELEMENT and SCHEMA_TYPE should be set according to the following table:

Application Option ROOT_ELEMENT SCHEMA_TYPE
--route-files <STRING>, --trip-files <STRING>, , --flow-files <STRING> routes routes_file
Note:
The value of ROOT_ELEMENT is a matter of convention and may take an arbitrary value.