Skip to content

SIRI XML schema

Jump to bottom
Eliot edited this page Nov 3, 2023 · 34 revisions

SIRI XML document structure

A SIRI XML document is a computer file containing XML data that adheres to the SIRI schema. It must have a root Siri 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 SIRI schema and satisfies key referential integrity constraints specified by the SIRI XML Schema

Below is an example

<Siri xmlns="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0" xsi:schemaLocation="http://www.siri.org.uk/siri ../../xsd/siri.xsd">

Notation for XML model structures of SIRI messages

General

In the SIRI documentation, SIRI XML structures are shown in a tabular form. A separate table is used for each major SIRI request and response message; additional tables are used for the major child elements making up a complex message. To save space, table headings are not repeated on individual tables, but are shown only in the example. The tables use a consistent set of conventions to describe the XML elements and their constraints.

Example of XML structure notation

Organizational Group Name of Element Min : Max Data Type Description
MessageResponse +Structure Returns data for a Message Request
Attributes srsName 0:1 xsd:string Default GML coordinate format for any spatial points defined in response by Coordinates parameter
Log ResponseTimestamp 1:1 xsd:dateTime Time individual response element was created
Endpoint ProducerRef 0:1 ➡️ ParticipantCode Participant reference that identifies producer of data. May be available from context
Endpoint ::: 0:1 AddGroup MyAddress Group elements
Status Status 0:1 xsd:boolean Whether the complete request could be processed successfully or not. Default is true
Status ErrorCondition 0:1 See below Description of any error or warning conditions that apply to the overall request
Status choice One of the following Error codes
Status a)CapabilityNotSupportedError -1:1 + Error Error: Capability not supported
Status b)OtherError -1:1 + Error Error other than a well defined category
Status Description 0:1 ➡️ ErrorDescription Description of Error
Payload ExpectedLifeTime 1:1 PositiveDurationType How long I expect to live. Time interval
Payload MyWay 0:1 foo bar Which way I did it. Default is ´foo´
Payload XxxDelivery 0:* +Structure See SIRI Part 3 - Functional Service and SIRI Framework

Classification

This first column specifies the category of the item, e.g. 'Payload'. and corresponds to the description of the object itself, independently of any accompanying data and other items.

For example:

  • Attributes
  • Log
  • Endpoint
  • Status
  • Payload

Different types of flow

Request

ProductionTimetableRequest +Structure Information request on ordered/theoretical timetables
Attribute Version 1:1 VersionString Service ProductionTimetable version
Endpoint properties RequestTimestamp 1:1 xsd:dateTime Request emission date
Endpoint properties MessageIdentifier 0:1 MessageQualifier Message identification number
Line Topic ValidityPeriod 0:1 ClosedDateRangeStructure Period for which you want the timetable information
Line Topic Start 1:1 xsd:dateTime Period start date and time
Line Topic End 1:1 xsd:dateTime Period end date and time
Line Topic TimetableVersionRef 0:1 xsd:string Known version of the theoretical reference system: only deviations from this will be transmitted
Line Topic OperatorRef 0:* ➡️ OperatorCode Identify the operator(s) for whom you wish to obtain information
Line Topic LineRef 0:1 ➡️ LineCode Identify the line for which you want the information

Example of information request on ordered/theoretical timetables

Below is an XML example of ProductionTimetableRequest element with the architecture mentioned above

<Siri xmlns="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0" xsi:schemaLocation="http://www.siri.org.uk/siri ../../xsd/siri.xsd">
 <ServiceRequest>
  <!--======ENDPOINT REFERENCES================================-->
  <RequestTimestamp>2004-12-17T09:30:47-05:00</RequestTimestamp>
  <RequestorRef>NADER</RequestorRef>
  <ProductionTimetableRequest version="2.0">
   <RequestTimestamp>2001-12-17T09:30:47-05:00</RequestTimestamp>
   <ValidityPeriod>
    <StartTime>2001-12-17T14:20:00</StartTime>
    <EndTime>2001-12-18T14:20:00</EndTime>
   </ValidityPeriod>
   <TimetableVersionRef>002</TimetableVersionRef>
   <OperatorRef>Smooth</OperatorRef>
   <Lines>
    <LineDirection>
     <LineRef>123</LineRef>
     <DirectionRef>Outbound</DirectionRef>
    </LineDirection>
   </Lines>
  </ProductionTimetableRequest>
 </ServiceRequest>
</Siri>

Subscription

ProductionTimetableSubscriptionRequest +Structure Request for a subscription to Production Timetable Service SIRI service
Identity SubscriberRef 0:1 1:1 ➡️ParticipantCode System requestor identifier
Identity SubscriptionIdentifier 1:1 SubscriptionQualifier Subscription identifier for the system requestor
Lease InitialTerminationTime 1:1 xsd:dateTime Subscription end date and time
Request ProductionTimetableRequest 1:1 +Structure See ProductionTimeTableRequest

Example of subscription to ordered/theoretical timetable information

Below is a XML example of ProductionTimetableSubscriptionRequest with the architecture mentioned above

<Siri xmlns="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0" xsi:schemaLocation="http://www.siri.org.uk/siri ../../xsd/siri.xsd">
 <SubscriptionRequest>
  <!--======ENDPOINT REFERENCES================================-->
  <RequestTimestamp>2004-12-17T09:30:47-05:00</RequestTimestamp>
  <RequestorRef>NADER</RequestorRef>
  <!-- Subscriptiont 1  for VIS123 to Place 975 -->
  <ProductionTimetableSubscriptionRequest>
   <SubscriberRef>NADER</SubscriberRef>
   <SubscriptionIdentifier>0000456</SubscriptionIdentifier>
   <InitialTerminationTime>2001-12-17T09:30:47-05:00</InitialTerminationTime>
   <ProductionTimetableRequest version="2.0">
    <RequestTimestamp>2001-12-17T09:30:47-05:00</RequestTimestamp>
    <ValidityPeriod>
     <StartTime>2001-12-17T14:20:00</StartTime>
     <EndTime>2001-12-18T14:20:00</EndTime>
    </ValidityPeriod>
    <TimetableVersionRef>002</TimetableVersionRef>
    <OperatorRef>Smooth</OperatorRef>
    <Lines>
     <LineDirection>
      <LineRef>123</LineRef>
      <DirectionRef>Outbound</DirectionRef>
     </LineDirection>
    </Lines>
   </ProductionTimetableRequest>
  </ProductionTimetableSubscriptionRequest>
 </SubscriptionRequest>
</Siri>

Response

ProductionTimeTableDelivery +Structure Provides the applicable races for a route
Attribute Version 1:1 VersionString Production Timetable service version number, integrating le profile version number
LEADER :: 1:1 xxDelivery
Payload DatedTimetableVersionFrame 0:* +Structure

Example

Below is an XML example of ProductionTimetableDelivery with the architecture mentioned above.

<Siri xmlns="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0" xsi:schemaLocation="http://www.siri.org.uk/siri ../../xsd/siri.xsd">
 <ServiceDelivery>
  <!--=======HEADER================================================== -->
  <ResponseTimestamp>2004-12-17T09:30:46-05:00</ResponseTimestamp>
  <ProducerRef>KUBRICK</ProducerRef>
  <Status>true</Status>
  <MoreData>false</MoreData>
  <!--=======PAYLOAD============================================== -->
  <ProductionTimetableDelivery version="2.0">
   <ResponseTimestamp>2001-12-17T09:30:47-05:00</ResponseTimestamp>
   <SubscriberRef>NADER</SubscriberRef>
   <SubscriptionRef>00123456</SubscriptionRef>
   <Status>true</Status>
   <ValidUntil>2001-12-17T10:30:47-05:00</ValidUntil>
   <DatedTimetableVersionFrame>
    <RecordedAtTime>2001-12-17T09:30:47-05:00</RecordedAtTime>
    <VersionRef>1.1</VersionRef>
    <!-- JP Info Group -->
    <LineRef>123</LineRef>
    <DirectionRef>Out</DirectionRef>
    <PublishedLineName xml:lang="EN">String</PublishedLineName>
    <DirectionName xml:lang="EN">Outbound</DirectionName>
    <!-- Service Info Group -->
    <OperatorRef>Smooth</OperatorRef>
    <ProductCategoryRef>AllCats</ProductCategoryRef>
    <ServiceFeatureRef>CyclesPermitted</ServiceFeatureRef>
    <VehicleFeatureRef>LowStep</VehicleFeatureRef>
    <LineNote>Special services at Easter</LineNote>
    <!-- Timetable real-time info Group -->
    <Monitored>true</Monitored>
    <DatedVehicleJourney>
     <!-- Identity Group -->
       [...]
    </DatedVehicleJourney>
   </DatedTimetableVersionFrame>
  </ProductionTimetableDelivery>
 </ServiceDelivery>
</Siri>

More information

The structure examples mentioned above are applicable to the Production Timetable SIRI service, and they may vary depending on the specific service. You can also find additional structure examples here.

SIRI schema overview

The SIRI XML schema is encoded as a W3C .xsd schema. It is modularized into a number of several reusable sub schemas and type packages. The schema is and has been, validated against mainstream validators and there are working applications using common tools.

Referencing the SIRI Schema in the XML Documents

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

XML document validation with SIRI

XML document validation is the process of verifying a given XML document against its schema to ensure its correctness.

To be validated successfully, an XML document shall be both:

Validation Requirement Status
Well-formed comprise a set of tags that are syntactically correct XML so that it can be parsed ✅
Valid conform to any constraints expressed in the document as to data type and integrity of reference ✅

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 shall 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:

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 SIRI XML schema

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

Constraint / Integrity Description
Domain constraints SIRI defines several domain constraints for its XML elements and attributes. For example, the VehicleRef element must contain a reference to a valid vehicle, and the ArrivalExpectedTime element must contain a valid time value.
Entity integrity SIRI defines several entity integrity constraints for its XML entities. For example, the Vehicle entity must have a unique identifier.
Referential integrity SIRI defines several referential integrity constraints for its XML entities. For example, the VehicleJourneyRef element must contain a reference to a valid vehicle journey.
Key constraints SIRI defines several key constraints for its XML elements and attributes. For example, the StopPointRef element must have a unique identifier within a given route.
  1. What is SIRI
  2. SIRI framework
  3. Versioning
  4. SIRI XML schema
  5. Structure & Compatibility
  6. Using SIRI
  7. Software & tools
  8. References
Clone this wiki locally