NeTEx Framework

Version Frame

In a NeTEx XML Document, NeTEx data is organized within containers known as VERSION FRAMEs. These version frames serve as structured repositories for various types of related data elements within specific functional areas.

Types of VERSION FRAMEs

1. ServiceFrame: This frame encompasses data related to the transport network, including:

   • ScheduledStopPoint
   • Line
   • Route
   • Other relevant elements

2. TimeTableFrame: Specifically designed for data related to ServiceJourney that make up a timetable.

3. ServiceCalendarFrame: Contains DayTypes and other elements that define temporal conditions applicable to other data elements.

4. CompositeFrame: This frame allows you to group other frames, although nesting of frames is not supported. Within a specific frame, elements of different types (e.g., stops, lines, journeys) are organized under specific tags, often named in the plural form of the content element (e.g., scheduledStopPoints for ScheduledStopPoint elements).

5. GeneralFrame: This versatile frame can contain elements of any type in any order.

Data Consistency and Validity

It's important to maintain data consistency and coherence within a given frame. Additionally, all data within a frame is subject to any ValidityCondition associated with that frame.

Example

Here's an example of a simple ServiceFrame containing a Line and two scheduledStopPoints.

  <ServiceFrame version="1.0" id="epd:UK:myb:ServiceFrame_UK_PI_NETWORK:Line_3:myb" 
 			dataSourceRef="myb:Mybus" responsibilitySetRef="myb:tariffs">
 		<Name>Netwrok elements for Mybus Line 3</Name>
 	        <TypeOfFrameRef ref="fxc:UK:DFT:TypeOfFrame_UK_PI_NETWORK:FXCP" versionRef="fxc:v1.0"/>
		<codespaces>
			<CodespaceRef ref="naptStop_data"/>
		</codespaces>
		<prerequisites>
			<ResourceFrameRef version="1.0" 
					ref="epd:UK:MYBUS:ResourceFrame_UK_PI_COMMON:MYBUS:myb"/>
		</prerequisites>
		<!--==== LINEs ==== -->
		<lines>
			<Line version="1.0" id="myb:Line_3">
				<Name>Mybus 3</Name>
				<Description>Alpha - -Gamma</Description>
				<PublicCode>3</PublicCode>
				<PrivateCode type="noc_data">METR_1</PrivateCode>
				<OperatorRef version="1.0" ref="noc:MYBUS">137122</OperatorRef>
				<LineType>local</LineType>
				<PaymentMethods>cash</PaymentMethods>
			</Line>
		</lines>
		<!--==== STOP POINTs ==== -->
		<scheduledStopPoints>
			<ScheduledStopPoint version="naptStop:any" id="naptStop:4400CY0037">
				<Name>Alpha</Name>
				<TopographicPlaceView>
					<TopographicPlaceRef versionRef="nptg:any" ref="nptgLocality:E0056633"/>
					<Name>Barchester</Name>
					<QualifierName>Barsetshire</QualifierName>
				</TopographicPlaceView>
			</ScheduledStopPoint>
			<ScheduledStopPoint version="naptStop:any" id="naptStop:4400CY0038">
				<Name>Beta</Name>
				<TopographicPlaceRef versionRef="nptg:any" ref="nptgLocality:E0056633"/>
			</ScheduledStopPoint>
			<ScheduledStopPoint version="naptStop:any" id="naptStop:4400CY0039">
				<Name>Gama</Name>
				<TopographicPlaceRef versionRef="nptg:any" ref="nptgLocality:E0056633"/>
			</ScheduledStopPoint> 
		</scheduledStopPoints>
	</ServiceFrame>

Transmodel Definition

A VERSION FRAME is a set of Version referring to the same DataSource and belonging to the same TypeOfFrame. A FRAME may be restricted by ValidityCondition.

Specific Frame Types

Frame Type	Description
CompositeFrame	Container for grouping other frames.
ResourceFrame	Common elements such as Organisations and Responsibility Sets.
SiteFrame	Elements defining the places relevant to the transport network.
ServiceFrame	Elements defining the transport network.
TimeTableFrame	Elements making up a timetable.
FareFrame	Elements defining transport Fare Products and Prices.
ServiceCalendarFrame	Contains DayTypes and other temporal conditions.
GeneralFrame	Can contain any element in any order.

Further Points

Organizing Frames

Frames may have dependencies on other frames. Key points regarding frame organization include:

• Frames of any type can appear in any order within a NeTEx XML document.
• There may be more than one instance of a given type of frame within a CompositeFrame.

Frame Defaults

Frames can have various default values that apply to all their content elements unless overridden individually. For example, defaults can include the Codespace and the currency used for financial amounts. Frames may also be classified with a TypeOfFrame, which is useful for indicating the specific NeTExProfile being used.

Tips & Hints

• It's recommended to place default values on the frame rather than repeating them for each individual element.
• Consider specifying an overall ValidityCondition, typically a specific ValidBetween condition on a CompositeFrame, to indicate that all the data within it is subject to the same condition. Note that this overall frame condition shall not be confused with any contentValidityConditions for the frame, as these declare shared conditions used by multiple specific elements within the frame, but do not necessarily apply to all elements in the frame.

Codespaces

What is a CODESPACE?

A CODESPACE defines the context within which an identifier of an object in a document is unique, essentially serving as a namespace for data. In NeTEx, it's crucial to ensure that identifiers remain unique and stable throughout an object's lifecycle because data in NeTEx comes from multiple sources and stakeholders, is exchanged repeatedly, and may be integrated in various ways.

In NeTEx, the structure of an identifier is indicated by its CODESPACE, which establishes a unique context for a specific code structure. Multiple CODESPACEs can be used within a document.

Examples of CODESPACES

Each CODESPACE has a unique identifier, and here are some fictional examples of CODESPACE PREFIXES used for different identifiers:

• <TopographicPlace id="nptgLocality:E00034531">, where 'nptgLocality' represents http://naptan.org.uk/nptgLocality
• <ScheduledStopPoint id="smirt:454e74">, where 'smirt' represents http://www.hdfmobilites.fr/smirt/stops
• <Line id="llp:22">, where 'llp' represents http://llp.sl/lines
• <Route id="enturRoute:985a">, where 'entRoute' represents http://www.entur.org/routes
• <ServiceJourney id="db:107678">, where 'db' represents http://bahn.de/reise
• <StopPlace id="ratpStop:43289">, where 'raptStop' represents http://ratp.fr
• <StopPlace id="naptStop:199G98765431">, where 'naptStop' represents http://naptan.org.uk/stops

Declaring a CODESPACE

A CODESPACE is specified as a path expression using internet domains that have a mechanism for registering global uniqueness, such as tfl.gov.uk, foo.com, or xxx.de. These can be declared within a frame.

Example

Here's an example that demonstrates the declaration of two CODESPACEs in a VERSION FRAME, with one set as the default for the frame:

<CompositeFrame version="3.0" id="epd:UK:FYOR:CompositeFrame-UK_PI_LINE_OFFER:FYOR@26"
               responsibilitySetRef="frst:data">
    <codespaces>
        <Codespace id="frst_data">
            <Xmlns>frst</Xmlns>
            <XmlnsUrl>https://www.firstgroup.com/york</XmlnsUrl>
            <Description>First data</Description>
        </Codespace>
        <Codespace id="fxc_metadata">
            <Xmlns>fxc</Xmlns>
            <XmlnsUrl>http://netex.org.uk/fxc</XmlnsUrl>
            <Description>FXC metadata</Description>
        </Codespace>
        <CodespaceRef ref="epd_data"/>
    </codespaces>
    <FrameDefaults>
        <DefaultCodespaceRef ref="frst_data"/>
        <DefaultResponsibilitySetRef version="any" ref="frst:data"/>
    </FrameDefaults>

Further Insights

• CODESPACEs in NeTEx enable an economical way of encoding identifiers in an XML document, eliminating the need to repeat a common prefix for each element.

• If a CODESPACE is the default for a frame, it can be omitted from elements within that frame.

• A CODESPACE may imply additional rules for the internal format of the code, but such rules are external to NeTEx and must be agreed upon by implementers of data producers and consumers.

• CODESPACEs make NeTEx neutral to the identifier systems used, allowing the concurrent existence of many different code systems within the same document.

• Applications processing NeTEx documents are expected to understand any rules specific to interpreting a particular CODESPACE.

Managing Distributed Allocation of Codes

CODESPACE ASSIGNMENTs can be associated with ADMINISTRATIVE ZONE to reserve specific prefixes or code value ranges for allocating identifiers to new entities within those zones. This allows for the distributed allocation of codes to different organizations responsible for various administrative areas.

Combining Different Element Types

A single CODESPACE may cover multiple types of different elements, provided that identifiers and class contexts remain unique within it.

For example, different types of elements in the UK National Public Transport Gazetteer have distinct scopes and can be placed in a single 'NaPTAN' CODESPACE.