Skip to content

Traveler- and ItemFields

It relates to all products which can be ordered. Check potentialAction.

Traveler- and ItemFields contain definitions which help the developers to validate required information. This varies depending of the product and the product providers. To order a T-Shirt not the same properties are required as to by a train ticket.

  • ItemField: is related to orderedItem. -> quantity, validFrom, ....
  • TravelerField: is related to each traveler of an orderedItem. -> First name, Last name, Date of birth, Gender, ...

Some of the properties are explained here, for further information please Check the properties for FieldDefinition.

  • type: can be text, int, date, datetime, radio, select, duration
  • PropertyId: property name. Possibly it is including the path from the object (orderItem or traveler)
  • rangeMin/rangeMax: defines the allowed value range for this property. How this is defiend (int, duration, ..) depends on the Typeof the property.
  • rangeBasePropertyId: The range is calculated relative to the value of the property referenced here (for example from the birthdate)
  • parentFieldPropertyId and parentFieldValue: this FieldDefinition only applies if the referenced parent property has the given parentValue. For example the possibility to select a pickup place depends of the chosen deliver type.
  • required: nullable boolean value. It indicates if this Traveler- or ItemFields is required (true), possible (false) or not relevant (null) for booking.
  • requiredForOffers: nullable boolean value. It indicates if this Traveler- or ItemFields is required (true), possible (false) or not relevant (null) to get an offer.

Info

On the backend we use these definitions to validate the data dynamically. For best user experience you do this already on the client.

Examples

Zürich Card

For Zürich Card 72 hours, the ItemField and TravelerField are defined as the following:

"ItemField": [
  {
   "PropertyId": "orderedItem.validFrom",
   "Type": "dateTime",
   "Name": "Valid from",
   "Required": true,
   "RequiredForOffers": true,
   "PossibleValue": {},
   "RangeMin": "PT1S", // one second in advance
   "RangeMax": "P2M"    // less than 2 months
    }
 ],
"TravelerField": [
    {
        "PropertyId": "givenName",
        "Type": "text",
        "Name": "First name",
        "Required": true,
        "RequiredForOffers": false,
        "PossibleValue": {}
    },
    {
        "PropertyId": "familyName",
        "Type": "text",
        "Name": "Last name",
        "Required": true,
        "RequiredForOffers": false,
        "PossibleValue": {}
    },
    {
        "PropertyId": "birthDate",
        "Type": "date",
        "Name": "Date of birth",
        "Required": true,
        "RequiredForOffers": true,
        "PossibleValue": {},
        "RangeMax": "-P6Y",
        "RangeBasePropertyId": "orderedItem.validFrom"
    },
    {
        "PropertyId": "gender",
        "Type": "radio",
        "Name": "Gender",
        "Required": false,
        "RequiredForOffers": false,
        "PossibleValue": {
            "female": "Female",
            "male": "Male",
            "diverse": "Diverse"
            }
    }
]

Example Dynamic validation

This example shows how the automatic validation works on ItemField. In the case of Zürich Card, a customer can make a ticket as it is less than 2 months in the future. If it is more than the defined RangeMax or less than RangeMin, it will result in 400 Bad Request and gives a validation error

Info

Assuming today is February the first.

{
    "orderStatus": "Placed",
    "priceCurrency": "CHF",
    "orderedItem": [
    {
        "orderQuantity": 1,
        "orderedItem": {
            "product": {
                "identifier": "nova_zurichcard24"
            },
            "validFrom": "2022-05-03T00:00:00"
        }
    }
    ],
}
POST {marketUrl}/orders
{
    //not all response is shown 
    "validationMessages": [
    {
        "level": "Error",
        "message": "The field Valid from must be less than 01/05/2022 15:17:03 +00:00.",
        "orderItemNumber": "22-103915-1",
        "source": "OrderedItem"
    }
    ] 
}

Example validation different options

This example shows how these properties parentFieldPropertyId and parent Field Value should work.

    {
    "PropertyId": "deliveryMode",
    "Type": "select",
    "Name": "delivery Mode",
    "Required": true,
    "RequiredForOffers": false,
    "PossibleValue": {
        "shipping": "Shipping",
        "pickUp": "Pick-up"
        }
    },
    {
    "PropertyId": "shippingMethod",
    "Type": "select",
    "Name": "shipping Method",
    "Required": true,
    "RequiredForOffers": false,
    "PossibleValue": {
        "train": "Train",
        "plane": "Plane"
        },
    "parentFieldPropertyId": "deliveryMode",
    "parentFieldValue": "shipping"
    },
     {
    "PropertyId": "pickupMethod",
    "Type": "select",
    "Name": "pickup Method",
    "Required": true,
    "RequiredForOffers": false,
    "PossibleValue": {
        "station1": "Station 1",
        "station2": "Station 2"
        },
    "parentFieldPropertyId": "deliveryMode",
    "parentFieldValue": "pickUp"
    },

Example special additionalProperty

If the propertyId is prefixed with additionalProperty. Then it is an additional property with the id of the full value of propertyId. Example

{
  "propertyId": "additionalProperty.info1",
  "type": "text",
  "name": "swim experience",
  "required": true
 },
{
   "additionalProperty": [
     {
        "PropertyId": "additionalProperty.info1",
        "Value": "good swimmer"
     },
    ]
}

Info

rangeBasePropertyId: can be applied for any dateTime. e.g., it concerns the validation of the traveler's age at the travel date.

Note

There is conditions to be fulfilled. For Gender and Salutation there are predefined values for PossibleValue property. For BirthDate the value should be within the age range.

Warning

In some cases itemFields can change after the first step in the checkout page because they can be dependent on the users choices.


Last update: June 2, 2023 08:44:14