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>.

This root element has an id and parent (physical) 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. This is mandatory 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 represents a (virtual) 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.

A service node may service multiple services (possibly of different modes) and therefore it may reflect multiple physical nodes. This relation is implicit and can be derived from its connected service leg segments that do carry an explicit relation to their underlying physical link segments.

Each Service node has the following attributes:

<> <servicelegs>

A service leg is a non-directional connection between a pair of 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 duplicating 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. It has no geometry nor length, those are to be extracted from the leg segments since these rely on their underlying physical link segments for this information.

When a service leg comprises 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. Geometry (and length) is derived from its parent physical link segments its references. A service leg can reference one or more physical link segments which are to be referenced in logical contiguous order starting at nodearef of the service leg and ending with physical link towards nodebref (if in ab direction and vice versa).

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 are different. 
    A leg reflects a path on the underlying physical network via its lsrefs (link segment refs) per service leg segment -->
    <servicelegs>
      <leg id="1" externalid="someid" nodearef="1" nodebref="2">
         <legsegment id="1" dir="a_b" lsrefs="11,22,33" />
         <legsegment id="2" dir="b_a" lsrefs="33,24, 26, 11" />         
      </leg>
      <leg id="2" nodearef="2" nodebref="3">
         <legsegment id="3" dir="a_b" lsrefs="44,45,46"/>         
      </leg>      
    </servicelegs>
  </servicenetworklayer>
</servicenetwork>