Skip to content

Meeting Minutes 2023

Jump to bottom
Andreas Schlapbach edited this page Jan 5, 2024 · 2 revisions

2023-12-15

  • Presentation by Eurail on their plans/needs from OSDM.

Discussion:

  • Eurail is interested in providing its offers using the OSDM standard.
  • Use cases identified are:
    1. Sell Eurail/Interrail passes in a non-journey based flow.
    2. Upsell Eurail/Interrail passes as part of a journey based flow. If its the cheapest offer we are legal obliged to present it to the customer (Personal Rights Regulation).
    3. Activation of travel day and journeys for a given pass.
  • Eurail/Interrail passes change prices once a year, except for promotions
  • OSDM supports non-trip based searches, as well as the activation of days. OSDM has the notion of a travel account. The reservation can be distributed using OSDM.

2023-12-08

2023-11-24

Mediatype: application/vnd.uic.osdm+json;version=3.0 parameter version is required.

I-6:

TODO:

  • Investigate the mapping OSDM - TOMP for a Use Case: Retailer via OSDM to Distributor via TOMP to TO (selling the first/last mile)
  • Check EU survey on MASS APIs
  • ask EC for participants with interest in implementation

2023-11-17

On Demand Services to be discussed next Friday OSDM/TOMP/BOB

2023-11-10

2023-11-03

2023-10-27

See discussion in the issue.

Should have multiple reservations with different covered sections, and tie them together in the provider system so they cannot be refunded separately. Price to be put on one (e.g. the first) of the reservations.

Linus will check whether this will fill the need.

Discussion was to add the new attributes (bookingPartIds, passengerIds) to the message in the origional refund offers endpoint, so we don't need a new endpoint.

RENFE prefers Option 2 (Mandatory last name field with all words in the last names), and optional fields for two individual last names.

lastname1, lastname2: numbered field names are confusing - the API should be more self explanatory.

Option 3 (with additional condition: maxitems = 2) would be technically better.

No decision possible today.

This would be a breaking change, but the feature is not urgently needed. We will retain this until version 4, but provide a nonbreaking (but more cluttered) change in case the feature is needed before we're ready for the next major version.

  • Inconsistent attribute name: the warnings attribute is called warning (singluar) in the responses to POST trips-collection an GET trips-collection/{trips-collection-id}. Klaus will raise an issue to correct this, but this will be breaking and needs to be postponed to version 4.

  • Question about provisional/confirmed price in the booking. Can the price change when the booking is confirmed?

Provisional booking is created, provisional prices is 100€, the booking is confirmed without any changes --> assumption would be that the confirmed price is then always 100€, and cannot change due to the confirmation process.

  • Question about "confirmableUntil" - this is not relevant in a confirmed booking. So semantically this should be made optional.

Stina will raise an issue. https://github.com/UnionInternationalCheminsdeFer/OSDM/issues/369

2023-10-20

2023-10-13

Discuss some issues with OSDM version 3.1

  • Split Booking - this needs the ID of the booking to be split and should be aligned to endpoint structure (POST /bookings-split becomes POST /bookings/{bookingId}/split)

  • Passenger/PassengerSpecification - contact detail is here twice (both at the top level of Passenger/PassengerSpecification and within PersonDetail. Remove "contact" from the Passenger object and from the PassengerSpecification object (as they were new in 3.1 - no need to deprecate)

  • Partial Refund (POST /bookings/{bookingId}/partial-refund-offers - nobody really understands how this works, so remove it from 3.1 (for now)

Everyone should do a review of 3.1 as it stands now.

Josef demonstrates GitHub features.

  • Agreed to convert the issues/improvements from the pure wiki pages to GitHub issues

Nicolas asks what to use when a mobile app just needs the barcode from the fulfillment. Use type=ETICKET and mediaType=RETAILER_APP.

"Ticketless" is supported. Some operators still send SMS (text) messages with ticket information.

2023-10-12

  • PR #353 contains all missing changes in 3.0.3 to be included in 3.1.0. Additionally, it provides fix to support data patch of Purchaser seeking by Nicolas and PersonDetail.taxId seeking by Josef for Polish market.

2023-10-06

This is a no longer valid. OpenAPI Generator 7.0.1 fixed the issue.

  • review of code list for product type

  • benerail/Sqills: requestedSection element needs some rework:

    • are legIds relevant here ? the tripspecifications do not provide any id for the legs so not possible to refer them using ids. Might be usable in conjunction with providing a tripId but not sure anyone wants this => remove ?
    • if multiple trips or tripspecifications are provided, no link can be indicated between the trip/tripspecification and the related requested section => we believe requestedSection should be either a subelement of tripspecifications or contain a reference to the tripspecification (externalref ?). Ifproviding tripIds remain, then the reference should aloso be possible on tripId

TODO add optional in Section externalTripRef referencing the externalRef of the Trip Object in 3.0.3 and 3.1

  • publish Releases 3.0.3 and 3.1

  • benerail: carrier as optional info ?

    we atm provide operating carriers as offers attributes,not schedule attributes. Is there a reason for making this a mandatory element on schedule-only endpoints(trips and tripCollections)

benerail will check to solve this internally

  • Second last name in passengerDetails

    Proposal:

    • Adding an optional second last name to have multiple last names in separate fields

    • Most systems will send the names in one field (concatenated) - Is this a problem for systems using two fields?

    • Some systems will send two last names - would it be ok to print only one?

Option 1: one optional second last name

  • a retailer is allowed to ignore the second optional name and not provide the name separately
  • a distributor is allowed to ignore the second optional name and use only the first last name

Option 2: lastName hold all last names as today and is mandatory

  • optional element firstLastName holds the first last name and can be ignored
  • optional element secondLastName holds the second last name and can be ignored

TODO: discussion on use cases in 2 weeks

2023-09-29 Meeting

  • SJ: Addition of a DELETE /bookings/{bookingId}/booked-offers/{bookedOfferId}/admissions/{admissionId} to be able to remove individual passengers for a npn-confirmed booking

remove an admission before the booking confirmation. It is up to the provider to change or remove dependent bookedOfferParts. A repricing might occure. This function is optional. Similat as for reservations and ancillaries. TODO in 3.1 and in 3.0.3 (Change: Clemens)

  • Samtrafiken: Rename BookingRef in Booking to BookingCode in 3.0.3 to avoid confusion with BookingRef in Fulfillment

(TODO change by Josef) Booking:

  • rename bookingRef to bookingCode in Booking and bookingPartRef in AbstractBookingPart to bookingPartCode BookingSearch:
  • add bookingCode , bookingPartCode
  • deprecate distributorBookingRef, retailerBookingRef
  • add externalRef The unique booking reference in the distributor/retailer system. Usually refers to an order number or PNR.

  • Turnit: How to enter a new home address to a prurchaser? Currently a known addressId with URN is needed.

    Temporary solution is to provide some id. (address is definedcompliant with OJP and unfortunately three an id is mandatory. We allow any kind of id).

  • Turnit: How to update a purchaser

  1. Always send in all information and replace with that. A PUT approach
  2. Only update given elements. How in that case can a companyDetail be removed? Alignments is needed.

    Only update the given elements TODO: (Change Joseph in 3.0.3 and 3.1)

  • make Address nullable to be able to delete the address
  • make CompanyDetails nullable
  • make PersonDetails nullable
  • TaxId for persons - Billing in Poland requires the printing of the personal taxId of a Purchaser TODO: add taxId as optional element in the PassengerDetails (Change Joseph in 3.1)

2023-09-22 Meeting

Code list for product type:

      TRAVEL_ACCOUNT  - travel account (not an admission using a travel account)
      TRAVEL_PASS
      CARD
      POINT_TO_POINT
      MULTI_TRIP
      MERCHANDISE_ITEM
      SERVICE_ITEM
      ....
  • TODO prepare a proposal (branch) for next week (Joseph, Linus) (Done)

Proposal has been created for 3.0.x, just for the immediate needs of Sweden.

  • Cleanup of references in Booking and Booking Parts, according to last weeks minutes:

     - bookingRef added, externalRef correctly described
 - deprecate retailerBookingRef and distributorBookingRef from BookingPart
 - add bookingPartRef to BookingPart

  • changes to BoookingPart to be reverted - this is just a patch version

  • in Fee, add productRef and deprecate productCode

  • in BookingParts, add "refundAmount" as new optional attribute

  • in CoachLayoutPlace, add "icon" attribute, which refers to the icon code in the Catalog of Code Lists (Graphical Item)

  • in Compartment, add "number" attribute

  • add breakdown on refund offers and exchange offers - refund/exhangeFee, refundAmout/exchangePrice, bookingParts

  • Revert changes to Structure Name (AddBookedOfferRequest --> BookedOfferRequest)

  • Revert changes in the structure: passengerRefs goes back to passengers

  • Rename new attribute additionalPassengers to additionaPassengerSpecifications

  • Instead of the new AddBookedOfferResponse, the BookedOfferRespose will be extended by the optional list of bookedOfferIds

  • new attribute "productType" in product (enum) with the two values "ADMISSION_PASS" and "ADMISSION_MULTI_RIDE" - change this to extensible enum.

TODO Josef: clean up according to this list, review by Ralf and Tim, then release 3.0.x

We will back port these changes to 3.1.0, but need to discuss with Clemens and Andreas on how to do this with the least work (e.g. go through UML generation for 3.1.0 - tbd)

Notes for further discussion:

  • need to discuss availability status on Coaches and Compartments - discussion for another day.
  • do we really need GET /bookings/{bookingId}/booked-offers/{booked-offer-id}

2023-09-15 Meeting

  • Clarification on booking/booking part references https://github.com/UnionInternationalCheminsdeFer/OSDM/issues/341

    in Booking: - externalRef: reference provided by the requestor and returned in booking

    • bookingRef: reference of a booking which is used by human usable given by the provider of the booking. - id: unique id of a booking

    in BookingPart: - bookingPartRef: reference of a booking part which is used by human usable given by the provider of the booking part. - id: unique id of a booking part

     deprecate:
 -  distributorBookingRef reference to the booking in the downstream distributor system
 -  retailerBookingRef  reference to the booking in the downstream distributor system

    TODO: create a PATCH with the changes described above. - prepare a patch (Joseph, review by Ralf) for 9/22 create a table with all ids used including a coherent description. - to be discussed in October

  • TODO: sequence diagram to document adding a reservation and selecting a place

seq-graphical-reservation seq-graphical-reservation-after-booking

  • TODO review (Ralf)

  • Turnit: Add name and owner to the fee object. Alternatively refer to a product. image

    • change productCode to productRef including an id
    • TODO (Joseph review by Ralf) Create a patch (3.0 and 3.1) to change the Fee object:
      • deprecated productCode
      • add optional productRef as sring with comment: includes productId

  • OEBB: http errorcode 422 is missing (semantic problems in interpreting a request).

    The recommended Zalando http error codes https://opensource.zalando.com/restful-api-guidelines/. They suggest using the 400 also for valid input failing due to business logic. I guess it's based on the updated HTTP semantics in https://www.rfc-editor.org/rfc/rfc7231

  • DB: when can "validUntil" be empty, and should it become mandatory?

    travel account might have no end date

  • DB: we see that the sandbox environment uses the same product id for admissionOfferParts and reservationOfferParts, is this a valid case? Shouldn't there be different products for different types of offerParts?

    this is the case for classic IRTs

  • DB: Enum values like "YES" and "NO" confuse some code generators. They create a binary element, even if there are three options (e.g. ExchangeableType has the options YES, NO, WITH_CONDITIONS). The solution is to have the values quoted, i.e. "YES", "NO", "WITH_CONDITIONS".

    to be discussed with Andreas for the generator

  • DB: can trip based offers lack trip references completely? In our opinion this should not be allowed, i.e. if the OfferCollectionResponse contains the trips element, for each offer there must be either a tripCoverage element at the offer level, or within each offerPart.

    TODO: add a comment that for offers requested for a trip the trip coverage must be provided.

2023-09-08 Meeting

  • Samtrafiken: Introducing refundOfferParts and exchangeOfferParts to make it possible to break down refundableAmount and exchangePrice to the customer image

image

--> Solution: optional refundBookingBreakdown and exchangeRefundOfferBreakdown as optional elements including fee, refund amount and an array of BookingPartReferences in 3.1 and as patch in 3.0.

  • Turnit: POST /bookings/{bookingId}/booked-offers

    • Replace Passenger with PassengerSpecification in request (Same as in POST /offers).

    • Respond with a booking or an empty response. Current response (bookedOffer) is incomplete.

      --> use optional additionalPassengers ( PassengerSpecifcation) and provide only the new passengers. existing passengers are already known and don't need to be send. Remove/deprecate passengers list. in 3.1 and as patch in 3.0 --> the response should return a list of the new bookedOfferIds only. Create a new return message in 3.1 and as patch in 3.0. --> TODO prepare patch Clemens until Thursday, Ralf to review it.

2023-09-01 Meeting

  • Samtrafiken: Clarify how to use refundAmount and refundFee in refundOffer --> TODO add clarification in RefundOffer. refundAmount = amount to be returned to the customer, refundFee = amount kept by carrier(s) and / or distributors

  • Turnit: Add icon to places in coach-layouts for version 3.0.3 --> TODO add the same fix as in 3.1 also in 3.0

  • Turnit: We would like to have the possibility to return a compartment number in GET /availabilities/place-map

    -- TODO: Add an optional string "number" in the Compartment object. Compartment.number is an identifier for compartments which have their own identifier shown at the door. in 3.1 also in 3.0

  • Turnit: We need a possibility to break down refundableAmount and refundFee between nested fulfillments in a refundOffer to get settlement correct. We have the same problem with exchangeOffer

    Options: - separate end point for settlement details Get settlementDetails (booked/refunded/exchanged OfferPartIds) - settlement details optional in refund offers? --> clear separation of settlement amounts and customer visible amounts

    Solution: draft a settlementDetails end point --> TODO Linus

  • fees on place selection --> TODO: Add a new value "PLACE_SELECTION" on conditionType to indicate different fees for different types of place selection (as specific seat of only via preferences,..)

  • Product: TODO summary should be the name of the product. Better: additional name element in 3.1/0

In July

2023-07-21 No Meeting

2023-07-14 Meeting

2023-07-07 Meeting

  • OSDM 2.0.7 released
    • Change: back porting local date time to 2.0.*
  • Linus:
    • Unify error and warning handling. To make it easy to integrate with different providers. It would be probably be a part of the certification process as well.

Consensus

  • problem type: <host>/problems/<problem-code>
  • warning type: <host>/warnings/<warning-code>
  • for standardized problems/errors the host: osdm.io/problems or osdm.io/warnings, respectively.
  • for provider specific every party is allowed to have it's own host
  • Problem should have an optional code in OSDM 3.1 and a mandatory code in OSDM 4.0
  • A customer facing party (i.e. retailer) is allowed to map codes to its own codes and translate them into the customer's languages.
  • An error returns an HTTP status code 400-599 and a Problem structure detailing the cause of the error.
  • An warning returns an HTTP status code 200-299 and a Warning structure detailing the cause of the warning.

2023-06-30 Meeting

Consensus reached, Tim will document it for the group

https://osdm.io/spec/technical-principles/

  • Turnit: New version 3.0.3
    • Add Place icon in CoachLayoutPlace

Will be fixed with 3.0.3.

  • New end point to remove a passenger and her admissions from a preBooked offer - DELETE /bookings/{bookingId}/booked-offers/{bookedOfferId}/passengers/{passengerId}

    Semantic: Look up offer parts linked to this passengerId and remove them if valid from a tarif point of view.

    I.e., only possible if offers are partitioned enough and no repricing is needed.

    Will be part of 3.1.0

  • Finalize OSDM 3.1.0

    • Split Booking

      Accepted, will be part of version 3.1

2023-06-23 Meeting

  • OSDM v.2.0.6 is ready to be released

2023-06-16 Meeting

  • SBB:

    • We have a requirement, that it must be possible to travel anonymously. The change is needed for 2.*

    • Version 1:

      Passenger:
…
detail: PersonDetail
personDetail: PersonDetail
contactDetail: ContactDetail
…

    PersonDetail: summary firstName* lastName* contactDetail: ContactDetail

    ContactDetail: summary email phoneNumber address preferredLanguage

    
- Version 2. use `firstName` = "N/A" and `lastName` = "N/A"

> Version 1 is cleaner, it's important to do it non-breaking

  • DB: Carrier on DatedJourney, why mandatory?

Some implementation require it to be mandatory, derive rics code from HAFAS administration code.

  • Amadeus: Update on Splitting

  • DB: Question: what is the fulfillment ID? Is it the ticket-ID according to UIC 918.9?

The fulfillment ID is not the ticket ID. The ticket ID is the controlNumber within the fulfillment.

2023-06-02 Meeting

  • OSDM 3.0.2 released
  • Sqills:
    • Sqills OSDM Demo environment to support OSDM 3.0
  • Webhooks:
    • Up to date?
    • Any implementations or plans?

Some events are missing and are added, leading to a 3.0.1 version.

Model resource as described in I-80.

Refund and Exchange are triggered by fulfillment ids currently, partial refund will be triggered by booking parts. While there is potential for alignement this is not in scope of 3.1.

  • Turnit:
    • Questions on Coach Layout

Bug: icons are missing on coach layout and places. Add optional with default seat.

Description: Grid size: boundary rectangle size of the coach.

2023-05-26 Meeting

  • Blocker on 3.0.2

    • Turnit: ReleaseOffer.confirmedOn must be optional image

      fix needed for 3.0.2

    • Bileto: Code generation problems with nullable: true

      set some attributes to nullable: false so that openapi generator bugs are ommitted

    • Bileto: What is purpose of Booking.ticketTimeLimit? No documentation is provided in openapi.

      add confirmationTimeLimit with comment and deprecate ticketTimeLimit.

  • Announcements

    • Sqills will release a 3.0.1 version next Wednesday, May 31st.
    • Billeto will release an updated sandbox version middle of June.

2023-05-12 Meeting

All:

Sqills:

ResSys: -Semantic of offer request

  • In the dimension PassengerType:
    • 4 Person are requested but only 3 places are available: Do we return an "incomplete" offer or nothing?

      If reservation is optional, do return 3 places. If reservation is mandatory, do not return an offer.

    • 1 Person and 1 Bike are available but it's impossible to transport bikes: What do we return?

      If bike reservation is optional, do return offer. If bike reservation is mandatory, do not return an offer

    • Dealing with up-selling: Do we return up-selling offer like bike or luggage only if requested?

      Upselling should not be modeled with "artificalPassengerType" but with AncillaryOfferPart

  • In the dimension trip: If not the complete trip can be priced how to behave?

    Provide as much coverage as possible.

  • Are there other relevant dimensions?

    No. Open: How to communicate to customer if 3 out of 4 places would be available? Do we want to support a 'non-strict mode'?

öBB:

  • in case of a first class offer for a connection with multiple legs it is possible to have "mixed" reservations of first and second class if first class reservations are not available on all legs.
  • how to use availablePlacePreferences and placeProperties in the booking request

    an entry in reservationOfferPart/availablePlacePreferences[]/preferences in an offer transforms into a placeSelection[]/accommodations[]/placeProperties entry in a booking request.

Improvements to address:

2023-05-05 Meeting

  • Roland Klapwijk

    • YAML seems to be untouched in that part, I guess it's yet to be done -- fixed
    • The card does need the "type", without it there is implicit logic (if there is a code it is a reduction card, otherwise a travel account). What about loyalty cards or reduction cards which require validation by the system where the customer needs to enter the number? Tim has sent several emails on this topic.
    • numberOfPrivateCompartments was indeed the suggested name -- fixed
    • an address now contains a mandatory ID. Will anyone actually be checking the unique address ID of each country and provide that in the request? If so, and if every address in each country has a unique ID, would we then still need the address details? 😉 I guess it came as a side effect from the Place inheritance -- won't fix Breaks the fundamental concept of every place to be uniquely identified. If not present, an id can be generated using longitude and latitude instead.

  • Ralf Bayer

    • The changelog says „remove relation from FareConnectionPointRef to FareConnectionPoint”. As far as I can see, the relevant part of the yaml looks exactly like in 3.0.1, and the connection (and circular reference) is still there. -- fixed
    • For AppliedPassengerType: the attribute “appliedReductionCardTypes” is of type “ReductionCardType”. Wouldn’t “CardTypeReference” be sufficient for this context (it contains the issuer, the code for the card as well as the human readable name for the card type)? -- addressed
    • Is the attribute name “numericAvailabilityPrivateCompartments” sensible? “numericAvailability”, at least for me, points to something like how much stock is remaining. However, I thought we were discussing a concept of “if you book this reservation offer, there will be n private compartments included. So shouldn’t this be named “numberOfPrivateCompartments” or even more simple “privateCompartments” (type is numeric)? -- fixed

  • Linus Turnit

    • Is status EXCHANGED missing in fulfillment? For me the old fulfillment must be marked as not valid any more. fixed
    • One more topic exists in I-77.
      • Add space for through-ticket tag on BookingRequest level – needed for RESPLUS post poned various solution approaches have been discussed and will be evaluated by Swedish experts.
    • Can we fix that and then close both I-76 and I-77 and make version 3.0.2 official?
    • List of offerIds can be posted but only one offer in response for POST /bookings/{bookingId}/booked-offers

  • Klaus K.

    • I would suggest to take over the change from the IRS 918.1 graphical availability regarding the direction change into the place map. Is therefore an improvement needed? -- please shortly define

2023-04-28 Meeting

  • OSDM 3.0.2:

    • FareConnectionPointRef:

      • remove relation to FareConnectionPoint

    • ServiceTime

      • make estimatedTime and actualTime optional

    • FulfillmentDocumentType:

      • add TRAVEL_ACCOUNT_REDUCTION, TRAVEL_ACCOUNT_PASS, TRAVEL_ACCOUNT_MULTI_RIDE
      • add optional issuer
      • make BookingPartReference optional

    • Add AppliedPassenger and ActualPassengerType

    • Product and FulfilmmentPart: add TextElement

    • CardTypeReference add Symbiology

    • add name to CardTypeReference optional

    • see: https://app.swaggerhub.com/apis/schlpbch/uic-90918_10_osdm/3.0.2-2023-04-27

  • CardType and CardTypeReference to be checked, there seems to be an error in 3.0.1 in the usage of the two objects

  • Final decide on modelling of IRT offers

  • I-77 to be discussed

2023-04-21 Meeting

  • Nicolas

    • Asynchronous post fulfillments does not actually return ids (as mentioned in endpoint description). IMO it also shouldn't (point of the 202 is the resource is not created yet => it does not have an id yet). Consequence is that if a 202 is received, one acutall needs to reload the whole booking to get the fulfillment ids

      Currently: If the fulfillments are created asynchronously the service starts the creation of the fulfillments. Only fulfillmentIds are returned. The fulfillments are in stage CONFIRMED.

      Should be changed to: If the fulfillments are created asynchronously the service starts the creation of the fulfillments. No fulfillmentIds are returned. The fulfillments are in stage CONFIRMED. The booking needs to be retrieved later to obtain the fulfillments.

    • in fulfillment definition, fulfillment type seems to largely overlap with medium & type of document => confusing, risk for inconsistencies, needlessly complex to read. Can we not get rid of one of these ? TODO: more documentation is needed on the use of media, format and type

    • bookingParts is not always possible to set => can it be not mandatory ? Decision: the links to the bookingParts in fulfillment should be optional.

  • Tim (Sqills)

    • errors and warnings

    • generic codes given, more process specific codes will come in the next few weeks.

    • new codes:

      • INVALID_INPUT_PARAMETER (invalid url parameters) http 40*
      • INVALID_REQUEST (invalid json) http 40*
      • NOT_IMPLEMENTED http 501
      • UNKNOWN_ERROR http 500
      • MISSING_PROVIDER_SPECIFIC_INFORMATION (violation of a bilaterally agreed usage) http 40*

    TODO Tim: update documentation

  • Koffi (Amadeus)

    • Documentation on how to use the seat maps

  • Josef:

    • there is a bug in ServiceTime as estimated and actual time must not be mandatory.

  • Linus

    • Review of modelling suggestions for I-76: approved with renamings:

      • passengerId --> passengerRef
      • section --> tripCoverage
      • to be included in common offer parts as well

    • see issue #332 in Git.

    • A walk through of nonTravelOffers sales flow (TravelPass and MultiRidePass). Where is the id returned for the travel-account?

  • Josef: Code generation and different return types for success and failure status. createOffers returns OfferCollectionResponse on success or warning but Problem on invalid input. But at least Java can't define union return type.

image
  • changes on fulfillment:
    • add new values in FulfillmentDocumentType
      • TRAVEL_ACCOUNT_REDUCTION , TRAVEL_ACCOUNT_PASS, TRAVEL_ACCOUNT_MULTI_RIDE
    • Fulfillment ControlNumber is the number of the travel account
    • Fulfillment should provide an issuer explicitely (company reference)

2023-04-14 Meeting

  • Bug in 3.0.1?

    • A cyclic reference in FareConnectionPoint --> TODO delete FareConnectionPointReference

  • Final version of OSDM 3.0.1 has been released

    • Passenger and PassengerSpecification use CardReference instead of CardTypeReference
    • added validFrom to different types of offers

  • Feedback on öBB's proposal on modelling IRT offers:

    • Consensus is to use individual offers and not to use the reservation grouping for different accomodationtypes within one offer

  • Linus (Turnit)

    • I-76 Add more information for the Passenger
      • --> change for product will be prepared: TODO Josef, Ralf, Linus
      • --> change wth an additional priority element in the trip attributes will be prepared: TODO Josef, Ralf, Linus
      • --> change for applied passenger types will be prepared: TODO Ralf

2023-03-31 Meeting

  • short communication (Nicolas): after giving it second thought, I agree local time is needed in our messages regarding departure and arrival times :)

  • Linus Johansson (Turnit)

    • number is missing in the CardTypeReference in booking response
      • image
      • resolution: Use CardReference instead of CardTypeReference which has a number field. (fix for 3.0.1)

  • Description of a fee is missing

    • resolution: add a description to fee

  • Stina (SJ)

    • Modelling of issued vouchers during rebook or compensation. There is a way to model this within the standard, but I want to ensure we are in agreement this is the correct way to work.
    • discussion: we need a means to return a voucher in the booking
    • resolution: add a list of issuedVouchers a VoucherInformation to Booking and RefundOffer ->

  • Koffi (Amadeus)

    • Seat Map
    • resolution: Process is sound however not properly supported.

  • The date-time issue has been resolved.

  • Klaus (ÖBB)

    • I think the attributes[] list in the trips or offers response is redundant. There is one under timedLeg{} and one within timedLeg{}/service{}
      • Solution: removal of the attributes[]-list that is located directly under the timedLeg{}. The attributes[]-list within the timedLeg{}/service{} should remain, extended with fromStopSeqNumber and toStopSeqNumber. Affected: tripSpecification and trips[].
    • number of private compartments in the offers[] response in the case that there are variants of private compartment offers (eg. offers for 3 passengers in an couchette private compartment: one offer with 1 private compartment for all passengers, a second one with two compartments...). See suggestion from Stina

  • unclear on how to use the get bookings/{bookingId} - Nicolas

    • we do not have a get get bookings/{PNRRef} on the reason that it may be flawed GDPR-Wise. This in itself culd be challenged as the call is performed on a secured network by an authenticated user.
    • furthermore, if the bookingId is fixed over time, then it is just a longer version of a PNR, which IMO is not really more secure
    • if it is not fixed over time, it forces the consumre to go through the search booking feature, which is cumbersome, not more secure as you still could get to a booking with just one parameter and where it is not possible to give the PNR as search criteria atm, while it is the most common criteria to open up an existing booking
    • I would propose to add a get bookings based on parameters where the consumer can retrieve a booking based on the PNR + one other information of the dossier if needed for GDPR Discussion

  • Consensus going towards a get /bookings/{id}?idtype=[id|extRef]. Default would be id so that is a non-breaking-change. => Nicolas to deliver a patch with the update and Andreas will do the modelling via UML tool.

  • security/privacy rules are managed by the authentication of user and user access rights management in the backend

2023-03-24 Meeting

  • Update on date-format

    • OpenAPI's date-formatsupports time offset
    • The example's in ServiceTime has been updated
    • We can thinking about enforcing OffsetDateTime by using a reg-exp .+[^Z]
    • Hitrail is now aware of the time zone topic and will address that on the H2O converter

  • Klaus (öBB):

  • Let's be more professional in our work:

    • Tim: Breaking changes early in the PI, only cosmetic changes towards the end.
    • The next version must be non-breaking, thus let's model accordingly using the deprecated keyword.
    • Please report issues using the github issues feature so that they can triaged and tracked:

2023-03-17 Meeting

  • OSDM 3.0 is released: https://osdm.io/osdm/update/2023/03/10/OSDM-V3.0-released/

  • Official logo is here: https://github.com/UnionInternationalCheminsdeFer/OSDM/blob/gh-pages/images/logo/OSDM-logo.png

  • OSDM 3.0.1 prepared

    • Addresses issues found by Sqills, Turnit and DB.

  • Tim:

    • Issue with local time on Alight/Board --> addressed in 3.0.1.

  • Linus Johansson

    • In POST /bookings-search the companyName is mandatory in the purchaser object, but a purchaser doesn't have to be a company. Actually the companySearchResuest is wrong, it should be purchaserSearchRequest or something, but that is a breaking change. Easiest is to make companyName optional. --> addressed in 3.0.1.

    • Pagination on booking-search response is missing. Depending on the search criteria the response can probably be quite hugh. Link parameter is missing, page parameter is included, but should be the same mechanism as everywhere.

    • Check the local time format on departure and arrivaltimes all over the specification

  • Clemens

    • the YML file contains a format error on exclusiveMinimum, format and interpretation has changed with openApi 3.0 --> addressed in 3.0.1

  • Gender is missing in anonymousPassengerSpecification and passengerSpecification (optional, extensible enum). This is required for specific offers (female compartments,..).

    • should be in 3.0.1

  • Local Time in arrival and departure is not jet in 3.0.1

    • proposal: have time zones in replys, no time zones in requests (local time)
    • --> a mandatory time zone would make it more difficult to have conversion between OSDM and existing TAP-TSI specs
    • --> solution: in requests: local time - add a mandatory time zone to the place in the master data - allow local time in request and reply? - UTC without time zone is not allowed. (indicated as comment, not via pattern) - should be consistent wherever the date-time is linked to a place
      • is it possible for converters to add the correct time zone? If yes the time zone can be made mandatory. - check with OJP - should be in 3.0.1

2023-03-10 Meeting

  • Nicolas Selleslagh:
    • there are still some places where we have attributes that are both mandatory and with a default value, which in my book does not make much sense and is confusing actually. Example: passenger type in anonymousPassengerSpecification

Keeping as is.

Discussion on later - is OSDM really stateless?

  • externalRefs are mandatory and not nullable: why is this so ?

3.0 is breaking, will review those 70+ occurences

  • Question to Sqills: is there a way we could get access to the OSDM validator ? What is the process herefore ?

There is only a PoC at the moment. When it is delivered, it will be shared with the group.

See OSTS Meeting Minutes.

  • Ralf & Josef:
    • First, on the specification of either a reduction card type or travel account when requesting an offer. My comment was actually a bit quick, we could also go with Josef’s suggestions, as long as we can either specify an anonymous card type (by card type id and optional card number) or an account (specified by number and issuer). I don’t care very much whether we have three optional attributes or two different structures, we should just make sure that it is clear what the intent is and that both users and implementors of the API can easily understand what we mean.

CardTypeReference will be used both for ReductionCards and TravelAccounts. Will have type (ReductionCardType link), issuer and number optional.

  • Regarding the MoneyAccountUnit:

    • It shouldn’t have VAT. VAT comes into play when the money is spent, money itself doesn’t have it (haven’t seen a VAT statement on my EURO or CHF banknotes). The offer generated will have VAT, but this is independent of the way it is paid. Which means that the implementing system needs to know what id does taxwise. There are rules, but like everything in the tax world they are complex, and cannot sensibly be expressed at API level.

VAT is on product, not on balance. Scale retained, vat removed.

 - But it should have the scale field, because a monetary amount is made up of the three attributes value (in cents or similar), currency, and scale. With the value present in the “total” and “remaining” fields of the account, we need the other two in the type, i.e. it must have currency and scale.
  • Klaus Kovar
    • AccommodationSuptypes Review (https://osdm.io/spec/catalog-of-code-lists/)
      • "COMPLETE" should be a place_property
      • there should be an accommodationsubtype like "SEATS_6"
      • the following place properties should also be subtypes (WHEELCHAIR_AND_SEAT, WHEELCHAIR_NO_SEAT, CHILDREN_AREA, NEAR_WHEELCHAIR, OPEN_SPACE, FAMILY, NEAR_BICYCLE_AREA, EASY_ACCESS, COMPARTMENT?
      • place location "middle" is missing for seat compartments

Clemenc will review and include to code list.

  • offers[]/offerSummary{}/minimalUnit{} is mandatory now
  • for each reservation reference in an admission it is possible to add a summary(admisstionOfferParts[]/reservations[]/reservationGroup{}/reservationRefs[]/summary), but under reservationOfferParts[] there ia also a summary reservationOfferParts[]/summary. Which one should be filled in which case - e.g. reservation only?

IRT is indicated only by required reservation flag. Price is reservation is used when there are multiple reservation options with diff. prices, otherwise price on admission is sufficient.

Documentation must be updated on different cases - IRT, compulsory reservation, etc.

  • offers[]/products[]/code is some sort of tariff id that should not be changed over time?

Product.code doesn't change over time, Product.id may for the same product.

  • offers[]/products[]/owner is the RICS code of the tariff owner

It is a CompanyRef of the company printed on the fulfillment.

  • Product.condition[].description vs shortDescription

should be short to be displayable on small screens, shortDescription to be removed.

  • is this the structure for an IRT offer?

IRT_structure

  • which price element should be filled in case of an IRT offer? should the admission or the res.offerpart price element be 0? Which product-reference should be filled?

  • tripLegCoverage is missing in ReservationOfferParts/availablePlacePreferences?

  • Improvement "parallel trains in OJP"

  • Linus Johansson:

    • We need the service attributes with the leg in the tripSpecification in offerSearch, since all provides doesn't have the trip defined and can't deliver them in the respons. For me the attributes are service related, so the proposal is to add the attributes into the DatedJourney together with the vehicle number, mode and other service related attributes. If we do like this, the attributes can be expressed in both directions. image

OJP allows attributes both on LegStructure and DatedJourney. Adding to DatedJourney.

  • AppliedOverruleCode and refundFee in refundOffer is required, change to optional

Fixed

Patrick: There is an OSDM group at UIC LinkedIn page. (It's private and access must be validated and granted.) Good to share monthly progress of each stakeholder in the community.

https://www.linkedin.com/groups/12793224/

2023-03-03 Meeting

Turnit can unfortunately not participate in this meeting.

  • Review OSDM v3 Pre 3 findings
    • By Linus: The cardReference in anonymousPassengerSpecification will not work. I think the old one describes the need. image

Same as Josef, Ralf

  • By Linus: Add TRAIN in ptMode enum-list

Add TRAIN to PTMode enum, it is contained in the code list on the osdm.io

  • By Linus: What is the difference between offerParts and bookingParts in fulfillment? image

Removing offerParts as marked deprecated in 2.0.4

  • By öBB: There is an issue with names: They are defined on the general Place level and also in the Subtypes (StopPlace, PointOfInterest).

  • By Josef: For using a TravelAccount in POST Offer request, the CardTypeReference is not sufficient at the moment. Needed changes:

Same as Linus, Ralf

Separate CardReference object for request and response, and create two request objects - ReductionCardReference where type links ReductionCardType (required) and number (optional) identifies the instance; TravelAccountReference has issuers and number both required.

Alternative solution was have type, issuer and number all optional and validate in the implementation.

TravelAccount doesn't have an ID,

  • By Ralf: The master data endpoints have different ways to express cache control instructions (4 have an "Expires" header: Coach Layouts, Coach Layout Reduction Card Types, Zone, 3 have a "CacheControl" header: Places, Products, Product). In addition, "Reduction Card Types", "Zones" has "deliveryDate" in the payload.

Expires (HTTP/1.0) can be expressed by Cache-Control (HTTP/1.1), not vica versa. Use Cache-Control everywhere and remove deliveryDate from the master data responses.

  • By Ralf: in the travel account balance, the "remaining" amount is both in the Balance object and in the amount of the units. Possible solution: remove the "remaining" attribute from the Balance type and rename the current "unit" attribut (of type "AbstractConsumptionUnit) to "remaining".

Separate TravelAccountUnit and TravelAccountConsumption, also TravelAccountConsumption separate for indication in Offer, and history of TravelAccount.

  • By Ralf: SupportingDocument.content should also be mandatory. Doesn't make sense to send a title and a format but no content

Provide download link and expire to have same functionality as for fulfillment documents

  • By Ralf: Reimbursement&Complaint UpdatedStatus (Type "BackOfficeStatus") should have a value "UPDATED" to indicate that additional documents have been filed (endpoint PATCH /bookings/{bookingid}/reimbursements/{reimbursementid}

Add to BackOfficeStatus enum

  • By Ralf: Almost all offer requests to change a booking or fulfillment are of the form POST /bookings/{bookingId}/xxxOffer (with xxx = exchange, release, cancelFulfillment), with the exception of exchange, which has a straight POST /exchange-offers. This should be changed to POST /bookings/{bookingId}/exchangeOffers (also removing one of the last few remaining dashes (-) in an endpoint URL)

Remove dash from API URLs

Change to POST /bookings/{bookingId}/exchangeOffers

Add Booking reference to Fulfillment

  • By Ralf: (cosmetic) In the Passenger type, age should be next to dateOfBirth to make it more visible that these two are related

Yes

  • By Ralf: BookingSearchResult should have no other attributes but id as mandatory. Reason: booking search can potentially return a many bookings, and if the mandatory results contain too many details, this can lead to large scale data extraction which is a security risk.

Keep it that way

  • By Ralf: (cosmetic) change POST /trips-collection to POST /tripsCollection in order to have consistent use of camelCase throughout the API

Yes

  • By Ralf: (in "OfferSearch") CardTypeReference.id should become "type" or "cardType"

As discussed above

  • By Ralf: (in GET /availabilities/placeMap) Coach has layoutId, layoutIdUpperDeck and layoutIdLowerDeck, and the layoutId is manadatory. Which layout should be in the (mandatory) layoutId when this is a coach with upper and lower deck, or should layoutId become optional?

layoutId is combined plan for both floors avaiable in master data, layoutIdUpperDeck and layoutIdLowerDeck duplicate the plans for single floor only.

Additional Remarks on the call

OfferPart objects miss validFrom as it represents validity of the product (timeframe of travel/usage rights), Offer.validUntil should be renamed to bookableUntil

2023-02-24 Meeting

  • Simplify fulfillment state diagram as we no longer need activation thanks to travel account

No, leave it in and check whether it's been used by anybody

  • fix providerRef/allocatorBookingRef/bookingRef/bookingProviderRef

    • align with TAP-TSI
      • Allocator --> Distributor
      • Ticker Vendor / Distributor --> Retailer

  • Discuss exchange refactoring --> two ways to book an ExchangeOffer

Remove exchangeOffer from PATCH /bookings/{bookingId}

  • Update error codes as well as warning codes
    • The list of functional warning code is missing on https://osdm.io/spec/errors-warning/.
    • Clarify: code or url (as requested by RFC 7807 (https://www.rfc-editor.org/rfc/rfc7807)
    • Area: Code Title-Code ohne Prozess/Funktion
      • REFUND: CONFIRMATION_REFUNDOFFER_ALREADY_CONFIRMED RefundOffer already confirmed REFUNDOFFER_ALREADY_CONFIRMED
      • REFUND: CONFIRMATION_REFUNDOFFER_EXPIRED RefundOffer is no longer valid (expired) (*) REFUNDOFFER_EXPIRED
      • REFUND: CONFIRMATION_REFUNDOFFER_NOT_FOUND RefundOffer does not exist or was deleted REFUNDOFFER_NOT_FOUND
      • BOOKING: BOOKING_BOOKING_NOT_FOUND Booking does not exist or was deleted BOOKING_NOT_FOUND

To be added

  • Ralf: 4. POST /bookings/{bookingId}/exchangeOperations/{exchangeOperationId} is also still there. We agreed to a. Add a POST /bookings/{bookingId}/exchangeOperations, which takes the exchangeOffer as a parameter b. Remove the exchangeOffer parameter from the PATCH /bookings/{bookingId} c. If we still need to update an exchange Operation, we would have a PATCH (instead of POST) /bookings/{bookingId}/exchangeOperations/{exchangeOperationId}

To be addressed in OSDM v3 pre3

  • Shopping Cart
    • Need for a cart functionality from a distributor point of view.
    • Release OSDM 3.0 within the next days as it otherwise blocks other parties.
    • Start to work on a true cart functionality after the release on a dedicated resource.
    • We probably have to increase the pace, so I imagine we build a small sub group to work on it. Koffi has already indicated to me that he is willing to support such an initiative.
    • Focus should be on fully understanding the business requirements and business rules before diving into the API modelling.
    • Have a discussion whether such a cart functionality is part of OSDM core or an extension to the OSDM standard for distributors.

2023-02-17 Meeting

  • Short update from OSDM@PES.
  • Finalize open points and the modeling
  • Nicolas (looking at 2.1): On offer: As far as I can see, the removal of the get offer-collection (or get offers) killed the scrolling capability. Are we ok with this (I think it is quite a loss) ?

Scrolling on trips is supported, however no scrolling on offers. Thus if you want to scroll, do it based on trips which are nicely ordered by the way.

  • Nicolas (looking at 2.1): Why do we still have an objectType in post offer ? I see no oneOf or other kind of structure requiring a discriminator ?

ExchangeOfferCollectionRequest and ExchangeOfferCollectionResponse should not inherit as it produces strange OpenAPi code.

  • Nicolas: same remark on stopPlaceRef in trips. Alos, if it s meant to indicate the kind of places, the discriminant should be in place not in the ref.
  • Nicolas: the whole stopPlace construction is sketchy IMO: in trips they make sense, only I would call them PlaceRefs (optional), but in places we again have stopPlaceRef and that one is confusing. I would not know what to put in there: you are already in the place itself ??

2023-02-10 Meeting

  • Ralf: Change POST /bookings/{bookingId}/exchangeOperations/{exchangeOperationsId} to PATCH /bookings/{bookingId}/exchangeOperations/{exchangeOperationsId} to be more RESTful (for 3.0)

from Meeting 2022-12-09 the change got lost but needs to be in 3.0:

      PATCH /bookings/{bookingId} -> POST /bookings/{bookingId}/exchangeOperations with exchangeOffer in body is missing

      The change of the POST is already included:
      POST /bookings/{bookingId}/exchangeOperations/{exchangeOperationsId} -> PATCH /bookings/{bookingId}/exchangeOperations/{exchangeOperationId}
  • Josef: Finalize modelling of travel account in (for 3.0)
    • Agree on business use cases to support:
      1. Initial creation of account by buying an offer
      2. Using the travel account to pay for/discount another offer/product
      3. Charging ("topping up") units to a travel account. Idea: Buy an offer and charge it to the account in the PATCH /booking/ step
      4. Dissolving a travel account (not in self service, only point-of-sale/back office)
    • Clarify relationship between passenger and travel account
    • Design: How to model the resources.

needed changes:

  • default for included objects is ALL
  • anyOf on the different cards/passes should be a oneOff
  • scale and vat is needed for MONEY --> use Price object
  • add tripSummary in TravelAccountConsumption and bookingId only

Service attributes are at Board an not at the service. Is that OJP style? or can we improve that?

------------------ next version ------------------------------------------

  • Koffi: Split of bookings

        One booking will be split into individual bookings per passenger before booking confirmation.

    Koffi will make a draft

  • Tim: Error codes and Warnings

        there are more error and wrning codes than in:

    https://osdm.io/spec/errors-warnings/

    Tim will provide a proposal for new codes

I-76:

additional texts in Product:

   - product features
   - display priority
   - text (for web sites)
   - short text  (for mobile devices)
   - category:
         MANDATORY - mandatory to be displayed (e.g. for legal reasons)
         ...

additional texts in TripLeg: - display priority - text (for web sites) - short text (for mobile devices) - category:

additional structure in offerpart to include the applied passenger types

2023-02-03 Meeting

  • Roland: Clarify time zones for destination

Decision: Use local time at the arrival or destination, respectively. Most be enforced by using a string with a pattern.

Datetime in the form '2017-02-17T13:35:08'. Interpreted as localtime. The seconds are mandatory.

pattern: '(\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d)'

  • Stina: Identifying the settlement

Every booking is finalized by creating fulfillment id(s). A fulfillment id most be unique, e.g. as a uuid or nanoid. The fulfillment id shall be used for settlement process.

A new settlement specification IRS-30301 will replace the existing 301.G4/G5 as the latter can not deal with online transfer. Planned for release by middle of 2023. (see https://github.com/UnionInternationalCheminsdeFer/UIC-Accounting-File-Viewer)

See github for more information.

  • Josef/Ralf: Finalize account feature

Todo Ralf.

  • Koffi: Finalize history feature

  • Andreas: Hardening Product

2023-01-27 Meeting

  • Patrick - OSDM Test Scenarios Team - Organisation and Kick-Off
  • Josef from Bileto: BookingRequest.externalRef is required, but Booking.externalRef in POST /bookings response is optional. Bileto question: optional or required?
  • make externalRef optional in the bookingRequest
  • change the comment in the booking as the externalRef is a reference from the requestor. The element has to be provided in the reply in case it was provided in the request.
  • add a providerRef in the booking to include an optional provider reference

--> Example errors owith http reply codes should be improved to show valid reasons.

  • Linus from Turnit: Passenger and trips are missing in response for POST /bookings/{bookingId}/bookedOffers and GET /bookings/{bookingId}/bookedOffers image
  • Include the complete booking in the reply and a list of the new bookedOfferIds created by the Post request.
  • Do the same for adding a reservation or ancillary
  • Linus from Turnit: CarrierRef is currently represented as RICS-codes. For the namespace UIC this is probably good, but we must introduce a x_swe name space in Sweden since we have a lot of PTA's and Express bus carriers not members of UIC in the system.

    Suggested is to replace RICS to carrier. urn:x_swe:carrier:74

image

  • Stina from SJ: Hopefully this can be handled within the standard, but we would like to reason about the sale of the full compartment (primarily for night trains) - where would the accomodationSubType be set for in the offer search to get the right response?

TODO : improve error message examples

2023-01-20 Meeting

NonTripSearchCriteria has been added

Check

Decide on API Versioning

Decision Tree

  1. Versioning of resource or suite?

  2. How/where do we version (path, header,...)?`

  3. Which kind of header versioning

    1. HTTP version (RFC 4229): version: 2.0
    2. Media Type Profile (RFC 6906) Accept: application/json; profile="https://osdm.io/2.0"
    3. Media Type Version Accept: application/vnd.example+json;version=2.0

  4. Backward compatibility and semantic versions

Many questions: Form a small group of experts

Decisions:

  • We must adhere to semantic versioning
  • OSDM 2.1 will be OSDM 3.0 as we have breaking changes

From Linus at Turnit

POST /bookings/{bookingId}/exchangeOperations/{exchangeOperationId}

The operation is meant to return the prebooked offers in the response:

  • the trips are missing.
  • Fulfillment for the new offer is not in scope since the offers are in PREBOOKED state.
  • exchangeOffer shall have the same definition as a bookedOffer with the extension of exchangeFee and exchangePrice.

The booking on the distributor side will be updated with new bookedOffers in the same way as for a normal booking. Probably it would be good for the distributor to get the replaced offer as well to update e.g. offerPartStatus to EXCHANGE_ONGOING

image

The exchange offer should only reference the fulfillment(s) that the exchange offers are created for.

To do: rename to exchangedFulfillmentIds

Status is missing in a Fee offer image

Fee's state are linked to an offer, no change required.

Points raised by Sqills

  • add flexibility to Product

Agreed

  • remove Purchaser.id

Agreed

  • add MIXEDto accommodation sub type

Agreed

2023-01-13 Meeting

  • New: The modelling date is available in the API version's field.

  • Different types of non-trip tickets

    • Season Pass

      Travel unlimited within a date range with a carrier

      Example: SJ, Yearly card

      Parameters needed:

      • Start date
      • Passenger category

      Can need a seat-reservation on some services. Book a 100% discount ticket with the Season Pass as a REDUCTION_CARD.

    • Season ticket

      Travel unlimited between two locations in both directions within a date range

      Example:

      • 30 days travel between Stockholm and Uppsala with Mälartåg.
      • 30 days travel in Stockholm area.

      Parameters needed:

      • Start date
      • StopPlace relation or an area
      • Passenger category

    • Multi ride ticket

      Travel n-times between two locations in both directions within a date range

      Example: 10-trip between Stockholm and Uppsala with SJ

      Parameters needed:

      • Start date
      • StopPlace relation or an area
      • Passenger category

      Need a call off functionality to register each travel. Book a 100% discount ticket with the multi ride ticket as a REDUCTION_CARD

    • Changes in OSDM

      When searching for non-trip offers, parameters for start date and StopPlace relation is missing. Passenger category works as it is specified.

      With a stopPlaceCoverage array it is possible to ask for products for one stopPlace and stopPlace-relations like Stockholm C to Uppsala C, or even more stopPlaces involved in the offer if that is needed.

      It is also possible for the provider to return alternative valid stopplaces for a Multi-Ride ticket.

      Example: You have a 10-trip multi ride ticket between A and C. Then it is possible to make a call-off between A and B since B is located between A and C. StopPlace coverage is then StopPlace A,B,C

    Change suggestions:

    image

Alternative change agreed in the meeting:

  1. add a "nonTripSearchCriteria" to the OfferCollectionRequest, with the understanding that exactly one of tripSpecification, tripSearchCriteria, tripIds or nonTripSearchCriteria will be specified
  2. define the NonTripSearchCriteria as follows:
    NonTripSearchCriteria:
      type: object
      description: >-
        This defines the requested validity when searching specifically for a non-trip Offer.
        The geographical validity can either be specified by a list of nutsCodes, by a list
        of places (i.e. stations) with the semantics that trips between either of any of
        the listed stations are covered (e.g. Frankfurt (Main)Hbf, Friedberg(Hess)
        and Hanau Hbf, which would imply that any travel between these stations is to
        be covered), or a list of zones (e.g. with carrier urn:vdv:rmv, the zones with the
        ids 50, 2501 and 3001 would cover the same area as the list of stations above)
      additionalProperties: false
      properties:
        validFrom:
          type: string
          format: date
        nutsCodes:
          description: >-
            Nomenclature des units territoriales statistiques COMMISSION REGULATION (EU) No 31/2011
          type: array
          items:
            type: string
        places:
          type: array
          items:
            $ref: '#/components/schemas/PlaceRef'
        zones:
          type: array
          items:
            $ref: '#/components/schemas/ZoneDefinition'
  1. remove the nutsCode and place attributes from OfferSearchCriteria structure, making the OfferSearchCriteria a pure filter specification

2023-01-06 Meeting

  • Hardening the modelling of Refund, too many attributes are optional (ASC).

image

validUntil: time until the offer can be used, however its availability is not guaranteed

  • Fix BookingPart state model

  • Finalize history feature from Koffi

    Offer
  createdOn

AbstractOfferPart
  createdOn

Booking
 createdOn
 confirmedOn

AbstractBookingPart
  createdOn
  confirmedOn

RefundOffer
  createdOn
  confirmedOn

ExchangeOffer
  createdOn
  confirmedOn

CancelFulfillmentsOffer
  createdOn
  confirmedOn

OnholdOffer
  createdOn
  confirmedOn

Fulfillment
  createdOn

  • 1.4.2 contained Offer.reservations[].optionality=INCLUDED to express that putting the Offer into Bookings means automatically add the Reservation. This field is not present in 2.0/2.1. How to express an Offer with Reservation always included? (Direct Reservation Booking use case).

image

Reservation.optionality was intended to design IRT products, not to provide relation of optionality of Reservation within an Offer. If the Offer is reservation-only, system should indeed validate if Reservation was selected in the prebooking request.

  • Questions by Turnit

    (1) Primarily we support three types of non-trip products.

    • Carrier pass, where you can travel on all trains for the carrier during a certain period
    • Season-passes (period cards), where you travel between two locations for free during a certain period. E.g. Stockholm C – Uppsala C, 30 days
    • Multi ride passes where you travel between two locations 10-times during a certain period.
      • This product uses a call off functionality, where you book a normal ticket to 100% discount with a reference to the multiride ticket to reduce the remaining amount of trips.

    Identified missing parts in OSDM

    • In Offer search there is no possibility to specify the relation ( from and to places) when searching for non-trip offers
    • Valid from date (Start date), is not possible to specify either

This should be already expressible by now: Either filter using productTags or using nutsCodes.

We probably need to standardize on productTags slightly.

image

(2) GET /bookings/{bookingId}

The current balance of a multi ride ticket is not presented in GET /bookings/{bookingId}. Also, a call of history is good to have,

Can we add something like this to the admissionPart?

"multiRideUsage":
  {
    "used": "integer",
    "total": "integer",
    "callOffHistory": [
       {
         "fulfillmentid": "string",
         "travelDateTime": "string"
       }
    ]
   }

We need more information on the use case, i.e., a better distinction between multi-ride and abo

OSDM Wiki

Links

Clone this wiki locally