Service Network Input Data format (XML)

In this section of the manual we discuss the service network’s XML input format used by PLANit.

• If you are only interested to see an example file, jump to the Expanded Example.
• XML Schema of service network https://www.goplanit.orgplanitmanual.github.io/version//xsd/servicenetworkinput.xsd

<servicenetwork>

A Service Network can be described in a stand alone XML file - only describing the service network characteristics - or as part of a PLANit XML file describing all input components. Either way, all services that exist on a given parent physical transport network are defined within its XML root element <servicenetwork>. When part of a larger (single) PLANit input file, the structure should resemble something like the following:

<PLANit	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xmlns:gml="http://www.opengis.net/gml"											
		xsi:noNamespaceSchemaLocation="https://planitmanual.github.io/version/<version>/xsd/servicenetworkinput.xsd">
	<servicenetwork>
		...
	</servicenetwork>
	...
</PLANit>

Whereas if, it is a stand-alone file, it should look something like

<servicenetwork
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	 xmlns:gml="http://www.opengis.net/gml"
	 xsi:noNamespaceSchemaLocation="https://planitmanual.github.io/version/<version>/xsd/servicenetworkinput.xsd">
...	
</servicenetwork>

This root element has an id and parent network element as well as one or more service network layers corresponding to parent network physical layers:

The id and parent network elements contain a number referring to the service network’s identifier, and parent physical network’s identifier it is built on top on. Thisi s madnatory since the service network components reference physical network components when defining its network structure in terms of service nodes and service legs.

The service network layer element(s) contain the actual definitions of the service network and relate to the physical layer(s) of the parent physical network they are built on.

In the remainder of this page, we discuss each of the service network XML elements in order of expected appearance in detail. We explore their attributes, sub-elements, or simple elements (elements without sub-elements). At the bottom of the page an expanded example is provided highlighting all the available options explicitly.

XML Elements

This section discusses the (complex) XML elements under the <servicenetwork> root element in expected order of appearance.

<servicenetworklayer>

Each physical layer in the reference parent physical network can have services defined on them by having a service network layer defined. Each service network layer references exactly one parent network physical layer and inherits its supported modes implicitly.

A service network layer has the following attributes:

A service network layer - like a physical layer - has nodes and links, although in this case, they are termed service nodes (locations where a service is accessible), service legs (interactions between nodes utilised by a service of some sort), and service leg segments (the directional component of a service leg).

All Geo-location information is derived from the parent layer.

<> <servicenodes>

All service nodes available in this service network are defined within this element. This element has the following sub-elements:

<><> <servicenode>

Each service node is also a physical node on the references physical network layer. It represents a location where one or more services are accessible and would typically represent - for example - a bus stop, a train platform, a parking lot, or warehouse. As a result the number of service nodes is by definition a subset of the number of physical nodes in a network.

Each Service node has the following attributes:

<> <servicelegs>

Service legs are non-directional connections between two service nodes. Each service leg can hold two service leg segments, where each service leg segment has a single (opposing) direction. The biggest different with a physical link is that a service leg comprises one or more physical links, meaning that a leg can be longer than a single (physical) link. For example, a bus service that is not stopping at every intersection, or is regional and covers a large route with few stops, requires only limited legs, but each leg between service nodes spans many physical links.

by defining all routed services in terms of legs rather than physical links, the services are abstracted out from the physical network, and can be defined in a more compact form. Also legs used by multiple services can be reused instead of duplicatnig the sequence of links in every service

This element has the following sub-elements:

<><> <leg>

A service leg is a non-directional connection between two service nodes (service node a and service node b). A service leg can hold two service leg segments, where each service leg segment has a single (opposing) direction. Its geometry (and length) is derived from its parent physical links its references. A service leg can reference one or more physical links which are to be referenced in logical contiguous order starting at nodearef and ending with physical link towards nodebref.

When a service leg comrpises more than one physical link, it means that the intermediate physical nodes are not used by the services that use this leg

It has a unique identifier, i.e., (XML) id that is set via an attribute, the same goes for the referencing of the underlying physical links:

This element has the following sub-elements:

<!--  Example of service leg supporting both directions and comprising of 4 physical links -->
<leg id="1" externalid="someid" nodearef="1" nodebref="2" lrefs="13,22,23,67">
   <legsegment id="1" dir="a_b" />
   <legsegment id="2" dir="b_a" />         
</leg>

<><><> <legsegment>

A service leg segment is a directional version of a service leg between its two service nodes (a and b). This direction can be from a to b, or b to a depending on the configuration. There can however only be a single link segment in either direction for each link. All other information is derived from the underlying physical link (segments).

The direction is specified as an attribute, and each service leg segment has a unique user defined identifier, i.e., XML id that is set via an attribute:

Expanded Example

Below you will find an expanded example where all elements and attributes are explicitly set, to give you an idea of the overall structure of the service network XML. This example does not make sense as an actual input file, it is purely meant to show off all aspects of the file, rather than be used as a practically feasible input file.

<?xml version="1.0" encoding="ISO-8859-1"?>
<servicenetwork xmlns:gml="http://www.opengis.net/gml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<path_to_schema>/servicenetworkinput.xsd">
  <id>1</id>
  <parentnetwork>1</parentnetwork>
  <!-- multiple service network layers can be defined for a service network. However each service network is 1:1 mapped to a physical network via its parent network reference -->
  <servicenetworklayer id="1" parentlayerref="1">
    <!-- each service network layer is mapped 1:1 to a network layer of the physical network -->
    <!-- service nodes reference a physical node for which a service is accessible -->
    <servicenodes>
      <servicenode id="1" externalid="someid" noderef="1" />
    </servicenodes>
    <!-- service legs are links between service nodes (from/to) where multiple legs between the same service nodes are possible as long as the underlying physical link segments represent. A leg reflects a path on the underlying physical network via its lrefs (link refs) and leg segments -->
    <servicelegs>
      <leg id="1" externalid="someid" nodearef="1" nodebref="2" lrefs="11,22,33">
         <legsegment id="1" dir="a_b" />
         <legsegment id="2" dir="b_a" />         
      </leg>
      <leg id="2" nodearef="2" nodebref="3" lrefs="44,45,46">
         <legsegment id="3" dir="a_b" />         
      </leg>      
    </servicelegs>
  </servicenetworklayer>
</servicenetwork>