Ability to specify the preferred namespace in a response

[rolandkla]

OSDM supports the powerful mechanism of namespaces which the OSDM client can provide in requests.

However it is not possible to request the preferred namespace of responses. For example if an OSDM provider has a default namespace like "x_mynamespace" it will most likely return the stations and operator in the default namespace. But what if the OSDM client wants to have the response in a different namespace?

We, as Sqills, have support multiple namespaces which are fully configurable. However, in the responses where no namespace is provided in the request, the default is returned. And this default doesn't not have to be the UIC (that might not be configured at all).

Also, it is not guaranteed that an OSDM client always wants the response to contain the same namespaces. This could be very much depending on the retailer or UI client connecting to a OSDM distributor. E.g. a Swedish retailer uses the x_swe namespace but an international OSDM client might prefer uic.

By introducing a "namespace" request input we can:

• let the client decide what its preferred namespace is (for that specific request)
• the OSDM provider can return the proper namespace (if valid & supported) This parameter could be a query param or custom header like e.g. "x_namespace".

We do have a Requestor header that could be utalized for this (and that would make it compatible wil all older versions) but:

• the content of it is not standardised
• the Requestor is for the who makes the request, not what it wants

[CGantert345]

is this linked to the osdm media type that is requested at IANA?

[rolandkla]

Not directly. As input we use namespaces in various areas like place refs. We have customers using their own codes and other supporting multiples.

During an offers request a code can be provided in the payload but when fetching a booking it is up to the OSDM provider to decide to return which. And that can be different then the OSDM client expects or that the OSDM client wants to have a different namespace for that specific request.

[jspetrak]

I get that, of an alliance of OSDM-capable systems want to talk with a prefered ID namespace, they need to make sure that UIC or other namespaces don't get used. It also helps to switch behavior if somebody from outside wants to call the API.

Question - how would that work if multiple preferred namespaces need to be requested. Let's say we have custom station codes for buses in Czechia, and train have "local" part of UIC station codes. So I would request x_cze:cisjr for buses and x_cze:sr70 for trains.

[rolandkla]

Content negotiation can work for that, same pattern that HTTP accept headers use.

This pattern involves supporting multiple values and a (optional) quality value where the client be specific which values are preferred in which order. Docs on this https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language. I don't think a quality value would be of real added value in OSDM because the amount of different namespaces per operator would usually be only a few. In increases complexity while not providing enough value (imo) at the moment. We can always add this in the future when a need arises.

In your example it would be something like, when using a header x-accept-namespace: uic, x_cze Where a uic namespace is returned where possible and x_cze as fallback.

With this approach we need to agree what the default behaviour should be if no header/param is provided or when the OSDM provider cannot fulfil the request. I guess the exact behaviour as today because it is not supported yet ;)

x-accept-namespace: uic would prefer the UIC namespace code, if not possible use the provider default x-accept-namespace: uic, iata, haf, x_cze would prefer uic, fallbacks to iata, which fallbacks to haf which fallbacks to x_cze and then as last resort let the provider decide x-accept-namespace: * would let the OSDM provider use its default namespace

[schlpbch]

Decisions

• Add a header for the client preferred name spaces to relevant resources.
• If not supported fall back to a default (preferably uic for train)

[hiletnes]

Entur are not having problems with the issue described.

[rolandkla]

I've created a PR and added the x-accept-namespace header to the resources that have a URN somewhere in the response, where no client input with a URN is given to cover the cases where the provider has to guess the URN the client prefers.

[jspetrak]

I've seen the branch. Looks good to me. Please create the PR for approval.