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.