Structure And Compatibility

NeTEx directory structure

The NeTEx XML schema is modularized into small W3C .xsd files, each corresponding to a package in the NeTEx UML design model. A directory structure organizes the packages in folders according to the design model parts.

A modular schema allows the selective use of just the required elements and isolates any changes to just the affected components. However, it means that the semantics are distributed over many files. In order to browse and edit the schema, the use of an XML editor such as XmlSpy or Oxygen is strongly recommended.

Folders

For each NeTEx-XML release the top level directory contains:

\schema\1.00\ReadMe.md    
\schema\1.00\ReadMe.md.html
\schema\1.00\netex-spp    [Altova XmlSpy PROJECT]
\schema\1.00\netex-xpr    [Oxygen PROJECT]

\schema\1.00\xsd                [XML schemas]

	\schema\1.00\xsd\NeTEx_publication.xsd   [XML Top level schema]
	\schema\1.00\xsd\NeTEx_publication_timetable.xsd    [XML Top level schema, timetable only]
	\schema\1.00\xsd\NeTEx_siri.xsd       [XML Top level schema with bound SIRI protocol messages]
	\schema\1.00\xsd\NeTEx_siri_SG.xsd    [XML Top level schema with bound SIRI protocol messages]
	\schema\1.00\xsd\NX.xsd               [Convenience schema for inspecting elements]
        \schema\1.00\xsd\NeTEx_publication_timetable.xsd              
        \schema\1.00\xsd\ifopt.xsd   

            [Subschemas]  [The XML schema body is broken down into modular packages - see NeTEX specification]
	\schema\1.00\xsd\gml\...
	\schema\1.00\xsd\netex_framework\... (Common Framework elements)
	\schema\1.00\xsd\netex_part_1\...
	\schema\1.00\xsd\netex_part_2\... (Timetable Model)
	\schema\1.00\xsd\netex_part_3\... (Fares Model)
        \schema\1.00\xsd\netex_part_5\... (New modes)
	\schema\1.00\xsd\netex_service\...
	\schema\1.00\xsd\siri\...
	\schema\1.00\xsd\siri_utility\...
	\schema\1.00\xsd\wsdl\...
	\schema\1.00\xsd\wsdl_model\...
	\schema\1.00\xsd\ynotation\...

\schema\1.00\examples\... [Example  xml documents]
        \schema\1.00\examples\functions\...
        \schema\1.00\examples\standards\...
        \schema\1.00\examples\ws_siri_request\...

Referencing NeTEx Schema in NeTEx XML documents

An NeTEx XML document contains data marked up with XML tags that conform to a given version of the NeTEx schema.

The schema to use to validate the document is given by the xsi:schemaLocation attribute in the document header. For example, publication.xsd in the following excerpt.

        <?xml version="1.0" encoding="UTF-8"?>
        <PublicationDelivery xmlns="http://www.netex.org.uk/netex" 
                             xmlns:gml="http://www.opengis.net/gml/3.2" 
                             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                             xmlns:siri="http://www.siri.org.uk/siri" version="1.0" 
                  xsi:schemaLocation="http://www.netex.org.uk/netex ../../../xsd/NeTEx_publication.xsd">  
	    <PublicationTimestamp>20209-12-17T09:30:46.0Z</PublicationTimestamp>
	    <ParticipantRef>SYS001</ParticipantRef>
	    <dataObjects>
		<CompositeFrame version="any" id="op:10000">
		     ::::: contents				
		</CompositeFrame>
	    </dataObjects>
        </PublicationDelivery>

Schema locations

The schema location may be

1. Relative to the document's location - as above.
2. An absolute reference (Eg http://mystuff.eu/schemas),
3. Mediated by an XML catalogue or other tool configuration mechanism to resolve schema references.

Ensuring Compatibility in NeTEx Schema Evolution

When developing new versions of software, it's highly desirable to maintain backward compatibility, which means that the software should still work with older data artifacts, such as XML documents created under previous versions. NeTEx schema evolution aims to support compatibility with previous versions.

Guidelines for Compatibility

In the context of XML schema, several considerations apply to ensuring compatibility.

The following changes can break strict XML document compatibility, causing previously valid documents to fail validation

• Changing the names of existing elements or attributes.
• Changing the values of existing enumerations (e.g., correcting typos).
• Changing the default value for an attribute.
• Deleting an existing tag.
• Deleting an existing attribute.
• Changing the order of existing elements.
• Reducing the cardinality of an existing element.
• Making an optional element mandatory.
• Making the definitions of a data type stricter (e.g., requiring a name to begin with "X").

The following change does not break strict compatibility, but changes the semantics of the interpretation.

• Adding a default value for an attribute.

The following changes do not break backwards compatibility of XML documents (but may require am updated binding)

• Adding new tags or elements.
• Adding new enumeration values to an existing element.
• Changing comments on elements.
• Adding an XML group to organize elements in the existing sequence.
• Increasing the cardinality of an existing element.
• Making a mandatory element optional (unless this introduces ambiguity with succeeding elements).
• Replacing a choice with an element whose substitution group covers all the choice elements.

Deprecated Changes

Certain changes that break strict compatibility, such as correcting the spelling of an enumeration or dropping an element or attribute, can be done in a backward-compatible way by retaining the old element or value with a "deprecated" status. The deprecated value may be dropped after a while at an appropriate major release.