meeting minutes 2022 - UnionInternationalCheminsdeFer/OSDM GitHub Wiki

2022-12-16 Meeting

Address feedback by Linus

  • Availabilities

    To get selectable seat preferences like Aisle, Window … I assume, use end point GET /availabilities/preferences. But I need an clarification of how to use the parameters.

    • What is contextId? Is it offerId or bookedOfferId depending on ContextType?
    • ContextType OFFER/BOOKING is obvious.
    • resourceId, in case of seat preferences it must be reservationId?
    • resourceType should be RESERVATION in this case.

    I think we need to add a better and richer documentation around the availability end points.

    Josef and Linus add documentation

  • Exchange flow

    In our point of view, the current flow for exchange of trips is:

    1. POST /exchange-offers

      a. To get alternative exchange offers (exchangeOperationIds) for the fulfillments

    2. PATCH /bookings/{bookingId} -> POST /bookings/{bookingId}/exchangeOperations with exchangeOffer in body

      a. with information of what to change to

      b. Puts the new offer (exchangeOperationId) to the booking

    3. If confirm the change

      a. PATCH /bookings/{bookingId}/exchangeOperations/{exchangeOperationId}

      1. Release the original offerParts
      2. Confirms the change

      Else (good practice):

      a. DELETE /bookings/{bookingId}/exchangeOperations/{exchangeOperationId}

      1. To remove the prebooked offer added in step 2 from the booking

    4. Confirm using POST /bookings/{bookingId}/fulfillments

    5. Optionally PATCH /bookings/{bookingId}/fulfillments if the fulfillment is in state

    Todos:

    • Add new POST Operation of (2) --> Andreas
    • Detailed documentation of exchange --> Ralf
    • Update swagger documentation:
      • PATCH /bookings/{bookingId}: updates fulfillment types, place selection and add payment. Does not confirm the booking
      • POST /bookings/{bookingId}/fulfillments confirms the booking and can return the fulfillments (1 step mode, fulfillment in state FULFILLED directly)
      • PATCH /bookings/{bookingId}/fulfillments is used in 2-step fulfillment mode with the intermediate state CONFIRMED.

  • Exchange of reservations and ancillaries.

    There are no possibilities to add/remove ancillaries and reservations on confirmed/fulfilled bookedOffers in version 2.1. I guess the first thing is to figure out if this is something we shall support in OSDM or not. In Sweden the functionality is currently not used, even that it exists but there can be changes in the future. If we decide that this is a wanted functionality, it can probably wait with to be specified to a later version.

    Since this relates to economical transactions it should probably be a part of the exchange flow where you currently can search for offers the normal way, with an existing fulfillment provided to give the provider the possibility to return matching offers to change to. So, exchange on admission level is probably covered, but on other offer-part levels we can’t see any endpoints today.

    Use case

    1. As a passenger I want to add (buy) meal to my already confirmed booking.
    2. As a passenger I want to change meal in my already confirmed booking.
    3. As a passenger I want to remove (refund) the meal from my already confirmed booking.

    To get information of exchange possibilities on a fulfillment we probably need a separate end point like, GET /bookings/{bookingId}/fulfillments/{fulfillmentId}/exchange-possibilities or can we extend the already available POST /exchange-offers.

    The endpoint shall return lists of ancillaries and reservations, possible to replace, add and remove.

Interesting business use case as it involves up-selling, to be addressed as an improvement.

  • Numeric Availability

    I have explored the availability response a bit more and have a suggestion to do a change. In my opinion is the numericAvailability is limited to show on accommodationSubType level but not on placeProperty level. I.e., it can be interesting how many free places with ANIMALS_ALLOWED there are at the service,ANIMAL_ALLOWED is a placePropperty for me. To make this possible, I think we shall have a totalAmount of free places on accommodation type level and an optional amount of places on placeProperty level. Also, the accommodationSubType is optional since it is probably not interesting for SEAT.

    • totalAmount on accomodationType level describes the total amount of available reservations for the offer
    • amount on placeProperty level is optional, but if it is used it present the number of places of that type. i.e, WHEEL_CHAIR, ANIMALS_ALLOWED. placeProperties not counted like WINDOW has no amount.

    image

Addressed, no API change needed only documentation.

Address feedback by Andreas on Booking state.

Main issue is that state has moved from Booking to BookingPart.

2022-12-09 Meeting

Address feedback by Linus for 2.1.pre:

  • We have gone into one unexpected problem with the GET /bookings/{bookingId}/bookedOffers/{bookedOfferId}/additionalOffers response. The reservations and ancillaries have references to productId’s, but the product list is not provided in the response ☹.

    We need a product description to show the end user when selecting reservations/ancillaries. We can probably not relay on the summary. This problem happened when we moved product outside the offer. The offer is not self-contained anymore.

  • Another place where we have the product problem is POST /exchange-offers. Here offers possible to exchange to are returned, but there is no way to describe for the end-user what the offer is since the product description and other product elements are missing in the response.

    For me it is more and more obvious to have the product in the offer to be more self-contained. An offer must have a product but not bind to a traveller or a person. Yes, we lose some band with, but is that so critical?

    Conclusion: In order to avoid having to add a products list to all of the different response objects which could contain an offer, we decided to add the list of products to the Offer object, i.e. Offer now contains a products attribute which is an array of Product objects. Also, any response objects (e.g. OfferCollectionResponse) which now have the product list beside the offer list should have the product list removed as it is redundant.

    To be consistent, within the Booking object, the products list should also be moved from the Booking object level into the BookedOffer object.

    Note: the Product object itself does not say what kind of product this is. This may be a problem in the future, when consumers of the interface retrieve all the products a provider offers (GET /products) and try to build an offline "catalog" of the non-trip related products.

Koffi & al.: Booking History feature

  • add a new endpoint GET /bookings/{id}/history, returns a list of modification events
  • add created/confirmed timestamps to the after sales offers within a booking (e.g. refund, exchange etc.)
  • Koffi will create a pull request

Question by Andreas:

  • Where to bundle /bookings/{bookingId}/bookedOffers/*? As part of BookingPart or as part of Booking?

  • Response by the meeting: neither, put them under a new heading "BookedOffers".

  • Also: remove GET /bookings/{bookingId}/bookedOffers, but add a GET /bookings/{bookingId}/bookedOffers/{bookedOfferId} to retrieve an individual bookedOffer.

Questions by Ralf:

  • What should be put into BookingRequest.offers.passengerRefs? The PassengerSpecification currently doesn't contain an appropriate "local id" field.

  • Response: the PassengerSpecification object needs an "localId" field which can be referenced in the offers for being put into the booking.

  • Also, on the OfferRequest/Response, the AnonymousPassengerSpecification also needs a localId field for referencing from the returned offers. This would only be filed on response.

  • How to actually book an ExchangeOffer - response: do a PATCH /bookings/{bookingid} and put it into the exchangeOffers field there. The next step is to GET the exchangeOperations and to PATCH (confirm) it.

  • The proposal is to make the flow more clearly by adding a POST /booking/{bookingid}/exchangeOperations endpoint which will have the functionality of the PATCH /booking with exchange offers.

  • Question by Koffi: how do we change seats? This could be done by PATCHing the /booking and giving a new place selection. Should the new seats have a different price, the provider will return an error and the exchange flow would have to be used.

Questions by Klaus:

  • What is, in the TripSearchCriteria.TripParameters, the semantics of numberOfResults, numberOfResultsBefore, numberOfResultsAfter

  • This is a kind of "window" over the timestamp, it can be requested (with ...Before) to also get the train at 10:59 when the search was for 11:00.

  • In TripSummary (on Trip search responses), origin should be mandatory and distance should be optional (now it is the other way around).

  • In Trip.TripLeg.TimedLeg.DatedJourney, the details on the train (e.g. is reservation required, reservation for bikes required, sleeper cars available, restaurant car available etc.) are missing. We need to add a structure (similar to the coveredSection structure) with MERITs attribute lists.

  • productCategory within the same structure references to service brands.

  • documentation of Trip.id says "unique within the trip", which is obviously wrong, it needs to say "unique for the trip".

Information: Rainer has created an issue to add a GET /version endpoint

Suggestion: update the list of participants of the original meeting (i.e. remove people no longer participating, add new regulars, kind of new-years-cleaning).

Also, add a link to the meeting at the beginning of the meeting minutes.

2022-12-02 Meeting

Address feedback by Linus for 2.1.pre:

  • GET /bookings/{bookingId}/bookedOffers/{bookedOfferId}/additionalOffers Maybe we shall have a slimmer more tailored offer in AdditionalOfferCollectionResponse. AdmissionOfferParts, fees and fares are not in scope. But it works with your suggestion.

  • POST /bookings/{bookingId}/bookedOffer/{bookedOfferId}/reservations/{reservationId} We have an array of PlaceSelections with reservationIds in the payload at the same time as we have a reservationId as a parameter. I don’t think reservationId shall be a parameter and we can use the reservationId in the pay-load. The result is a bookedOffer. It is not self-contained in the meaning passengers, products and trips are not there ☹. I think we need them as well. Is the response a BookingResponse? Clients will probably run GET /booking anyway.

  • Do we really need PATCH /bookings/{bookingId}/bookedOffer/{bookedOfferId}/reservations/{reservationId}. I think POST replace it.

  • POST /bookings/{bookingId}/bookedOffer/{bookedOfferId}/ancillaries/{ancillaryId} We have ancillaryOfferId in the payload at the same time as we have ancillaryId as a parameter. I don’t think ancillaryId shall be a parameter. The result is a bookedOffer. It is not self-contained in the meaning passengers, products and trips are not there ☹. I think we need them as well. Is the response a BookingResponse?

  • Do we really need PATCH /bookings/{bookingId}/bookedOffer/{bookedOfferId}/ancillaries/{ancillaryId}. I think POST replace it.

  • POST /bookings/{bookingId}/bookedOffer The result is a bookedOffer. It is not self-contained in the meaning passengers, products and trips are not there ☹. I think we need them as well. Is the response a BookingResponse?

  • Add the plural s on bookedOffer since this are new endpoints.

  • We still miss the DELETE /bookings/{bookingId}/bookedOffer/{bookedOfferId} endpoint to remove a pre-booked offer from a booking before confirmation.

  • We need to add externalRef in the tripSummary in the response for POST /bookings-search.

Decisions:

  • remove PATCH /bookings/{bookingId}/bookedOffers/{offerId}/ancillaries/ancillaryId and ../reservations/reservationId
  • fix POST /bookings/{bookingId}/bookedOffers/{offerId}/ancillaries and ../reservations
  • add DELETE /bookings/{bookingId}/bookedOffers/{offerId}
  • rename bookedOffer to bookedOffers
  • improve booking search:
    • add externalRefs to TripSummary
    • add BookedOfferSummary and BookingPartSummary

2022-11-25 Meeting

  • Updated version OSDM v2.0.3:
    • Adresses points decided in meeting last week:
      • remove GET /bookings/{id}/bookedOffer
      • add products to OfferCollectionResponse and Booking
  • News from Bileto: OSDM at bus exhibition CZECHBUS

https://www.bileto.com/en/blog/bileto-exhibited-osdm-capability-at-czechbus-2022 (English leaftlet included)

  • News from TAP-TSI

  • A long time ago we discussed different code lists for locations and found that there is a need for at least:

    • UIC location codes (urn:uic:stn)
    • UIC reservation codes
    • Proprietary codes for a specific system

    Many of the existing reservation systems use UIC reservation codes when exchanging reservation messages using IRS 90918-1 messages today. It would therefore be beneficial for us to be able to use UIC reservation codes in OSDM as well.

    As UIC location codes replaces UIC reservation codes, the UIC reservation codes are deprecated and thus should not be officially supported.

  • Proposal I-72 Fulfillment Type/Media override and named value list on Fulfillment Part

    Need to structure the information in the offerpart.

  • Questions from DB

    • How do I know whether graphical seat reservation is supported or not for a given offer?

    Information is available on fare graphicalReservation, needs to be exposed on the offer side. --> Ralf makes improvement

    Ralf: when preparing the improvement, i noticed that the relevant structure is already present in the ReservationOfferPart. Sorry for the confusion.

    • How do I know how to refund (on voucher or on credit card)?

    Add information to conditions. --> Ralf make improvement

    Ralf: done, see I-73 Extend after sales conditions with permitted payment methods.

    • How should an offer for a individual ticketing look like?

    OfferCollectionResponse for individual ticketing

    Note that there are variations for the ReservationOfferParts:

    • there could be a separate ReservationOfferPart for each passenger and each leg
    • there could be a common ReservationOfferPart for all passengers for each leg
    • there could be a separate ReservationOfferPart for each passenger, but for multiple legs
    • and there could be a common ReservationOfferPart for all passengers, but for multiple legs (i.e. one ReservationOfferPart covering everything in this offer)

2022-11-18 Meeting

  • Bug in Get booked offer for a given booking: --> not usable in the curent version

    parameter for the id of the booked offer is missing

    --> Can we remove it? --> do we need a get booked offer that returns all the context of the booked offer (+ trips + products + passengers)?

    Decision: remove the endpoint and do it properly with the cart functionality improvement

  • Bug Fix on Products

    Product got lost in Offer.products:

    --> add list of Products (sibling to trips) in post offer response (OfferCollectionResponse) --> add list of Products (sibling to trips) in booked offers (Booking)

  • Discussion on PassengerType?

    • Product should be utilized to gather textual information to present on final distributed fulfillment.

    • Offer produces FulfillmentDocument nd Fare produces FulFillmentPart. Add option to use Fulfillment.fulfillmentParts depending on bilateral agreements --> option to get fulfillment parts in the get fulfillment request for booked offer

    • extend available FulfillmentMediaType by FULFILLMENT_PARTS that disables fulfillment document generation and populates fulfillment parts instead.

    • query string parameter to request different fulfillment media in the get fulfillment request including Fulfillment type and fulfillment media type; OSDM specification will hint that this may be whitelisted in the backend system based on Requestor or Application/Client ID associated with the JWT, HTTP 4xx series error code for forbidden fulfillment overrides.

    • option for named value list on the fulfillment parts (e.g. for custom pairing code list values of a distributor)

    --> new Improvement to be added (Josef - Bileto, Ralf - DB)

2022-11-11 Meeting

  • Released a v.2.0.2 version
    • TripCoverage.coveredLegIds is now nullable
    • OfferCollectionRequest.tripIds is now nullable
    • TripCoverage.coveredLegIds is now nullable
    • Changes data type of Longitude and Latitude from float to double. This solves precision issues and ensures compatibility with Java's Bean Validation mechanism
    • Minor changes to some comments
    • fixed typos:
      • BookedOfferAncillaryPatchRequest
      • cancelFulfillmentsOffer:
    • add bookedOffer to BookedOfferAncillaryPatchResponse
  • Review proposed modelling of OSDM v.2.1
  • Is there a business need for bookedOffers
    • Assumption: yes, there is. For discussion, see I-71.

Decision: intermediary release 2.1.0 end of November for Swedish Market:

  • I-68
  • I-70
  • bookedOffer --> bookedOffers

2022-11-04 Meeting

  • Address feedback on OSDM 2.0.0 release
  • Work on improvements for Swedish market

Improvement to be able to add not-yet-booked optional items to a pre-booking:

  • need a GET unbooked-offers, i.e. GET /bookings/{bookingId}/bookedOffer/{bookedOfferId}/unbookedOffers
  • need to be able to add reservations and ancillaries, i.e. POST /bookings/{bookingId}/bookedOffer/{bookedOfferId}/reservations and ../ancillaries

Input for the POST would be similar to the patch request (i.e. BookedOfferReservationPatchRequest / BookedOfferAncillaryPatchRequest, but with the addition of the id of the item to be added, i.e.

BookedOfferReservationPostRequest:
   reservation-id: string
   ...

The flow would be:

  • POST the original booking, selecting some of the optional items while we do this
  • GET unbooked-offers
  • POST reservations
  • POST ancillaries
  • confirm/fulfill the booking

Shopping Cart Functionality within pre-booking

  • need to be able to add offers to a pre-booking
  • need to be able to remove offers from a pre-booking

Note: adding something to a confirmed/fulfilled booking is, while also desirable, another topic and shall be discussed a another time

To add: POST /bookings/{booking-id}/bookedOffer, with the following payload:

BookingPostOffersRequest:

  • array of offers (mandatory)
  • array of passengers (optional)
  • array of promoCodes (Optional)

Response: same as for POST /booking, i.e. the usual array of warnings and the resulting booking

To remove: DELETE /bookings/{booking-id}/bookedOffer/{booked-offer-id}

Note: we're not implementing a complete shopping cart function, as there are enough standards out there which specifiy these, e.g. (https://www.tmforum.org/resources/specification/tmf663-shopping-cart-api-rest-specification-r17-0-1)

Note: "bookedOffer" should really, really be "bookedOffers" but that would be a breaking change. See new improvement I-666 for a wishlist of such changes.

2022-10-28 Meeting

OSDM v2.0 RC04

needed fixes in V2.0.0:

Based on RC04

  • POST offers-collection accepts ExchangeOfferCollectionRequest when new offers are requested? And returns ExchangeOffer and not just Offer?
  • same for GET offers/ID ?

Decisions

  • rename POST /offer-collections to POST /offers and POST /exchangeOffer-collections to POST /exchangeOffers
  • delete GET offersand GET exchangeOffers

2022-10-21 Meeting

OSDM v2.0 RC03

needed fixes in V2.0.0:

  • paging (previous/next) on trip collection / trip offer collection has been lost
  • non-trip-offer structure is missing from offer request, however some parameters applicable to it have been moved to offer search criteria (nutsCode, place)
  • should CorporateCode.beneficiary be mandatory on input?
  • why are code and name on Address mandatory?
  • why are PersonDetails included at offer creation time
  • in AdmissionOfferPart (and the other OfferParts as well)
    • availableFulfillmentTypes is redundant with the subfield type of the availableFulfillmentOptions
    • availableFulfillmentOptions should be an array (as it is plural)

Homework: please review the RC.

Further discussions:

(from Linus Johansson) improvement required for the shopping basket functionality: need to be able to review the available options for adding to the basket at a later time. (refer to eMail sent to Andreas and Clemens).

  • discuss in detail at next meeting

(from Patrick Heuguet) What is the status of BoB? Improvement I-66 is still at template status, input will be provided in spring 2023.

PTA’s integration in OSDM

  1. Swedish Market case: SAMTRAFIKEN is hosting in its IT solution (Turnit) all PTA’s sold in conjunction with other mode of transports. SAMTRAFIKEN will manage the integration of those PTA’s inside OSDM. Aside potential template changes, they do not forsee changes in the OSDM API, but should be confirm after detailed study. Target is to have a visibility in spring 2023.

  2. PTA’s distribution standards : As PTA’s world is very heterogenous, there is not a distribution standard emerging, even if with DG Move MDMS initiative we could expect that the sector will progress on standardization.

In some countries, there are standardization promoting at country level like VDV in Germany.

In some other countries like CZ PTA’s are looking at OSDM to become the standard to be used.

Over all, we see three major type of PTA’s type of distribution on the market:

  • The historical Fare Collection system
  • The evolution to account based system
  • The trend to use CheckIn/CheckOut system to calculate the price on a pay as you use basis. The first 2 system could be integrated in OSDM easily, the third one is a more tricky subject for an integration in OSDM

On fulfillment side, the trend is to move from Secure in media (smart card) to secure in system (Smart phone) fulfillment solutions. Integrating the smart card in an OSDM fulfillment process is challenging, Smart Phone could be easier, the distributor producing a secured token that the end user will use on the PTA’s apps on its smart phone to generate the "ticket".

  1. Commercial: Aside the technical challenges above. There is a commercial challenge. Some Railways distribute PTA’s content, but by contract only on their direct channels. 3rd parties distributors will have then to integrate all PTA’s, but with a question mark on the associated business case. Important investment to integrate as no standardization, and low revenue stream due to the level of price of a PTA’s ticket

2022-10-14 Meeting

needed fixes in V2.0.0:

  • add description to POST fulfillment to indicate that this confirms the booking! (in V2.0)

  • add description in POST return offers that this applies to trips only

  • add description of Fee also in the schema / UML model

  • POST offers collection in the version send by mail misses the parameters for non-trip offers --> needs to be fixed in 2.0.0

  • change from comfortClass to travelClass is not jet in the schema update needs to be in the V2.0.0 update

  • the id in the POST refund offers response is obsolete and not documented. To be removed.

  • exchangeOffers in PATCH booking must not be required!

  • descriptions in product got lost:

    • conditions on usage description (as string)
    • regional validity description text (as string) long and short ("Season ticket Berlin and Frankfurt" not more than half of a line) version

  • productLegAssociation must not include product but the productId only. Products are separate and are not necessarily associated with a leg.

  • trip in exchangeOffer should be optional for non-trip offers

  • in embedded tags: BOOKING_RELEASEOFFER, BOOKING_CANCELFULFILLMENTOFFERS, BOOKING_DOCUMENTS is missing

in V2.1:

  • new requirement to add a history on status changes
    • required on the fulfillment including timestamp and status change (Koffi makes a proposal for V2.1)

Modularize the API documentation:

      examples: https://wiki2.railml.org/wiki/UC:Use_cases

       separated per use case and per role:
            - without trip search
            - Reservation
            - without reservation
            - Without Fares
            - no change in pre-booking
            - no return trips
            - Fares only
            - Exchange
            - Claims
            - Reimboursements
            - Webhook on Booking / ...

      solutions:
          - Document which objects/end points are needed for which use cases.
          - Postman collections per use case

2022-10-13 Approval Meeting Praha

The Version 2.0 of OSDM was approved by the workgroup including the last minute change on RESPLUS (still to be integrated in the model):

The Swedish through ticket „RESPLUS“ will be include in OSDM via the generic OSDM through ticket mechanism for Distributors in the offers:

The offer will provide the throughTicketTag

- a dedicated name „RESPLUS“ will be defined for RESPLUS. The string of the throughTicketTag will therefore become an extensible enum with the entry „RESPLUS“
- the throughTicketTags will be moved one level higher from product to commonOfferPartAttributes

Distributors can apply the throughTicket if the tags match and inform the provider in the post booking by providing the throughTicketTag.

The RESPLUS value in regulatory conditions will be removed. The regulatory conditions in the post booking will be removed

The next Increment PI-7 will concentrate on:

2022-10-07 Meeting

Latest Version

https://app.swaggerhub.com/apis/schlpbch/uic-90918_10_osdm/2.0.0-RC02

Relevant for OSDM 2.0

  • Add Booking Part functionality added

Accepted

  • Regulatory Conditions - How to indicate which one was chosen?

Add addRegulatoryCondition to POST booking on OfferSelection level.

Highlight special situation in Swedish market.

Patrick discusses relationship of throughTicketTag and regulatory conditions.

  • ComfortClass to TravelClass?

deprecate ComfortClass and add TravelClass

  • Status on BookingSearch

removed status from response

  • Fixing embed

Outlook

  • Impact of "booking state in leaves" on refund and exchange

    • Do we want to support partial refund / partial exchange(!)

  • Andreas on autumn vacation for the next two weeks.

2022-09-30 Meeting

Latest Version

  • https://app.swaggerhub.com/apis/schlpbch/uic-90918_10_osdm/2.0.0-RC01

  • In the Swedish as well as the Swiss market we need a stable version now, as many parties are depending on it. Thus we propose to do have a freeze phase for 1-2 weeks and then release this version as stable. We propose to call it OSDM 2.0, as we have changed the offer structure substantially. Next we propose to have incremental patches, adhering to semantic versioning.

Decision: Group supports the proposal

Crucial is the following features:

  • adding pre-booked offers to a booking (cart functionality)

  • Next we need to have to prioritize next features/improvements and bundle what we release until the end of this PI 6 (28. November).

  • Additionally, we propose to have a discussion / brain storming about a modularization of the API.

  • Last, we want to switch to Papyrus, so that we no longer have a modelling bottleneck.

2022-09-23 Meeting

Latest Version

  • at the moment there is no alignement on how to distribute bikes or luggage. Two approaches are competing: bikes as passenger types or bikes as ancillaries.

  • multiplicity in the link between offerparts & products: can we have collective offerparts (in pricing or ticketing) but where different passengers have different products

  • we also have to make sure we can support cases with multiple fulfillments (different TCNs) on the same fulfillment DOcument (the model does not seem to support it today

  • https://app.swaggerhub.com/apis/schlpbch/uic-90918_10_osdm/2.0.0-2022-09-22

  • Changes: passengerSpecification for offer request and response and booking request -> passenger is created at booking step only.

Discussion ensues on whether variations could be allowed i the passenger party described in the offer request and the booking request. The consensus is that while it does not impact the API specs, we should give as implementation rule that the passenger party in the booking request has to be the same as in the offer.Should there be a modification, it is up to the provider actually hosting the product to perform the validation. Distribution systems will not do it.

Topics

  • rename comfortClass --> travelClass

Confirm with Clemens that change is reflected in

  • add type to ancillary (caveat: BIKE, LUGGAGE are passenger type)

Discussion: model lugagge / bike can be modeled either as passenger type or as ancillary. Both have pro and cons, the group aggrees that it should be handeled consistently --> needs more discussion

  • Discuss states

Driver I-62.

We currently have status at the booking level, however it might be sensible to have at the leaves of a booking as well:

booking.status
  bookedOffer
    admission   <-- status?

If yes what does that mean for the overall state? We have to ensure consistency.

Same question applies to fulfillment.

No decision taken concerning booking, needs more analysis.

OnBookingStates

2022-09-16 Meeting

Snapshot: https://app.swaggerhub.com/apis/schlpbch/uic-90918_10_osdm/2.0.0-rc1-2022-09-15#/

Challenging use case:

Trip: Basel - Chur - Brig - Blatten (bei Naters)

  • leg_1: optional reservation (flat world train)
  • leg_2: required reservation (touristic train)
  • leg_3: - (bus)

Reservation only scenarios

The Offer API may be approached in three distinct ways

  • User doesn't possess any reservations/admissions (or doesn't provide that information to OSDM), and is presented with offers for admissions, mandatory and optional reservations. Validation that admissions cover entire trip and all mandatory reservations are selected is applied.
  • Power user or distributor requests reservations only and optionally details travel class. OSDM provides an offer that covers 1 or more trip legs. The user may select 1 or more of these reservations in booking step. Mandatory reservations are not enforced in reservation-only scenario.
  • (API needs to be reviewed/designed) User specifies which admissions/passes/reservation does possess, OSDM offers admissions and reservations to complement the entire trip.

Review

Remove addmissionSelection as if you book the offer then the admissions are being confirmed as well.

Show on-hold modelling:

booking-state-model-with-onhold-state

2022-09-09 Meeting

  • walk trough of proposed changes

Requirements

  • An offer needs to cover a whole trip or even a set of trips (return trip).
  • Todos
  • Review return trips and partial trips
  • trips-collection request or tripSeachrCriteria in the offer-collection request: How to handle meta stations with merits ids?
  • fix patch bookings
  • cart functionality

PATCH /bookings/{bookingId}/bookedOffers

GET /bookings/{bookingId}/bookedOffers

DELETE /bookings/{bookingId}/bookedOffers

Add BOOKED_OFFER_STATE

2022-09-02 Meeting

  • Thoroughly review the changes (
    • CommonBookingPart / using inheritance?
    • NonTrip Offers broken

2022-08-26 Meeting

  • max length of a string, especiall of id strings
  • present v1.5-rc3
    • open question: Can we split Admission in AdmissionOffer and Admission etc.

Summary of discussion

Splitting ReservationOffers and Reservation is agreed on

Rename /offers/{offerId}/reservations/{reservationId}/ to /offers/{offerId}/reservationOffers/{reservationOfferId}*

Two flows

a. First get offers and then call available places (supported)

b. First pre-book offer and then call available places (not yet supported)

Modelling the two flows.

GET /availabilities/nearBy/?contexId={contextId}&contextType={offer ¦ booking}&resourceId={resourceId}&resourceType={reservation ¦ fare}

GET /availabilities/placeMap/?contextId={contextId}&contextType={offer ¦ booking}&resourceId={resourceId}&resourceType={reservation ¦ fare}

GET /availabilities/placeProperties/?contextId={contextId}&contextType={offer ¦ booking}&resourceId={resourceId}&resourceType={reservation ¦ fare}

  • Question by Turnit

    Provisional price vs confirmed price

    What is the provisional price in relation to the confirmed price? Is the idea that you can present both the price of the offer response and the price of the booking response in case of a price difference between offer and booking?

    Carrier vs Operator

    In the TimedLeg in the tripLeg, “operator” is used to identify a company, but on other places the word carrier is used. We believe “carrier” is more widely used in this context, but there might be some other good reason to use operator instead of carrier?

    Discounts:

    As we see it is possible to apply a discount with a discount card or get an offer with a campaign code.

    But there are also needs to apply a discount on an offer that not really are a campaign and not are driven of a discount card.

    E.g. When issuing a replacement ticket for a delayed passenger it should be possible to issue a new ticket on a later train for free. But there might be other use cases where a passenger is entitled to a discount without having a card tor present.

    Applied promotion code and corporate code:

    appliedCorporateCodes and appliedPromocodes are available on booking level and the appliedpromocodes are also available in common offer part attributes, we think it should be on offer level.

    Suggestion, add appliedCorporateCodes to common offer part attributes.

    Is there a use case for keeping them on booking level?

    Purchaser

    I the Post (and patch-) booking request you can add the “Purchaser”.

    It seems like the purchaser is a physical person only, we believe that it also could be a company, could a new element Company name be added in the Purchaser details?

    Creation time of booking

    The getBooking (and the future searchBooking-) response should contain the creation datetime (and timezone). The value should show when the booking (I guess pre-booking) was made.

    There are needs to make it visible to the user when the booking is done.

    “Booking on hold” – (“Stored” but not paid/fulfilled)

    This might be a bit bigger task.

    As we see it the time between pre-book and confirmation (TicketTimeLimit) is expected to be 20-30 minutes. When the booking is confirmed, an economical transaction has been created between the distributor and the allocation system.

    We have some use cases where it is expected that an agent should be able to make a booking “put it on hold” and maybe some days (or weeks-) later continue with to fulfillment.

    Is this anything that we have thought about in another way?

    State diagram (states of booking)

    In the booking diagram it seems to be two ways of going from pre-booked. When are the “confirmed” step used? or rather, when do we not go direct between pre-book and fulfilled?

    Currency object:

    When looking at the currency object one can believe that it is an array of currencies, but we believe that it is just examples, and only one may occur at the same time. Perhaps it would be better to just have “EUR” as example.

  • Revise Compliance

2022-08-19 Meeting

  • Changes to the v.1.5 specification

    • "You have to by n out of m ancillary/reservation" can now be expressed via Ancillary Relation / Reservation Relation

      Use cases exist in Sweden for breakfast, in Switzerland for touristic trains, and in Austria

  • Questions by öBB

    • tripId missing in POST offer-collections

      Add as third parameter to query offers.

    • How to deal with unsupported parameters (e.g. filters in place request) in requests.

      Return a response with a warning object indicating that the optional request parameter was ignored.

      Return an error "NOT SUPPORTED" if the parameter is required.

    • How to deal with places that do not have UIC code?

      Return the place id in an alternative namespace "x_swe:std:3452345" / "eva:stn:444444"`

      /places return alternativeIds if available

      inform Fabrice

2022-08-12 Meeting

  • Fulfillment Types and Fulfillment Media Types

Proposal from Ralf:

-- Remaining Fulfillment Types

Code Description
ETICKET Printable electronic ticket
DTICKET Fully digital ticket
CIT_PAPER Value paper
TICKETLESS No ticket, customer needs to provide means of identiy

-- Fulfillment Media Types referenced to Fulfillment Types

Code Applicable to Fulfillment Type Description
RCT2 CIT_PAPER RCT2 secure paper format (including compressed format)
RCCST CIT_PAPER Credit Card Size format
UIC_PDF ETICKET PDF according to UIC Standard
PDF_A4 ETICKET proprietary A4 pdf format
PKPASS DTICKET pkpass file format (‘wallet’)
ALLOCATOR_APP DTICKET mobile ticket in allocator specific format to be loaded into mobile app
NONE TICKETLESS no ticket, however the customer needs to informed that no ticket is needed
NONE DTICKET digital ticket has been referenced to chipcard number given in booking request (passenger.card.number)

2022-08-05 Meeting

  • How to do patches in UML?

  • tripSpecifications and requestedSections: how much of the trip needs to be spanned

    • For fares requestedSections is mandatory
    • We can not force a caller to pass in the complete trip.
    • For correct pricing in an international context we need to know the leg at least.
    • However it's useful to know the complete trips for other processes, such as operation planning.

  • reimbursemnt readded

    • not mandatory from a specification point of view, however if required by law needs to be implemented (E.g. Germany)
    • candidate for modularization

  • Fulfillment Types and Fulfillment Media Types

    Code Applicable to Fulfillment Type Description
    RCT2 CIT_PAPER RCT2 secure paper format (including compressed format)
    RCCST CIT_PAPER Credit Card Size format
    UIC_PDF ETICKET PDF according to UIC Standard
    PDF_A4 ETICKET proprietary A4 pdf format
    PKPASS DTICKET pkpass file format (‘wallet’)
    ALLOCATOR_APP DTICKET mobile ticket in allocator specific format to be loaded into mobile app
    TICKETLESS TICKETLESS no ticket, however the customer needs to informed that no ticket is needed

    What I’m wondering is what the exact meaning of the pass chip / pass reference is, and whether a fulfillment type is missing for “TICKETLESS”.

    • PASS_CHIP: The pass is loaded onto the chip. For example multi-journey tickets can be loaded on passes.
    • PASS_REFERENCE: Only a reference to the pass is loaded onto the chip. For example the SBB Half Fare Pass is reference by the SBB pass card.

    To do: final proposal by Ralf for next week.

  • Need for "Remise à disposition (RAD)" Supporting Carriers

    • SNCF, SJ, DB

    We need two steps for this process

    • refund done at the station (not the travel agency) calculating the refund fee and releasing booked places without accounting / payment
    • refund at the agency for the payment and to trigger the accounting

    We need to extend the refund state model:

    • Currently: PROPOSED --> CONFIRMED
    • New: PROPOSED --> ACCEPTED (booking is “refunded” but payment and accounting are pending, maybe there is a better word) --> CONFIRMED To go from PROPOSED to ACCEPTED we can use the existing PATCH with the new state.

2022-07-29 Meeting

  • accommodation sub types (cleanup and ÖBB comfort types)

    • remove SEPARATE_COMPARTMENT
    • add NEAR_WHEELCHAIR used to indicate places near the wheelchair when booked by an accompagning person.

    changed group names:

    • BERTH_LOCATION --> PLACE_LOCATION
    • PLACE_POSITIONING --> PLACE_ALIGNMENT
    • LEVEL --> DECK

  • reimboursement

    • to be discussed with andreas why generation failed (+ enum --> extensible and Notification Code)

  • change of seat - documentation

    • issues found by DB (Ralf)

       In TripOfferRequest the structure to limit the priced offer to a subset of the trip is placed in the TripSearchCriteria sub-structure, where it does not make any sense at all – when using TripSearchCriteria, there is no predefined trip which is being input, therefore the caller cannot specify for which legs/stations they want an offer. The requestedSection attribute should therefore be moved from TripSearchCriteria to TripSpecification. Comments need to be adopted as well.

Symmetrical to the requestedSection, the provider should be able to specify that the offer given only covers part of the trip. This is “kind of” there, but there are multiple problems: The relevant structure (coveredLegIds) is present in “Offer” and “BookedOffer”, neither of which is returned by an offer search – the offer search returns an AbstractOffer. It think we have a problem with the inheritance structure between Offer, AbstractOffer and BookedOffer which we need to clean up.
      • patch will be provided for 1.5 (Ralf)

  • more fulfillment types for mobile tickets (Ralf)

    fulfillmentMediaType: - ALLOCATOR_APP content to be imported to an app of the allocator or bilaterally agreed

     securityElementType and format should become extensible enums and should be explaingd in the code list.

2022-07-22 Meeting

remaining tasks in 1.5:

  • review of reimbourcement

  • request data are not in the patch request

  • reason should be an extensible enum

  • notification on the decision made should be added via webhook

  • change of seat

    • documentation missing (Roland)

for 1.6

  • combination of ancillaries (Andreas)

  • request a fulfillment again (after it is expired) or resend an fulfillment document by e-mail

  • I-61 needs more descriptions

  • I-59 to be splitt into separate topics

  • I-6 collect input for the topics (UIC Door2Door Project, NS bicyles,...)

2022-07-15 Meeting

  • OSDM API generated from UML model is available for review.
  • Clarify passenger ids in /offers and /bookings

Add id to PassengerSpecification and use it in the Offer flow (response and request)

Add optional gender to PassengerSpecification

Pass in PassengerSpecfication in /bookings and only create a Passenger in the Booking response.

  • New needs
    1. one-of the reservation offers needs to be booked
    2. one-of the ancillary offers in category needs be booked

Resolution for Reservation

Todo ASC

Resolution for Ancillary

 "ancillaryOptions": [
    {
      "ancillaryReferenceGroup": "Meal",
      "minimalSelectableOption": 1,
      "maximalSelectableOption": 1,
      "selectableIds": [
         "2-Course-Menu-Id",
         "3-Course-Menu-Id"
     ]
    },
    {
      "ancillaryReferenceGroup": "Souvenir",
      "minimalSelectableOption": 0,
      "maximalSelectableOption": 3,
      "selectableIds": [
         "Heidi-Puppet-Id",
         "Picture-Id",
         "Puzzle-Id"
     ]
    }
   ]
  • rename:
    • optionalsReservationIds --> reservationIds
    • optionalsAncillaryIds --> ancillaryIds

Rename is ok, we will also have to add all reservationIds

  • Use case optional place properties not respected --> need for message?
  • New improvments I-61, I-62, and I-63.

2022-07-08 Meeting

  • Small Issues in OSDM 1.5
    • Fix Fulfillment Patch Part
    • Applied CorporateCodes
    • getZones(): What is returned?
    • PaymentMethod.money
    • Improve documents

Voiding tickets needs an improvement

  • Functional Questions

    1. Let's say I need to travel between A and B two times next week. So, I need to buy 2 round-trip tickets (A <-> B).

      1. How should we handle round-trip tickets? I guess it's two separate offers - one for outbound and one for inbound. And if I have two of them then I'll end up with four offers.

        Some of our customers use "round-trip pricing", i.e. if you buy one round-trip instead of two one-way trips (separate trips for outbound and inbound) then you'll get a better price. How could that be handled?

      2. Multiple journeys in one booking vol 1 - let's take a case where I would like to buy two round-trip tickets. I couldn't find a way in OSDM to add additional offers to an existing booking. Should the offer searches be conducted for all the journeys first and then added all at once? If there is a race condition caused by capacity limitation then you may end up losing a place if you can't book it right away.

      3. Multiple journeys in one booking vol 2 - let's say I have managed somehow to add all my four offers to the booking and for some reason would like to remove one of them (because I just remembered that my dear friend John promised to give me a ride). Not sure how to achieve that in OSDM.

Round trips are supported (see: returnSearchParameters)

  1. It seems that the ancillary services that can be added as optional ones (not included in the trip offer) cannot be related to any of the legs. Let's take a case where I booked a multi-leg journey and I would like to add breakfast for leg 1 and lunch for leg 2. How to implement it in OSDM? (see ancillary-->commonOfferPartAttributes-->products-->legIds)

Needs two improvements

  1. Add/remove elements to a unconfirmed booking ("cart functionality")
  2. Add elements to a confirmed booking

2022-07-01 Meeting

Version 1.4.2 officially released.

  • Do we have the need for a mechanism to rely messages directly to passengers?

To do: find convincing use case in a new improvement.

2022-06-24 Meeting

From OSDM Meeting/Call 2022-06-23

  • Reminder: OSDM logo is approved and should be used along with osdm.io domain to promote the specification

Publish logo on the website - Clemens

  • Announcement by DB: DB starts the implementation of OSDM with Phase 1 - Products (2022-2025) and Phase 2 - Fares (2025 and beyond). OSDM will publish the announcement in the community channels

To provide overview how the OSDM is used, please update Implementation Details with your projects, and possibly technology details if possible.

We need to create separate page for implementations, functional part coverage. Josef to start, consult Clemenc, Andreas on major functional parts, share in community.

Completion of PI-5

  • #278 Update of terminology: Clemenc, what is the status? We are waiting for contribution of Stefan Jugelt from ERA on 28.6.?

Replace Ticket Vendor to Retailer. Changes on the website only. Wording will be provided on Tuesday June 28.

  • #284 Revise embeds: Andreas - does it cover selected endpoint, or entire OSDM online?

ReDoc might not be updated, embed "TRIPS.PLACES" was already removed from 1.5.0 POST /trip-collection remove this embed check if conflicting changes happen or not

  • Pagination - issue, assignment, what is needed

rel was added, _links is missing yet See https://github.com/UnionInternationalCheminsdeFer/OSDM/commit/ab977e9a70e9af3b1e29cfd7df0795ee6276d2fd

Andreas to restore the old branch with former implementation.

still awaiting PR, could be contributed by anyone, not a blocker of I-32 CO2 report is implemented

  • I-46: Change of Seat after Booking: documentation is missing. Who will provide?

Roland will provide PR for documentation

Scope of PI-6

Epics, Enablers

  • Tooling and guidance for UML modelling of OSDM

Probably to first tasks to do, to spare the double work in UML and YAML Combine online and webhooks yamls

I-6 to be expanded; for the implementation, split to tasks covering required features

VAT exemption - elaborate with Swedish Team why it should be part of trip and request VAT exemption is also needed for Czechia, Slovakia VAT exemption vs VAT deduction Bileto to provide basic support for agencies paying turnover tax instead of VAT ? Margenbesteuerung / margin taxation

Additional parameters for booking search - e.g. possibility to search bookings by passenger details Booking search was part of 1.3, and removed later Search to be reintroduced Separate search by personal data (POST with body)

Ticket validation - outside of OSDM, please see UIC-IRS-90918-4 (ETCD)

Additional support for multi-ride/passes - support already included Clemens to check if the API provides information about remaining validity

Flag to indicate if passenger DoB is derived (by age) or provided (by passenger) Boolean indicator if the DoB is derived/provided vs separate property "pricing age" Additionally, how to have correct pricing age for return journeys (probably covered by terms of conditions only, not OSDM) PassengerSpecification and Passenger must be adjusted

To be discussed

  • Establish Certification Process (PATRIC group) -- Engineer requirements for the automatization of the certifcation process
  • Validation test set -- Review each others POSTMAN collections
  • Documentation update -- Clarify dealing with passengers without need for a ticket.
  • Security review --> 42Crunch
  • Model hardening with edge cases (non-happy flows)

2022-06-17 Meeting

  • Switched to Redoc

ok

  • Fixed bug in PlaceRef concerning GeoPosition.

ok

  • Fixed externalRef (#273)

ok

  • Todo embed: fix, reduce or remove

add _links to PlaceRef, add rel to links and review embed.

  • Short demo of new version of sandbox

Thank you Tim, Roland and Sqills

  • Discussion

improve the documentation of POST fullfilments

add POST, GET, DELETE /documents

fulfillment.document -> fullfilmenetDocuments

Add "DOCUMENT_AVAILABLE` event

Koffi prepares patch

2022-06-10 Meeting

Merged

  • Updates from SJ @stina

Must have features are in, PR soon avaible

PR merged

  • On placeRef: The specification is correct, however the UI of Swagger has problems in properly displaying inheritance.
    • Possible action: Use ReDoc instead.

Switch to Redoc

2022-06-03 Meeting

Accepted

  • Fix externalRef

Patch will be provided

  • Adding an AbstractOffer -> Version 1.4.2

Decision: Release 1.4.2 is accepted

Transforming CommonOfferPart into inheritance in 1.5 - Decision: Model first and then check with group

Adhere to semantic versioning --> 1.5 becomes 2.0 - Decision: right thing to do, as we claim to support semantic versioning.

Design defined, needs a patch.

  • Points identified by Turnit:

    1. POST /trip-offer-collection response doesn't contain operator names. The names are needed for displaying in the sales applications. Would it be possible to add the names to the response?

    Add operaterName to DatedService (extension to OJP)

    1. POST /trip-offer-collection response doesn't contain the service/timetable attributes like WiFi, A/C, WC, etc. Hafas supports it and perhaps it would be a good idea to support it in OSDM as well?

    Needs to be added, check OJP how to do it.

    Facilities are part of the of attributes in DatedService

    Service Facilities in the code list needs cleaning

    1. In some cases the response of POST /trip-offer-collection may contain offers for hundreds of trips (e.g. airport shuttle that departs every 5 to 10 minutes) and there is a need for pagination. I read from swagger that _links[] can be used for pagination. Do you know if anyone has already implemented pagination this way?

    See OSDM Pagination.

TODOs

  • Update pagination documentation to match actual specs

  • Add a "query" parameter allowing to steer pagination using a parameter (as opposed to just linking to the next/previous tripcollection id, for trips) => Nicolas Selleslagh to update

    1. The abstract property name needs to be changed to "summary" in 2.0 as it causes problems in code generators for languages where this is a reserved word. We should apply this to 1.4.2 as well, even though it is strictly a breaking change => to be documented as deviation from the semantic versioning guideline. Update: was actually supposedly changed already in 1.4.0. Is only still visible in callbacks => to be updated as well => Koffi to do the update

    2. Question from Sqills (Tim): Origin & destination in tripsearch criteria now only contain the discriminator objectType, and not the place where the ref can be placed

=> must be corrected before publishing

2022-05-20 Meeting

  • Refund of unused tickets

    Extended RefundOfferRequest

TODO align Overrule Codes between yml and documentation

  • Reseller Authentication

    Towards the remote inventories themselves most likely tokens will be used, but we have a chained situation in Sweden where the reseller connects to a GDS, who connects to an allocator, and then to the individual inventories. We would like to explore the possibility to transport identifying information in the header or the payload as a compliment to the token management.

    TokenFlowOSDM

2022-05-13 Meeting

  • We have moved to osdm.io.

Hurray!

  • Present OSDM modeled in UML (SBB)

Potential on the approach is big, we try it using lead modelers for a start.

  • Adding an abstract class to offer

Accepted.

  • Present Work on I-49 Change of Seat after Bookings (Sqills/Amadeus)

Tim will add analyses to page.

  • Ability to tag certain legs as being part of a train “alliance" (SJ)

Slides

image image

The experts continue working on finalizing a proposal

  • Address issues identified by Sqills

Using the UML model should help in keeping consistency.

2022-05-06 Meeting

  • OSDM EC Meeting
  • Designed I-47, I-51, I-52, I-54, I-55 and I-56.

2022-04-29 Meeting Minutes

No meeting due to many absences.

2022-04-22 Meeting Minutes

  • Present work on I-49 Payment information

    • solution is available in a separate branch extending the patch booking service
    • more payment types need to be added E_PAYMENT,..
    • alignment with I-48 needed

  • Present Work on I-48 Payment by Voucher

    • solution is available in a separate branch extending the patch booking service
    • alignment with I-49 needed
    • passengerIds shoule be optional (Gift-Voucher, Merchandising)
    • process description
    • vcode and issuer should be manadtory (also for Promos)

  • Present Work on I-58 Corporate Code

    • solution is available in a separate branch extending the patch booking service
    • companyRef to e renamed to issuer
    • beneficiary is a name
    • code and issuer should be mandatory

  • Train Facilities --> To be continued on the next meeting

    • facilities per class needed?
    • clean-up of codes, remove codes not used in MERITS --> Fabrice??

  • Ancillaries --> To be continued on the next meeting

    • use standard codes (urn and add a list in the code lists urn/uic/osdm/anc/... ) for "category" in the ancillaryOffer, not just a string
    • check for codes in NeTEX, MERITS/TAP-TSI-/Train Facilities
      • PAYMENT_VOUCHER
      • MERCHANDISE_PRODUCT
      • LUGGAGE
      • ...
      • generic types ON_BOARD_SERVICE, FOOD_ON_BOARD, ...
      • content from NetEX: NETEX SUPLEMENT_PRODUCT does not fit as it includes admissions and reservations and is lacking most other items. Useful to be reused is LUGGAGE, MEAL and WIFI which are in the Train Facility list already and additionally PARKING.

  • TODO add description on the urn for codes within an company defined list (currently used for stations) --> Nicolas

2022-04-15 Meeting Minutes

Good Friday, no meeting

2022-04-08 Meeting Minutes

  • Issues found by SBB's öV platform team; suggestions for Java/C# compatibility of openapi spec to be provided as PR

OSDM v.1.4.1 to be released until 2022-04-14

  • Next OSDM Meeting June 23th in Utrecht

Hybrid Meeting

  • Asc on vacation for two weeks

Clemens holds Meetings

2022-04-01 Meeting Minutes

  • Announcement by Turnit

  • Work on I-53 and other open tasks

Clemens has prepared a patch (https://github.com/UnionInternationalCheminsdeFer/OSDM/pull/263)

Added activation to fulfillment state diagram

  • Work on I-58

Review

  • Company--> CompanyRef
  • CompanyCode --> CoporateCode
  • add list of CorporateCodes
  • Work on I-43

Review incorporated

2022-03-25 Meeting Minutes

Roland & Nicolas for the exchange part including place selection.

Clemens has prepared a patch (https://github.com/UnionInternationalCheminsdeFer/OSDM/pull/263)

2022-03-18 Meeting Minutes

  • Fix "PlaceRef" in V.1.4

keep oneOf semantic and remove topographicPlaceRef

  • Fix recursion on ViaStations

Remove routeand alternativeRoute for now, properly fix as soon as Clements is back.

2022-03-11 Meeting Minutes

  • Walk through of lastest changes to OSDM
    • Added cursor based pagination
    • Added proper HAL-JSON support
    • Renamed booker to purchaser

Accepted, remove cursor.

  • Address findings of Elisa for v.1.4.

Accepted, ASC will patch.

  • Address feedback by Nicolas on v.1.4.

PRs merged

2022-03-04 Meeting Minutes

  • Announcement by SJ and Samtrafiken to us OSDM for their new platforms.

Great news for the adoption of OSDM!

  • Walkthrough of latest changes to Version 1.4.
    • better support for real-time message
    • added booked offers

Accepted

Idenified an issue with scrolling that needs to be addressed.

  • Add "Verwaltungscode" optionally to denote with company is really running the vehicle within a country.
    • E.g.: urn:uic:rics:1185:000044

Accepted

from/until for temporal

start/end for spatial

bay vs quay vs terminal --> stopPointName

2022-02-25 Meeting Minutes

  • Walkthrough of recent changes to Version 1.4.
    • simplification on trip structure
    • tariff in product

Approved

  • Define necessary attributes of booker

Some systems do not support bookers. If a booker exist, only firstName and lastName are mandatory.

2022-02-18 Meeting Minutes

  • Information on Gap Analysis
  • Finalize Webhooks
  • Add feedback from öBB

2022-02-11 Meeting Minutes

  • Feedback on executive commitee 31/01/2022 (Andreas)
  • API versioning & production upgrade planning (Josef)

Best Practices

  • Add no major version to the path
  • Respect semantic versioning in OSDM spec versions
  • Optionally: support content negotiation
  • Support of the lastest and latest-1 versron at least
  • A version should be supported for at least to OSDM PIs, where a PI is ~4 months

operatorRef --> operatorRefs

legStop --> legBoard, legAlight...

2022-02-04 Meeting Minutes

  • Finalize web hook specification.
    • recommended receiver action
    • documentation: how it works, how to use it
    • Misalignment discovered between use case on trip events and expected logic . Leads to needed update in the booking design so it is possible to retrieve both saved trip and real-time version of
    • Trip event seem irrelevant in the context of OSDM. Only booking event which may consist in an updated on a related trip is relevant. Means that booking updates will be sent by RUs when a trip is modified even in case of open tickets.
    • BOOKING_CANCELLED EVENT is put in question:cancellation event should not be relevant: each party should proactively clean up when a cancellation occurs.

the trip (with a clear distinction) => Subject to a future fix

  • Clarify Question on Coach Layout: https://github.com/UnionInternationalCheminsdeFer/OSDM/issues/244

  • Passengers without ticket: is it something we really want ? If so what are the exact requirements

  • Assess whether we are ready with next version

  • Review the TripSpecification: Is asking whether the latest updates on tripSpecifications have been committed & merged on the 1.4 branch.

2022-01-28 Meeting Minutes

  • Superfluous entry/exit points in fare

Not needed, Clemens will do a patch

  • Debriefing meeting with DG Move / Shift2Rail

Shift2Rail bases there work on OSDM modelling of distribution

Follow up: Define an Improvement to address functional gap in fare offline

  • OSDM for Buses, Josef prepares a deep dive

Bileto: Buses in OSDM

  • Review the TripSpecification

Patch looks good

But readd fare connection points

ASC prepares patch for client credential flow.

2022-01-21 Meeting Minutes

  • Concerning the length of vehicleNumber the size of H/H the field is restricted to 5,

    • I see two possibilities, either constrain vehicleNumber to max 5 or add a vehicleNumber.

    Decision:

    • Leave vehicleNumber and add a comment concerning the limitation of H/H. This reflects the commercial train number, no the operational train number
      • In Merits there's a field of 35 characters.

  • On trip: We see two scenarios

    1. The trip is created by the caller, i.e. the distributor

      To identify the requested trip, the relevant attributes per leg are:

      • origin and destination per scheduled legs (legBoard.stopPlace.stopPlaceRef)
      • vehicle number (legBoard.service.vehicleNumber or logBoard.service.lineNumeber respectively)
      • departure times (legBoard.stopPlace.serviceDeparture.timetabledTime) with a certain fuzziness of +/- 5 Minutes

      Review:

      • Naming: TripSpecifcationand TripLegSpecification
      • Add lineNumber as alternative to vehicleNumber (especially for regional traffic)
      • Add array of vehicleNumber and lineNumber
      • A allocator should be flexible in matching departure times, however it's up to the system to define, if the trip matches.

    2. The trip is created by the receiver, i.e. the allocator

      To communicate the trip to the caller and the passenger, to following attributes need to be set:

      On Trip level:

      • tripId
      • duration
      • originand destination
      • origin (origin.stopPlace.stopPlaceRef and stopPlaceName) and destination (destination.origin.stopPlace.stopPlaceRef and stopPlaceName)
      • transfers
      • startTime
      • endTime
      • on TripLeg level:
        • legId
        • on TimedLeg
          • legBoard.stopPlace.stopPlaceRef and stopPlaceName and serviceArrival or serviceDeparture
          • legBoard.plannedQuay - SNCF only publishes this information shortly before
          • service.productionCategory.shortName and .name
          • vehicleNumbers xor lineNumbers
          • operatorRef
        • on TransferLeg: no changes
        • on ContinuousLeg: no changes

      Add to version to v.1.4

  • How to use vouchers which we give out in complaint management

    • Def. voucher: form of payment
    • Next Step: define improvements to properly plan and scope:
      1. Indicate form of payment of a booking as it has impact on after sale (real currency / virtual currency)
        • Koffi-Frédéric formulates improvement for v1.5
      2. Use "payment vouchers" <== ERA / TAP- TSI relevant
        • Clemens and Ralf formulates improvement for v1.5
      3. Redeem loyalty points
        • Address later

  • Reimboursement

    • Clemens has defined a version and will define a pull request

  • Claim Managements

    • a claim needs an id
    • train number --> vehicle number
    • remove iban --> accout number

  • Fix tripSearchCriteria

    • tripSearchCriteria.TripRequest for round trip with one leg

  • Operator change on a trip leg - how to deal with it?

    • Example: Chur to Brig

2022-01-14 Meeting Minutes

  • Address issues found in v.1.3.0:
    • Access-Token --> Authorization - accepted
    • trips.startTime | endTime | transfers optional, as redundant to same info in leg - rejected
    • Def. MOUNTAIN_TRAIN
    • publishedServiceName optional - rejected its Service Brand Code of Merits
    • tripLegIndices --> tripLegIds - alternative approch, use a tripRef, to be defined
    • tripKey: What is semantic? --> "externalRef" - accepted
    • passengerIds: add array - accepted
    • product.code: make mandatory - accepted
    • accommodationSubType: make mandatory
    • coveredTripLegIndexes --> coveredTripLegIndexes
    • add FEE as enum to requestedOfferParts - rejected, clarification in documentation that fees are returned as part of admissions or reservations if exsiting
  • Reimboursement of unused tickets (I-48)

OSDM Wiki

⚠️ **GitHub.com Fallback** ⚠️