Innhold

Preface

Harmonization of exchange methodology between different systems is essential to:

Entur AS on behalf of Jernbanedirektoratet

in order to efficiently collect all time table data from each data provider, ensure consistency of data, and grow data quality. This allows the creation of multimodal infomation systems which may be used to implement nationwide journey planning solutions and publisize business neutral information to all interested parties.

travellers

in order to present relevant, and high quality journey suggestions

public transport operators

in order to re-use the data in their own journey planning-, ticketing-, and information systems, and offer a better service to their customers.

third party service providers

in order to minimize unessescary costs related to supporting multiple different exchange formats, and to contribute to a continued growth of standardized public transport data exchange.

Introduction

NeTEx (CEN TS 16614-1, 16614-2 og 16614-3) is a CEN-standard which defines the data format and description for public transport data exchanges. The standard is based on Transmodel (EN 12896), and the reference model for permanent objects required for access to public transport: IFOPT (Identification of Fixed Objects in Public Transport, EN 28701).

NeTEx supports the exchange of data nessescary for stop place information, journey planning, and ticketing, and is divided into their main categories

1. Networktopology (CEN TS 16614-1)
2. Plan data (CEN TS 16614-2)
3. Tariff-information (CEN TS 16614-3)

NeTEx was created by CEN / TC278 / WG3 / SG9 lead by France. The final part of the format was published in 2015. The format was created to support the needs of a collection of public transport data providers in Europe, among others ERA (European Rail Agency) and UIC (International Union of Railways).

NeTEx is an XML format that facilitates the exchange of route data between distributed systems. Data in the NeTEx format should be used to effectively update various information and operational applications through both file-based services and web service architectures. The official website contains a detailed explanation of the intention underlying the standard, data models and publicly available standard documentation. In particular, "NeTEx White Papers", available under the website's Downloads section, provides a good introduction to how different concepts in public transport can be modeled using NeTEx.

NeTEx is a comprehensive data format intended to describe concepts in public transport data in different ways, and in many cases there will be parts of the specification that are superfluous in relation to the need. In actual implementation, therefore, an extraction of necessary objects, which constitute a so-called NeTEx profile, should be made. Such a profile should be used to specify which parts of the NeTEx format are expected to be exchanged between systems in a given context.

This document describes NeTEx's profile Norway for the exchange of stop and route data between external actors and central systems provided by Entur, and this profile has been prepared with the assistance of the NeTEx working group in CEN (Comité européen de normalization, the European Committee for Standardization).

TO reduce complexity, the profile is divided into several parts:

• Reusable components (framework (korrektur))
• Information about stopplaces(stops (korrektur))
• Information about Transport Network Information (network (i arbeid))
• Information about timetable (timetable (korrektur))
• Information about fare and ticketing (fares) (norwegian profile is prepared in later version)

Each section describes data objects that belong to a given functionality. In addition, a common part has been separated, which describes the basic objects that are reused across the entire profile.

References

The following documents forms the basis of the Norwegian NeTEx profile:

• TS 16614-1, Network and Timetable Exchange (NeTEx) - Part 1: Public transport network topology exchange format
• TS 16614-2, Network and Timetable Exchange (NeTEx) - Part 2: Public transport scheduled timetables exchange format
• EN 12896, Road Transport and traffic telematics - Public transport - Reference data model (Transmodel)
• EN 28701, Intelligent transportation systems - Public transport - Identification of Fixed Objects in Public Transport (IFOPT)

Exchange of information

Information exchanged over the NeTEx format should be XML files containing only one root tag:

PublicationDelivery

Information should be delivered as one XML file per line, packed as ZIP in a flat structure (without subdirectories). It is technically possible to deliver each line separately, packed in a separate ZIP file, if all the data objects used by the line are defined within its PublicationDelivery. However, in order to avoid overwriting issues and ensure good data change / deletion management, it is strongly recommended that the ZIP file always contains complete datasets for all lines. Then, common objects used across the line XMLs - such as organizational data, stopplace associations and calendar objects - should be defined in one or more common object files (these must be prefixed with underscore, "_filename.xml") so that redundancy is avoided for objects that must be unique to the dataset.

Inne i PublicationDelivery defineres det <dataObjects> som består av et sett med Frames, hvor hver frame samler alle relevante objekter i én gruppe og spesifiserer felles gyldighetsbetingelser, f.eks. gyldighet og versjon. Denne mekanismen støtter inkrementell oppdatering av individuelle objekter i tilfeller hvor relasjonene mellom objektene ikke blir endret, og legger til rette for sporing i tilfeller hvor feil eller spørsmål må avklares ned på objekt- eller gruppe-nivå. 

PublicationDelivery tillater bruk av vilkårlig antall frames, fra én til mange, og samme type frame kan brukes flere ganger. Men generelt anmodes det om å benytte færrest mulig frames, slik at grupperingen innen samme PublicationDelivery er hensiktsmessig (unngå å "wrappe" objekter inn i egne frames). Objekter som naturlig hører sammen, dvs. har samme versjon og gyldighet, skal samles i samme frame.

Datainnsending i CompositeFrame

Ved gruppering av Frames i en CompositeFrame, må ValidityCondition være likt for alle frames under denne. Det vil si at dette ikke settes per frame, men styres implisitt fra CompositeFrame.

Datainnsending som enkeltvise frames

Når frames ikke er gruppert i en CompositeFrame, må alle relevante frames ha satt eksplisitt ValidityCondition. 

Generalisering

I NeTEx er det gjennomgående at objekter kan legges på ulike nivåer, på den måten å mest mulig korrekt kunne modellere faktiske forhold. For å unngå redundans stilles det derfor krav i norsk profil om at alle beskrivelser og referanser skal ligge så høyt i hierarkiet som mulig.

F.eks. kan Operator refereres fra den enkelte ServiceJourney i Timetable, men i de fleste tilfeller vil en Line ha bare én hovedoperatør. Denne skal derfor referes i Line, og eventuelle unntak i stedet overskrives per ServiceJourney (med referanse til "additionalOperators" i Line).

Versjonering

For å sikre kompatibilitet, tilbyr NeTEx versjonskontroll-mekanisme som lar dataleverandører og - mottakere:

• Spesifisere hvilken versjon av NeTEx-profilen som brukes 
  • Medfører at data håndteres korrekt dersom det sendes i henhold til eldre (men fremdeles støttet) versjon
• Bearbeide utvekslede data på korrekt måte
• Fortelle klienten om etterspurt versjon ikke lenger er støttet

Versjonshåndtering er basert på versjonsattributt (konseptuelt VersionFrame), og skal settes på relevant(e) objekt(er) så overordnet - dvs. på så høyt nivå i den leverte XML-strukturen - som mulig.

Versjon for profil

Ved innsending av NeTEx XML for henhodsvis stoppestedsinformasjon og rutedata må det spesifiseres i datasettet hvordan innholdet skal leses inn. Dette gjøres ved å oppgi hvilken profilversjon innsendingen gjelder. 

Profil-versjon skal settes i version-attributt for XMLens PublicationDelivery rotnode, og format for versjon av profil er som følger:

[NeTEx XSD-versjon]:[Profilnavn]:[Profil-versjon]

• NeTEx xsd-versjon er et tall som angir hvilken versjon av NeTEx XSD som benyttes (format X.Y)
• NO-NeTEx-<profilnavn> er profilnavn med en av predefinerte verdier:
  • stops
  • networktimetable
  • fares
• Profil-versjon er et tall som angir hvilken versjon av Norsk NeTEx-profil som benyttes (format X.Y)

Eksempler:

Ved oppdatering av NeTEx vil formatet normalt være bakover-kompatibelt, og det samme vil forsøkes å gjøre med profilen, slik at en vilkårlig klient som benytter tidligere versjon av NeTEx (både XSD og norsk profil) også skal kunne utveksle data med tjenester som kjører med nyere versjon(er).

Når ny versjon av NeTEx publiseres, vil det likevel normalt bli laget og publisert en oppdatert versjon av denne profilen. 

Dersom det likevel skulle skje fremtidige endringer i formatet eller kravene i den norske NeTEx-profilen, som gjør at formatet ikke er bakoverkompatibelt, vil tjenestene i sentrale systemer støtte både gammel og nye versjon i rimelig tid slik at dataleverandører får tid til å gjøre nødvendige tilpasninger. 

Versjon for dataelementer

For versjonering av enkeltobjekter i innsendt XML står dataleverandørene friere til å sette dette, med følgende forbehold:

• Versjonsnummer må være et positivt heltall
• Versjonsnummerne må økes på en slik måte at den seneste versjonen for gjeldende objekt alltid har høyest numerisk verdi

Elementer som skal versjoneres

I praksis må de aller fleste objekter med ID også har en versjon (se Eksempel-katalog for nærmere detaljer), og innsendte stoppesteds- og rutedata skal versjoneres slik at alle relevante endringer medfører en økning av versjonsnummer.  

Følgende versjoneringsregler presiseres spesielt:

• Endring i informasjon om Network / GroupOfLines
• Endring av informasjon om Line krever ny versjon (ID skal normalt bestå)
• Endring av organisations (Authority, Operator) krever ny versjon (ID skal normalt bestå)
• Endring av geografiske data / posisjonsinformasjon for objekter (som ellers ikke revideres) krever ny versjon
• Ny tilleggsinformasjon (f.eks. AlternativeName for oversettelse) krever ny versjon
• Mindre korreksjoner som påvirker publikumsinformasjon (f.eks. justering av tidspunkt for ankomst/avgang), men ellers ikke påvirker datasettet, krever ny versjon

version="any"

I NeTEx kan man eksplitt spesifisere at et objekt ikke er versjonert ved å sette versjonsattributtet til "any".

Objekter definert annet sted enn i datainnsendingen, f.eks. eksterne objekter fra det nasjonale stoppestedsregisteret, vil alltid være i for tiden gjeldende versjon.

Versjonering i referanser

Det stilles krav om version-attributt for referanser til et unikt objekt definert innenfor samme PublicationDelivery, det vil si at ved referanse til et dataelement som er definert i den sammen filen må versjon oppgis. Referanse til eksterne objekter skal derimot oppgis uten versjon.

Ved å oppgi version-attributt i en referanse blir denne referansen validert mot ID + VERSION for eksisterende objekt innenfor gjeldende PublicationDelivery. Fordi XML i ved Schema-validering kun støtter streng-likhet, er det ikke mulig å benytte version="any" for referanse til objekter definert med eksplisitt versjonsnummer (selv om dette etter standarden betyr referanse til siste gyldige versjon). Hvis det finnes flere mulige versjoner av et objekt definert internt i filen, og man skal referere til det siste gyldige, brukes derfor referanse uten version-attributt. Altså på samme måte som ved referanse til eksterne objekter.

Gyldighet for dataelementer

Alle objekter som versjoneres må ha gyldighet, enten implisitt (arvet) eller satt eksplisitt på objektet.

Dette settes gjennom ValidityCondition(s), som definerer gyldigheten for objektene i datainnsendingen (en linje eller et sett av linjer), og skal gjøres på en av følgende måter:

• ValidityCondition satt eksplisitt per frame i datainnsendingens PublicationDelivery
• ValidityCondition for en CompositeFrame, hvor denne inneholder alle frames i datainnsendingens PublicationDelivery
  Denne ValidityCondition definerer gyldighet som arves av alle objektene i innsendingen, og gjelder implisitt for samtlige underliggende frames (man kan ikke overstyre ValidityCondition for underliggende frames innenfor en CompositeFrame)

Dataelementer som kan overstyre gyldighet (ValidityCondition)

Alle underliggende datalelementer arver implisitt gyldighet, enten satt gjennom ValidityCondition for innsendingens CompositeFrame eller satt gjennom ValidityCondition for den enkelte frame (når CompositeFrame ikke brukes). Ved behov for å overstyre gyldigheten på underliggende objekter, kan dette gjøres ved å sette eksplisitt ValidityCondition for elementet hvis gyldighet skal avvike fra gyldigheten arvet fra på innsendingens frame:

• Overstyrende ValidityCondition(s) settes per dataobjektet, for å eksplisitt angi annen gyldighet enn den som implisitt ville vært arvet fra frame (alternativt arvet fra overliggende CompositeFrame)
• Overstyrende ValidityCondition(s) må være innenfor rammene av arvet gyldighet, det vil si kan kun være strengere (gjelde for kortere tidsperiode)

Slik overstyring er støttet for følgende objekter:

• Network
• lines
• organisations (Authority, Operator)
• routes
• serviceLinks
• journeyPatterns

Overstyring av Timetable- og ServiceCalendar-relaterte data skal skje gjennom komplette TimetableFrame og ServiceCalendarFrame med ValidityCondition som utvetydig viser perioden underliggende elementer gjelder.

Konvensjoner

Utforming av identifikatorer

Identifikatorer til diverse objekter i NeTEx skal følge samme mønster og skal utformes som følger:

[codespace]:[type]:[id]

• codespace
  Codespace som representerer provider namepace definert for frame (se codespaces)
• type 
  Dette skal være lik datatypens navn (eksempel Network, Line, StopPlace, Quay osv.)
• id
  Unik id for en gitt objekt-type. Merk at i ID-strengen godtas kun tall, store/små bokstaver (A-Z/a-z), bindestrek (-) og/eller understrek (_) som gyldige tegn.

Faste identifikatorer

For utveksling av stoppestedsinformasjon (StopPlace, Quay etc.) med sentrale systemer er det et krav at identifikatorer alltid skal være de som er gitt i det nasjonale stoppestedsregisteret. Dette for at alle objekter skal kunne identifiseres entydig over tid.

Det er sterkt anbefalt at alle dataobjekter som beskriver uendrede rutedata-forhold, som for eksempel Line, Route, ServiceJourney osv. også benytter faste identifikatorer på tvers av leveranser, selv om det gjøres mindre endringer i rutemønstre eller tider for ankomst og avgang. Kun da vil det være mulig å opprettholde gjennomgående historikk for like data, samt gi eksterne brukere muligheten til å kunne forholde seg til faste identifikatorer på tvers av leveranser. Dette gjelder også selv om elementene nødvendigvis ikke er identiske over tid, så lenge disse er naturlig å koble sammen. For eksempel vil det være relevant å opprettholde identifikatorer for periodevise sesongruter, for en linje hvor det endringer av rutemønster eller hvor avgangstidpunktet er forskjøvet med noen minutter.

Der det er nye rutedata uten naturlig kobling til tidligere objekter skal derimot ikke identifikatorer gjenbrukes, selv om det eventuelt skulle tilfeldige likheter med tidligere data.

Codespace

Tilsvarende som namespace brukes for å identifisere et unikt XML Schema, benyttes codespace i NeTEx for å sørge for at de enkelte dataelementer og attributter i XMLen kan identifiseres unikt for hver innsendt XML. Slik kan data fra ulike innsendere identifiseres og kombineres på tvers av aktører. Alle innsendte data skal derfor identifiseres med et unikt codespace tilordnet den enkelte som leverer stoppested- og rutedata. 

Liste over codespaces vedlikeholdes av Nasjonalt Selskap, og alle som skal ha tilgang til å sende inn stoppested- og/eller rutedata på NeTEx-format vil være tilordnet en codespade-ID med samsvarende namespace der.

Kardinalitet

Kardinaltallet er en egenskap som beskriver mengde, og viser antallet elementer som er forventet for et gitt objekt i henhold til den norske NeTEx-profilen.

• 0: 1 - Valgfri - Kan sende inn null eller maksimalt ett av elementet
• 0: * - Valgfri - Kan sende inn null, ett eller flere av elementet
• 1: 1 - Obligatorisk - Må sende inn ett, og bare ett, av elementet
• 1: * - Obligatorisk - Må sende inn ett eller flere av elementet

Typebeskrivelse

Hvert objekt er beskrevet med følgende tabell:

Arvehierarkiet beskrives på følgende måte:

Class < ParentClass < ParentClass < ... < ParentClass

Den første kolonnen utelates dersom tabellen kun inneholder elementer (kolonnen brukes kun for å skille mellom attributter og elementer).

Bruk av Enumeration

Profildokumentene beskriver de forskjellige NeTEx-objekter som brukes i Norge, med aktuelle felter og tilhørende datatyper. Noen datatyper er Enumeration, dvs. en liste med pre-definerte verdier som er tillatt for feltet.

Det finnes to måter å bruke Enumeration på:

1. Enkel Enumeration
   Når datatypen er satt til xxxEnumeration (f.eks. FacilitySetEnumeration), betyr det at bare én verdi er tillatt i feltet:

   ...
   <facilitySet>seatingOnly</facilitySet>
   ...

2. Liste av Enumerations
   Når datatypen er satt til xxxListOfEnumerations (f.eks. MealFacilityListOfEnumerations), betyr det at det er tillatt med flere verdier i samme element. Dette settes opp i XML'en på følgende måte:

   ...
   <mealFacilityList>breakfast dinner drinks</mealFacilityList>
   ...

Definisjoner

Her beskrives alle NeTEx-begrepene som er brukt i profilen.