Author: Peter Hirzel (Software Architect SBB Journey Planner), 2023
Licence: Apache License, Version 2.0

About OJP-Adapter

This is a simple OJP-Adapter library to request Public-Transportation queries against the swiss public Open Journey-Planner (SKI).

Remark about OJP SKI

• Public Transportation router commissioned by BAV
• Usage for e.g. by öv-info.ch

Goals

Abstracting the complex VDV OJP v1.0.1 Schema by Java POJOs, map response properly and provide low-level error-handling.

Anyone (for e.g. public transport-organisation) who plans to use the Swiss OJP router (or other european OJP instances supporting the same protocol version) may try this library to setup a quick working starting point.

The vdv ojp XSD might be quite complex and JAXB POJO generation therefore too!
Besides, understanding the OJP semantics may mean a steep learning curve for non-insiders.

The author hopes using this OJP-Adapter library may "abstract" the above steps massively, though the resulting OJP model may still be complex to deal with (perhaps check the returned data for a more intuitive understanding as well).

Content

• the OJP.xsd 1.0 is transformed into a JAVA POJO (by JAXB) by
  • open-source bliksemlabs or Maven
  • dependency ojp-java-model
• Further documentation:
  • Swiss OJP cookbook
  • OJP/Transmodel mapping
  • Semantic model description OJP - Open API for distributed Journey Planning by jmaerki

The provided OJPAdapter is able to query Swiss SKI+ OJP instances, if configured well (by means your own access token):

• use OJPAadapter for raw native XML handling in conversation with OJP protocol.

Run it

1. Download repository
2. mvn clean install
3. copy ojp-adapter-integration/src/main/resources/ojp-SAMPLE.properties to ojp.properties and add your own key for SKI+ OJP Instance from opentransportdata.swiss passive instance "Manage the API key"
4. run swiss.opentransportdata.ojp.adapter.v1.OJPAdapterAccessTest (to try out native OJP XML based request/response)
5. run swiss.opentransportdata.ojp.adapter.service.application.OJPWebApplication and open OpenAPI 3 Swagger-UI

Remark:

• At least the OJP passive key should be easy to get.
• For the OJP active instance key you probably need to contact the operation-responsibles.
• If your just interested in Open API 3 Swagger-UI resulting out of ojp-adapter-service/../* OJPController*, see JSON-specification

Open issues

Module "ojp-adapter"

OJP 1.0 implementation

OK: Covers Place, Trip, DatedVehicleJourney (including Departures/Arrivals)

• Currently, OJPAdapter deals with one SINGLE Journey-Planner request at a time, though MULTIPLE requests could be performed at once.
• Complete OJP set of request-filters (currently the most relevant filters are adapted).
• Complete OJP response mapping (currently the most relevant properties are implemented).
• Implement further details marked by TODO
• Quality tests for correctly mapped output should be verified and confirmed by SKI+.

OJP 2.0 implementation

Planned upgrade to use OJP 2.0 API. See:

• OJP 2.0 Cookbook
• OJP SDK
  • VDV OJP 2.0 Model base for Java model

Module "ojp-transmodel" & "Swagger-UI"

• Planned for the near future: further extension of OJPController like subset of SBB Journey-Service v3 APIs where supported by SKI+ OJP:
  • Transmodel like implementation model as used by SBB Customer Information
  • Model mapper between VDV specification to the Transmodel like implementaiton model
  • Simple OpenApi 3 REST API based application offering a Swagger UI to execute requests against OJP

Known usage

This Software was originally developed for SBB AG Switzerland, Personenverkehr, Customer Information by Peter Hirzel (Software Architect Journey-Planner) for experimental reasons:

• APIs (endpoints) under SBB Journey-Service within tag Open Journey Planner V3