Skip to content

XML Schemas

Jump to bottom
Eliot edited this page Oct 9, 2023 · 13 revisions

NeTEx XML Document Structure

A NeTEx XML document is a computer file containing XML data that adheres to the NeTEx schema. It must have a root PublicationDelivery element that indicates the schema and version to which the document conforms. The document can then be validated against the schema to ensure correctness, meaning it is well-formed XML that conforms to the NeTEx schema and satisfies key referential integrity constraints specified by the NeTEx XML Schema.

Structure of the PublicationDelivery Element

The PublicationDelivery element consists of two sections:

1. Header

The header contains a timestamp and an optional PublicationRequest element that describes the document's contents.

2. Payload

The payload includes a dataObjects tag, within which the "payload" content of the document is structured. This content is organized using tags from the NeTEx schema in the prescribed order and format. In most cases, VersionFrames are used as the top-level elements to group related content.

Example

Here's an example of a PublicationDelivery element with a header and a payload containing a COMPOSITE FRAME that includes several other frames of different types (detailed contents not shown):

 
<PublicationDelivery version="ntx:1.1"
	xsi:schemaLocation=http://www.netex.org.uk/netex NeTEx_publication.xsd
	xmlns="http://www.netex.org.uk/netex"
	xmlns:xlink="http://www.w3.org/1999/xlink"
	xmlns:ifopt="http://www.ifopt.org.uk/ifopt"
	xmlns:gml=http://www.opengis.net/gml/3.2
	xmlns:core=http://www.govtalk.gov.uk/core
	xmlns:siri=http://www.siri.org.uk/siri
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<!--==== HEADER ==== -->
		<PublicationTimestamp>2001-12-17T09:30:47.0Z</PublicationTimestamp>
		<ParticipantRef>mysis:SYS001</ParticipantRef>
		<PublicationRequest version="1.0">
			<RequestTimestamp>2001-12-17T09:30:47.0Z</RequestTimestamp>
			<topics>
				<NetworkFrameTopic>
					<Current/>
					<NetworkFilterByValue>
						<objectReferences>
							<TypeOfFrameRef ref="fxc:UK_PI_LINE_OFFER" versionRef="1.0" /> 
							<OperatorRef version="1.0" ref="noc:METR"/>
							<LineRef ref="mb:Line@1"/> 
						</objectReferences>
						<places>
							<CountryRef ref="uk" refPrincipality="iso1366-2:GB-ENG"/>
							<TopographicPlaceRef
								 ref="nptgLocality:E0054812">Crawley<’TopographicPlaceRef>
						</places> 
				</NetworkFilterByValue>
			</NetworkFrameTopic>
		</topics>
		</PublicationRequest>
		<!--==== PAYLOAD ==== -->
		<dataObjects>
			<CompositeFrame version="3.0" id="epd:UK: METR:CompositeFrame_UK_PI_LINE_OFFER:Line-1:mb”
						reponsibilityetRef="mb:timetable_data"/>
				<ValidBetween>
					<FromDate>2019-01-01T09:02:30.0Z</FromDate>
					<ToDate>2020-01:01T00:02:30.0Z</ToDate>
				</ValidBetween>
				<TypeOfFrameRef ref="fxc:UK_PI_LINE_OFFER" versionRef="1.0" />
				<codespaces>
					<Codespace id="mb_data">
						<Xmlns>mb</Xmlns>
						<XmlnsUrl>http://www.metrobus.co.uk/</XmlnsUrl>
						<Description>Metrobus data</Description>
					</Codespace>		
					<CodespaceRef id="fxc_metadata">fxc</CodespaceRef>
					<CodespaceRef id="epip_data">epd</CodespaceRef>
				</codespaces>
				<FrameDefaults>
					<DefaultResponsibilitySetRef ref="mb:timetable_data"/>
					<DefaultCodespaceRef ref="fxc_data"/>
				</FrameDefaults
				<frames>
					<SiteFrame version="2.1" id="epd:UK:METR:SiteFrame_UK_PI_STOP:Line@1:mb">
						<TypeOfFrameRef ref="fxc:UK_PI_STOP" versionRef="1.0" />
							<prerequisites>
								<ResourceFrameRef version="any" ref="epd:UK:METR:ResourceFrame_UK_PI_COMMON:Line@1"/>
							</prerequisites>

						::::: Etc., etc., Specific Frame contents :::::
					</SiteFrame>

					<ServiceFrame version="2.1" id=“epd:UK:METR:ServiceFrame_UK_PI_NETWORK:Line@1:mb">
						<TypeOfFrameRef ref="fxc:UK_PI_NETWORK" versionRef="1.0" />
						::::: Etc., etc., Specific Frame contents :::::
					</ServiceFrame>

					<TimetableFrame version="2.4" id="epd:UK:METR:TimetableFrame_UK_PI_TIMETABLE:Line@1:mb”>
						<TypeOfFrameRef ref="fxc:UK_PI_TIMETABLE" versionRef="1.0" />
							<prerequisites>
							<ServiceCalendarFrameRef version="any" ref=”epd:UK:METR::ServiceCalendarFrame_UK_PI_CALENDAR:Line@1:mb-"/>
							</prerequisites>

						::::: Etc., etc., Specific Frame contents :::::
					</TimetableFrame>

	                                <ServiceCalendarFrame version="1.6" id="epd:UK:METR:ServiceCalendarFrame_UK_PI_CALENDAR:Line@1”>
						<TypeOfFrameRef ref="fxc:UK_PI_CALENDAR" versionRef="1.0" />
						::::: Etc., etc., Specific Frame contents :::::
					</serviceCalendarFrame >

					<ResourceFrame version="1.6" id="epd:UK:METR:ResourceFrame_UK_PI_COMMON:Line@1:mb”>
						<TypeOfFrameRef ref="fxc:UK_PI_COMMON" versionRef="1.0" />
						::::: Etc., etc., Specific Frame contents :::::
					</ResourceFrame>

					<ResourceFrame version="1.0" id="fxc:UK:DFT:ResourceFrame_UK_PI_METADATA:FXC">
						<TypeOfFrameRef ref="fxc:UK_PI_METADATA" versionRef="1.0" />
						::::: Etc., etc., Specific Frame contents :::::
					</ResourceFrame>
				</frames>
			</CompositeFrame>
	</dataObjects>
</PublicationDelivery

NeTEx Schema Overview

NeTEx is provided as a W3C XML schema, defined using .xsd files. This schema serves a dual purpose: it can validate NeTEx-conformant XML documents and automatically generate bindings for software tools that use NeTEx data.

Key Points About the NeTEx Schema

  • The NeTex schema is modularized into several small W3C .xsd files, each corresponding to a package in the NeTEx UML design model.
  • The Directory Structure organizes these packages within folders, aligning with the design model parts.
  • To browse or edit the NeTEx Schema, we recommend using a fully featured XML editor that can integrate the separate subfiles into an easily navigable visualization.

Note: XSD Schemas are used by validators to qualify NeTEx feeds

Referencing the NeTEx Schema in XML Documents

For an XML document to be NeTEx-conformant, it must include a reference to the root schema file (usually netex_publication.xsd).

XML Document Validation with NeTEx

XML document validation is the process of verifying a given XML document against its schema to ensure its correctness. For a document to be considered correct:

Validation Requirement Status
It must be well-formed XML, adhering to the basic rules of XML syntax. ✅
It must conform to the NeTEx XML Schema, following the specific structure and data types defined in the schema. ✅
It must also satisfy any referential integrity constraints imposed by the NeTEx schema. ✅

Validation is typically performed using automated tools.

Well Formed XML

Well-formed XML is XML that meets the basic syntax rules for XML as laid down in the EW3C specification.

Syntax Rule Status
Base data types (dates, numbers, strings, booleans) must have correct formats. ✅
All data elements must be enclosed within tags, starting with '<' and ending with '>'. ✅
Special characters must be escaped using numeric values or symbols, e.g., '&' for '&' when necessary. ✅

XML Document Conformance

An XML document is considered conformant if it successfully validates against its schema. This validation encompasses the following checks, as well as adherence to any Xml Integrity rules:

Element Validation

  • Only permitted element tags are allowed (note that some tags may allow the embedding of other schemas).
  • Mandatory elements must be present.
  • Minimum and maximum cardinalities must be satisfied.
  • All elements must appear in the required order.

Attribute Validation

  • Only permitted attributes are allowed (in any order).
  • Mandatory attributes must be present.

Data Type Validation

  • Values for enumerations must be one of the allowed values.
  • Data types must satisfy their specified format, e.g., date, time, boolean, integer, URI, etc.

Ensuring Integrity in NeTEx XML Schema

XML schemas often include constraints to ensure the elements within a document maintain integrity. Two critical aspects of integrity are:

  • Key Uniqueness: Ensuring that a specific identifier is unique within the document.
  • Referential Integrity: Ensuring that references to other elements are valid, meaning the referenced elements are declared elsewhere in the document.

Implementing Integrity Rules in NeTEx

In NeTEx, referential integrity constraints are applied at the root document, typically within the file netexPublication.xsd.

Key Constraints

In a NeTEx Xml document, each entity is considered a versioned instance. This means that the combination of its id and version attributes must be unique within the document. Key constraints are defined as follows:

  • Most DataManagedObject are required to be unique within their XML element class and version (e.g., Line, ScheduledStopPoint).
  • Certain first-class NeTEx entities are expected to be unique within their XML element superclass, for example, ADDRESS / POSTAL ADDRESS / ROAD ADDRESS (details to be added).
  • NeTEx VersionedChild must be unique within their XML element class and order number.

A convention in NeTEx allows "any" to be used as a version id when no specific version is intended.

Examples

Here are some examples illustrating unique IDs for various entities in NeTEx:

Unique ids for versions of first class entities Line and ScheduledStopStopPoint

<Line id="X43A" version="any">  :::: </Line>
<Line id="X22" version="any">  :::: </Line>

<ScheduledStopStopPoint id="A" version="any">  :::: </ScheduledStopStopPoint>
<ScheduledStopStopPoint id="B" version="any">  :::: </ScheduledStopStopPoint>
<ScheduledStopStopPoint id="C" version="any">  :::: </ScheduledStopStopPoint>

Unique ids for versions of a ServicePattern and three child entity instances StopPointInPattern.

  <ServicePattern id="foo" version="any">
     <StopPointInPattern id="foo" version="any" order="1">   <ScheduledStopStopPointRef  ref="A" version="any"/>  </StopPointInPattern>
     <StopPointInPattern id="foo" version="any" order="2">  <ScheduledStopStopPointRef  ref="B" version="any"/>  </StopPointInPattern>
     <StopPointInPattern id="foo" version="any" order="3>   <ScheduledStopStopPointRef  ref="C" version="any"/>  </StopPointInPattern>
  <ServicePattern>

Unique ids for versions of a Country and a Codespace.

     <Country id="uk" province-UK-WLS">  :::: </Country>
     <Codespace id="epip_cs"  ">  :::: </Codespace>

Referential Integrity Constraints

In NeTEx, referential integrity constraints are enforced through a uniform VersionRef mechanism used to reference entities uniquely within a document. Each reference can be viewed as the serialization of an association relationship from the representational model. There is generally a referential integrity constraint for each distinct element class.

Here are some key points about referential integrity constraints:

  • Each reference has two key attributes: ref and version.
  • References to versioned children have key attributes: ref, version, and order.

There are two special cases:

  • References to a Codespace have a single key attribute: ref.
  • References to a Country have two key attributes: ref and province.

In practice, referential integrity constraints are only validated when the key is fully specified:

  • If the version attribute is present in the reference, it will be validated.✅
  • If the version attribute is missing, the reference will not be validated. ❌

This approach allows for distinguishing between internal references (within the same NeTEx XML document) and external references (in a separate document). It provides flexibility in managing references based on specific use cases.

Examples

Example - Validated reference

The following example example shows a ServiceLink that references two different ScheduledStopPoint of a specified version.

   <scheduledStopPoints>
		<ScheduledStopPoint version="001"  id="mybus:SSP0001">
			<Name>Museum</Name> 
		</ScheduledStopPoint>

		<ScheduledStopPoint version="001"  id="mybus:SSP0002">
			<Name>Bahnhof</Name> 
		</ScheduledStopPoint>
   </scheduledStopPoints>
   <serviceLinks>
		<ServiceLink version="002"  id="mybus:SSP0001+SSP0002">
			<Distance>1.12</Distance>
			<FromPointRef version="001" ref="mybus:SSP0001"/>
			<ToPointRef version="001" ref="mybus:SSP000B"/>
		</ServiceLink>
   </serviceLinks>

Example - Unvalidated (External) reference; no version indicated

The following example shows the same link using unvalidated references.

  <serviceLinks>
   	<ServiceLink version="002"  id="mybus:SSP0001+SSP0002">
   		<Distance>1.12</Distance>
   		<FromPointRef ref="mybus:SSP0001"/>
   		<ToPointRef   ref="mybus:SSP0002"/>
   	</ServiceLink>
  </serviceLinks>

Example - Unvalidated (External) reference; with version indicated

Sometimes it is useful to indicate a version on an external reference. This can be done using the auxilliary versionRef attribute. The following example shows the same link using unvalidated external references.

   <serviceLinks>
		<ServiceLink version="002"  id="mybus:SSP0001+SSP0002">
			<Distance>1.12</Distance>
			<FromPointRef  versionRef="001"  ref="mybus:SSP0001"/>
			<ToPointRef   versionRef="001" ref="mybus:SSP0002"/>
		</ServiceLink>
</serviceLinks>

Further Points

Separate instance versions

It is possible to have two separate versions of the same entity in the same NeTEx Xml document. For example, the following is allowed

  <ScheduledStopStopPoint id="A" version="001">  <:::: </ScheduledStopStopPoint>
  <ScheduledStopStopPoint id="A" version="002">  :::: </ScheduledStopStopPoint>
  1. What is NeTEx
  2. NeTEx Framework
  3. Release history
  4. XML Schemas
  5. Structure And Compatibility
  6. Using NeTEx
  7. Software & tools
  8. References
Clone this wiki locally