Innhold

Forord

Harmonisering av måter rutedata utveksles på mellom diverse systemer er essensiell for:

Entur AS på vegne av Jernbanedirektoratet

for å kunne samle rutedata fra hver enkel leverandør på en fornuftig måte, sikre datakonsistens og øke datakvalitet. Dette vil tillate etablering av multimodale informasjonssystemer, noe som kan brukes for å implementere landsdekkende reiseplanlegging for alle typer rutegående kollektivtransport, tilgjengeliggjøre data på en konkurransenøytral måte for alle interesserte;

reisende

for å kunne presentere relevante søkeresultater som har god nok kvalitet;

operatørene

som kan bruke dataene i egne ruteplanlegging-, billettering- og informasjonssystemer for å tilby bedre service til sine kunder;

tredjepartsleverandører

for å minimere utgifter knyttet til utvikling av formatstøtte samt bidra til mer strømlinjeformet og standardisert datautveksling.

Innledning

NeTEx (CEN TS 16614-1, 16614-2 og 16614-3) er en CEN-standard som definerer dataformat og beskrivelse av tjenester for utveksling av ruteinformasjon, tidtabeller og andre relevante data for kollektivtrafikk. Denne standarden er basert på referansemodellen for kollektivtransport, Transmodel (EN 12896), samt referansemodellen for permanente objekter påkrevd for tilgang til kollektivtransport, IFOPT (Identification of Fixed Objects in Public Transport, EN 28701).

NeTEx støtter både utveksling av nødvendige data nødvendig for stoppestedsinformasjon, ruteplanlegging med tilhørende informasjonssystemer samt takst og billettering, og er delt opp i tre hoveddeler:

1. Nettverkstopologi (CEN TS 16614-1)
2. Ruteplan (CEN TS 16614-2)
3. Tariff-informasjon (CEN TS 16614-3)

NeTEx ble utarbeidet av CEN / TC278 / WG3 / SG9 ledet av Frankrike. Siste del av formatet ble publisert i 2015. Formatet er laget som en sammenstilling av behov og krav som finnes hos diverse leverandører av offentlige transport-tjenester i Europa, blant annet ERA (European Rail Agency) og UIC (International Union of Railways).

NeTEx er et XML-format som legger til rette for utveksling av rutedata mellom distribuerte systemer. Data i NeTEx-formatet skal kunne benyttes for å effektivt oppdatere ulike informasjons- og operasjonelle applikasjoner gjennom både filbaserte tjenester og webservice-arkitekturer. På den offisielle nettsiden ligger utdypende forklaring av intensjonen som ligger til grunn for standarden, datamodeller og offentlig tilgjengelig standard-dokumentasjon. I sær gir "NeTEx White Papers", tilgjengelig under nettsidenes Downloads-seksjon, en god introduksjon til hvordan ulike konsepter innenfor offentlig transport kan modelleres ved hjelp av NeTEx.

NeTEx er et omfattende dataformat ment for å beskrive konsepter innenfor kollektivtrafikk-data på ulike måter, og i mange tilfeller vil det være deler av spesifikasjonen som er overflødig i forhold til behovet. Ved faktisk implementasjon bør det derfor lages et uttrekk av nødvendige objekter, som utgjør en såkalt NeTEx profil. En slik profil skal brukes for å spesifisere hvilke deler av NeTEx-formatet som er forventet at utveksles mellom systemer i en gitt kontekst.

Dette dokumentet beskriver NeTEx profil Norge for utveksling av stoppesteds- og rutedata mellom eksterne aktører og sentrale systemer levert av Entur, og denne profilen er utarbeidet med bistand fra NeTEx arbeidsgruppen i CEN (Comité européen de normalisation, den europeiske komité for standardisering).

For å redusere kompleksiteten er profilen delt opp i flere deler:

• Gjenbrukbare komponenter (framework (Copy))
• Informasjon om stoppesteder (stops (Copy))
• Informasjon om transportnettverket (network (Copy))
• Informasjon om ruteplan (timetable (Copy))
• Informasjon om takst og billettering (fares (Copy)) (norsk profil klargjøres i senere versjon)

Hver del beskriver dataobjekter som hører til en gitt funksjonalitet. I tillegg er det skilt ut en felles del, denne beskriver de grunnleggende objektene som gjenbrukes på tvers av hele profilen.

Referanser

Følgende dokumenter ligger til grunn for den norske NeTEx-profilen:

• 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)

Utveksling av informasjon

Informasjon utvekslet over NeTEx-formatet skal være XML-filer som inneholder kun én root tag:

PublicationDelivery

Informasjon skal leveres som én XML-fil per linje, pakket som ZIP i en flat struktur (uten underkataloger). Det er teknisk mulig å levere hver linje for seg, pakket i en egen ZIP-fil, såfremt samtlige dataobjekter som benyttes av linjen er definert innenfor dennes PublicationDelivery. Men for å unngå overskrivningsproblematikk, samt sikre god håndtering av dataendring/sletting, er det sterkt anbefalt at ZIP-filen alltid inneholder komplett datasett for samtlige linjer. Da skal felles-objekter som brukes på tvers av linje-XMLene - for eksempel organisasjonsdata, stoppestedstilknytning og kalender-objekterer - være definert i en eller flere fellesobjekt-filer (disse må prefikses med underscore, "_filnavn.xml"), slik at det unngås redundans for objekter som må være unike for datasettet.

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.