Service calendars

In this chapter:

ServiceCalendarFrame
AvailabilityCondition
ServiceCalendar
DayType
Timeband
DayTypeAssignment

ServiceCalendarFrame

Purpose

Groups calendar definitions that describe when services operate - DayTypes, [operating periods, TODO we don’t define / use OperatingPeriod, do we?] and DayTypeAssignments. Wilfried 10.6.

See the following class diagram for the most important objects of the ServiceCalendarFrame and their relationships to the other frames.

classDiagram
    %% Styles
    classDef frame fill:#FFF8E1,stroke:#FFB300;
    classDef contained fill:#E8F4FF,stroke:#1E90FF;
    classDef external fill:#F6F6F6,stroke:#AAAAAA;

    %% Frame
    class ServiceCalendarFrame {
        - validityConditions : AvailabilityCondition[]
    }
    class ServiceCalendarFrame frame

    %% Contained elements
    class AvailabilityCondition {
        FromDate
        ToDate
        ValidDayBits
    }

    class DayType {

    }

    class DayTypeAssignment {
    }


    class ServiceCalendar {

    }
    class Timeband {

    }

    %% External elements (not in the frame)
    class ServiceJourney {
        
    }

    class CheckConstraint {
    }

    class FacilitySet {
    }

    class StopAssignment {
    }

    class NoticeAssignment {
         }

    %% Containment relations (only contained elements)
    ServiceCalendarFrame "1" o-- "0..*" AvailabilityCondition : contains
    ServiceCalendarFrame "1" o-- "0..*" DayType : contains
    ServiceCalendarFrame "1" o-- "0..*" DayTypeAssignment : contains
    ServiceCalendarFrame "1" o-- "0..*" ServiceCalendar : contains
    ServiceCalendarFrame "1" o-- "0..*" Timeband : contains

    %% Usage relations from external elements to AvailabilityCondition
    ServiceJourney ..> AvailabilityCondition : uses
    CheckConstraint ..> AvailabilityCondition : uses
    FacilitySet ..> AvailabilityCondition : uses
    StopAssignment ..> AvailabilityCondition : uses
    NoticeAssignment ..> AvailabilityCondition : uses

    %% Other internal links
    DayTypeAssignment --> DayType : assigns

Table

Sub	Element	Usage	Card	Type	Note
	ServiceCalendarFrame	expected	1..1	unknown	A minimal ServiceCalendarFrame must be present in all timetable files.
+	validityConditions	mandatory	1..1	unknown
++	AvailabilityCondition	mandatory	1..1	unknown
+	ServiceCalendar	expected	1..1	unknown
+	dayTypes	optional	1..1	unknown
++	DayType	optional	1..1	unknown
+	timebands	expected	1..1	unknown
++	Timeband	expected	1..1	unknown

→ General NeTEx definition

Example

<?xml version="1.0" encoding="UTF-8"?>
<ServiceCalendarFrame  id="ch:1:ServiceCalendarFrame" version="1">
  <!-- A minimal ServiceCalendarFrame must be present in all timetable files. -->
  <validityConditions>
    <AvailabilityCondition id="ch:1:AvailabilityCondition:b7" version="1"/>
  </validityConditions>
  <ServiceCalendar id="ch:1:ServiceCalendar:j23" version="1"/>
  <dayTypes>
    <DayType id="ch:1:DayType:ycy10_1" version="1"/>
  </dayTypes>
  <timebands>
    <Timeband id="ch:1:Timeband:1140:1260" version="1"/>
  </timebands>
</ServiceCalendarFrame>

→ Template

Usage Notes

Note that VALIDITY CONDITIONs could be combined and ANDed (all the conditions must be fullfiled at the same time) thanks to the WITH CONDITION REF attribute. We will work with FromDate/ToDate and ValidDayBits of AvailabilityCondition only.

AvailabilityCondition

→ Glossary definition

Purpose

Temporal availability in terms of Dates, Timebands, ValidDayBits.

Table

Sub	Element	Usage	Card	Type	Note
+	FromDate	optional	1..1	unknown	Is equal to the start date of the timetable year or, more generally, the period in which the ValidDayBits apply.
+	ToDate	optional	1..1	unknown	Is equal to the end date of the timetable year or, more generally, the period in which the ValidDayBits apply.
+	ValidDayBits	mandatory	1..1	unknown
+	timebands	optional	1..1	unknown	Can also be referenced
++	Timeband	optional	1..1	unknown
++	TimebandRef	optional	1..1	unknown

→ General NeTEx definition

Example

<?xml version="1.0" encoding="UTF-8"?>
<AvailabilityCondition  id="generated" version="1">
  <FromDate>2026-05-17T00:00:00Z</FromDate>
  <!-- Is equal to the start date of the timetable year or, more generally, the period in which the ValidDayBits apply. -->
  <ToDate>2026-05-17T00:00:00Z</ToDate>
  <!-- Is equal to the end date of the timetable year or, more generally, the period in which the ValidDayBits apply. -->
  <ValidDayBits>01010010111</ValidDayBits>
  <timebands>
    <!-- Can also be referenced -->
    <Timeband id="ch:1:Timeband:4937" version="1">
      <StartTime>06:00:00</StartTime>
      <EndTime>06:01:00</EndTime>
    </Timeband>
    <TimebandRef ref="ch:1:Timeband:4937-2" version="1"/>
  </timebands>
</AvailabilityCondition>

→ Template

Usage Notes

Examples of use of AVAILABILITY CONDITION include ENTRANCEs, EQUIPMENTs, STOP PLACEs, etc.
AvailabilityCondition replaces OperatingDay and OperatingPeriod. Whenever a reference to a VP (“Verkehrsperiode” or operating period in english) is needed, we use an AvailabilityConditionRef:
The referenced AvailabilityConditions are centrally stored in the ServiceCalendarFrame.
The element ValidDayBits directly indicates the days on which some service is provided or not. They are similar to the HRDF bitfields.
ValidDayBits is required whenever the AvailabilityCondition is of temporal nature (more often than not). Examples include:
- ServiceJourney
- NoticeAssignment
- ServiceFacilitySet
- ServiceJourneyInterchange
Hint: The frames TimetableFrame, ServiceFrame and ServiceCalendarFrame and their elements must have the same validity.
id-attribute does not need to be kept stable between exports.

ServiceCalendar

→ Glossary definition

Purpose

Long-term planning uses calendar days that are classified as specific DayTypes (example: weekday in school holidays). A ServiceCalendar defines a mapping between DayTypes and OperatingDays.

Table

Sub	Element	Usage	Card	Type	Note
	ServiceCalendar	expected	1..1	unknown
+	Name	mandatory	1..1	unknown	timetable year
+	FromDate	mandatory	1..1	unknown	Beginning of timetable year
+	ToDate	mandatory	1..1	unknown	End of timetable year

→ General NeTEx definition

Example

<?xml version="1.0" encoding="UTF-8"?>
<ServiceCalendar  id="ch:1:ServiceCalendar:j23" version="1">
  <Name>Fahrplan 2018</Name>
  <!-- timetable year -->
  <FromDate>2017-12-10</FromDate>
  <!-- Beginning of timetable year -->
  <ToDate>2018-12-08</ToDate>
  <!-- End of timetable year -->
</ServiceCalendar>

→ Template

Usage Note

id-attribute should to be kept stable between exports.

DayType

→ Glossary definition

Purpose

A classification of days on which a specific set of transport services operates (e.g., Weekdays, Saturdays, Public Holidays). The DayTypes of the Swiss profile represent national holidays.

Table

Sub	Element	Usage	Card	Type	Note
	DayType	optional	1..1	unknown	In Switzerland only used for holidays and the like
+	alternativeTexts	expected	1..1	unknown
++	AlternativeText	mandatory	1..1	unknown
+++	Text	mandatory	1..1	unknown
+	Name	mandatory	1..1	unknown
+	properties	expected	1..1	unknown
++	PropertyOfDay	mandatory	1..1	unknown	Holidays only
+++	HolidayTypes	expected	1..1	unknown
+++	DayEvent	optional	1..1	unknown

→ General NeTEx definition

Example

<?xml version="1.0" encoding="UTF-8"?>
<DayType  id="ch:1:DayType:Bundesfeier" version="1">
  <!-- In Switzerland only used for holidays and the like -->
  <alternativeTexts>
    <AlternativeText attributeName="Name">
      <Text lang="it">Festa nazionale</Text>
    </AlternativeText>
    <AlternativeText attributeName="Name">
      <Text lang="en">National Day</Text>
    </AlternativeText>
    <AlternativeText attributeName="Name">
      <Text lang="fr">Fête nationale</Text>
    </AlternativeText>
  </alternativeTexts>
  <Name>Bundesfeier</Name>
  <properties>
    <PropertyOfDay>
      <!-- Holidays only -->
      <HolidayTypes>NationalHoliday</HolidayTypes>
      <DayEvent>normalDay</DayEvent>
    </PropertyOfDay>
  </properties>
</DayType>

→ Template

Usage Note

id-attribute needs to be kept stable between exports.

Timeband

→ Glossary definition

Purpose

A period of time within a day, usually defined by a start and end time.

Table

Sub	Element	Usage	Card	Type	Note
	Timeband	mandatory	1..1	unknown
+	StartTime	mandatory	1..1	unknown	Local time (not Zulu), i.e., without “Z” or “hh:mm:ss” suffix. Seconds are not used.
+	EndTime	mandatory	1..1	unknown	Local time (not Zulu), i.e., without “Z” or “hh:mm:ss” suffix. Seconds are not used.

→ General NeTEx definition

Example

<?xml version="1.0" encoding="UTF-8"?>
<Timeband  id="ch:1:Timeband:4937" version="1">
  <StartTime>06:00:00</StartTime>
  <!-- Local time (not Zulu), i.e., without “Z” or “hh:mm:ss” suffix. Seconds are not used. -->
  <EndTime>06:01:00</EndTime>
  <!-- Local time (not Zulu), i.e., without “Z” or “hh:mm:ss” suffix. Seconds are not used. -->
</Timeband>

→ Template

Usage Notes

Currently Timeband is used in RG 1.0 for InterchangeRuleTimings, later also used for the opening hours in StopPlace models.
id-attribute should be kept stable between exports.

DayTypeAssignment

→ Glossary definition

Purpose

Assignment of a date to DayType. The DayTypes of the Swiss profile represent national holidays.

This assignment overrides the DayType specified for the day in the overall plan. (TODO should be stated more clearly / precisely) Wilfried 10.6.

Table

Sub	Element	Usage	Card	Type	Note
	DayTypeAssignment	expected	1..1	unknown	We currently use DayType to store the national holidays.
+	Date	mandatory	1..1	unknown
+	DayTypeRef	mandatory	1..1	unknown

→ General NeTEx definition

Example

<?xml version="1.0" encoding="UTF-8"?>
<DayTypeAssignment  id="BundesfeierAssignment" version="1">
  <!-- We currently use DayType to store the national holidays. -->
  <Date>2023-08-01</Date>
  <DayTypeRef ref="ch:1:DayType:Bundesfeier" version="1"/>
</DayTypeAssignment>

→ Template

Usage Notes

We currently use DayTypeAssignment only for the national holidays.
id-attribute should be kept stable between exports.