Product Evaluation Guide
Table of Contents
- Conditions for a product to be valid for offering
- Validity overview
- Implementations
- Placement and structure
- Context
- Data Types
- Operators
- Ignore flag 'canIgnoreInOffering'
Conditions for a product to be valid for offering
This guide attempts to describe how offers determines what products are to be offered, through the use of Generic Parameter Assignments (GPA).
NeTEx terminology and types are used both in offers and this documentation. You can read more about NeTEx in the Entur NeTEx documentation or their official website.
Validity overview
What controls what products are to be offered (and to what price) is based on generic, mostly quantitative, validity limitation rules which consist in assigning certain “limiting parameters” to specific access rights.
Generic Parameter Assignments (GPA) are used to set these limitations. They specify generic (theoretical) access rights for a class of products, and describes pre- and post- conditions/rules for a product to be valid for offering (e.g. a time band limit - 7 to 10 a.m. - for trips made with a student pass). They indicate a theoretical set of possible limitation parameters that apply to a product. a GPA can be connected to any level of a product definition, i.e. Sales Package, Fare Product, Validable Element or Fare Structure Element.
GPAs are a subtype of Validity Parameter Assignment (VPA). Another sub-type of VPA is Specific Parameter Assignment (SPA), which assigns a limiting parameter to a particular right, thus representing the choice of a specific set of parameters for consumption on an individual trip.
The limitation parameters of a GPA can be of the following types:
- Usage Parameters (UP), that contain limitations/rules mainly linked to the characteristics of the actual/practical use of access rights, for e.g. User Profiles, Group, Refund, Reserving, Usage Validity Period, Interchanging, Purchase Window.
- Temporal Validity Parameters (TVP), reflecting temporal limitations, contain validity limitations/rules for time management, e.g. Availability Conditions with Day Type and Timeband.
- Scoping Validity Parameters (SVP), reflecting spatial and consumption limitations, contain validity limitations/rules for scoping, e.g. elements like Authority, Submodes, Lines, Zones, Fare Sections.
A GPA contains information about:
- What specific limitation parameters (rules) the GPA includes, either of types Usage Parameters or Validity Parameters (Temporal or Scoping).
- What marketable/priceable object the GPA is related to, which include Sales Package, Preassigned Fare Product, Validable Element, Fare Structure Element, or a parent GPA (see Placement and structure).
- How the underlying parameters are to be validated, through operators set on Includes Grouping Type, Limitation Grouping Type, Validity Parameter Grouping Type and Validity Parameter Assignment Type (see Operators).
- If the GPA will be ignoring unsupported data types and values in endpoints that does not evaluate the data type, so that an offer can still be made (see Ignore flag 'canIgnoreInOffering').
- If the GPA is required in context (
requiredInContext), has a required type (requiredType) or has required elements (requiredElements) (see Context).
Implementations
There are currently two different GPA implementations used in offers, with some differences in how different GPAs are evaluated.
How a GPA implementation is selected in offers
Each GPA is set up with a GPA variant, through a field set on the GPA itself (comparisonOperatorVariant), with values (e.g. A or E),
pointing to what GPA implementation is to be used for this GPA in offers.
Each element (marketable/priceable object) that a GPA is attached to has set an active GPA variant (activeComparisonOperatorVariant)
with values (e.g.A or E) that decides what GPAs are to be used in offers.
The diagram below shows how an implementation in offers is selected based on the variant set on each element and GPAs.
Implementation E
Implementation E is the newest implementation, used for GPAs containing Scoping Validity Parameters (SVP). The main change is how the operators are used and read for a more consistent, simple and strict setup (see Operators). The way unknown data types are handled in the various endpoints are also changed, with the addition of the ignore flag 'canIgnoreInOffering' (see Ignore flag 'canIgnoreInOffering'). Implementation E exists in parallel with implementation A for a period, so both are valid and working in offers.
Implementation A
Implementation A is the original implementation. This implementation is still used for all Usage Parameters (UP), Temporal Validity Parameters (TVP) and some unconverted Scoping Validity Parameters (SVP).
Placement and structure
GPAs can be connected to an element (marketable/priceable object): a Fare Product, a Sales Package, a Validable Element, a Fare Structure Element, or as a child to another parent-GPA that's connected to a marketable/priceable object. There are no fixed rules for what type of object a GPA is and can be connected to, only guidelines and best practice.
If a GPA that is associated with an element (marketable/priceable object) has several GPA levels below it, it forms a tree structure where each node is a GPA.
Types of GPA nodes and what they can do and contain
In offers, the GPAs are divided into leaf nodes and parent nodes. The leaf nodes are the ones that perform data validation, while parent nodes only contain leaf GPA nodes or other parent nodes. There should never be nodes that are simultaneously a parent node (that have children GPAs) and a leaf node that perform data validation.
GPAs that are parent nodes only determine the kind of logical operation to be performed on their leaf nodes, and on these no data validation shall occur. On the parent nodes, only the 'Includes Grouping Type' data field must contain an operator that describes how the underlying leaf nodes are to be validated. If a GPA hierarchy contain Usage Parameters (UP), the data field for 'Includes Grouping Type' has no effect.
GPAs that are leaf nodes must contain data validation with an operator against a data type that determines the prerequisites/rules for an offer to be valid. The leaf nodes are considered as a chain of operations, consisting of retrieving data values, enforcing constraints on the data values, comparing data values from the product definition and query, examining whether the result should be ignored and finally a summary of the results that ends up with a Boolean value. Leaf nodes perform logical operations. In Implementation A, comparison operators are also performed, but in Implementation E they do an implicit comparison of data values (see Operators). Furthermore, leaf nodes may have limitations in the value space of the data values, and for some data types pre-processing of the data values is necessary.
Conditions and Choices
A GPA is in offers considered either a "condition" or a "choice", or a parent to other GPAs. If a GPA is a parent GPA, it includes other GPAs, that in their turn is either a "condition" or a "choice".
All types of GPAs can be set as 'Required In Context', have a 'Required Type' and potentially have 'Required Elements' (for more info see Context).
Conditions
If a GPA contains only Scoping Validity Parameters (SVP) or Temporal Validity Parameters (TVP) it will be a "condition". Common to all "conditions" is that they have a validation function that takes a list of TravelScopes as an argument and returns true or false.
Choices
If a GPA contains Usage Parameters (UP), either alone or in combination with any of the validity parameters, it will be a "choice". A "choice" has options, and consists of a list of Alternatives and has a method to retrieve valid alternatives based on TravelScopes and Travelers. Each alternative is evaluated and converted to a ValidAlternative if it is valid, otherwise filtered out. If there is no valid alternative for a "choice", it becomes a "failedChoice" and it will not result in an offer.
Special rules and prerequisites worth noting
A mix of Usage Parameters (UP) and the Validity Parameters (SVP & TVP) is only allowed when the parameters are on the same GPA, meaning that the SVP/TVP is scoping the validation of the Usage Parameter.
Scoping with PlaceUse (when used for zones) with different PlaceUse types (StartAt, Via, EndAt) cannot share the same GPA. There must be separate GPAs for SVPs with different PlaceUse values.
Context
To enforce the fulfilment of the GPA requirements in the context of an offer generating system, GPAs can be set as Required In Context, with a specific Required Type and with possible Required Elements, to require the element type upon travel.
When 'Required In Context' with the value OFFERING is added to a GPA, offers adds a Specific Parameter Assignment (SPA), with the type in 'RequiredType' set as limitations.
The SPA assigns this parameter to the offer, and is validated when the ticket is inspected upon travel.
For example, if 'Required In Context' is set to OFFERING and 'Required Type' is set to DATED_SERVICE_JOURNEY_REF, it returns valid if the passenger is on this exact Dated Service Journey upon validation.
See Swagger doc for example response for specificParameterAssignments in endpoint /offers/v2/{id}
| Field | Description | Example(s) |
|---|---|---|
| requiredInContext | The context in which the validity parameter assignment must be made specific by specifying the required type. Only OFFERING is evaluated when generating offers. | OFFERING, BOOKING, SALE, ACTIVATION |
| requiredType | Type of class that must be specified. | USER_PROFILE_REF, FARE_ZONE_REF, USAGE_VALIDITY_PERIOD, GROUP_TICKET, DATED_SERVICE_JOURNEY_REF |
| requiredElements | Name of element(s) that must be specified. | START_TIME, STANDARD_DURATION, START_STOP_POINT_REF, END_FARE_ZONE_REF |
Data Types
Data Types for Usage Parameters (UP)
| Data Type | Evaluated in offers | Required in offers | Example (NeTEx ID) |
|---|---|---|---|
| ChargingPolicy | ✕ No | ✕ No | ABC:ChargingPolicy:BillAsYouGo |
| CompanionProfile | ✕ No | ✕ No | ABC:CompanionProfile:Infant |
| EntitlementGiven | ✕ No | ✕ No | ABC:EntitlementGiven:Nullbillett |
| EntitlementRequired | ✓ Yes * | ✕ No | ABC:EntitlementRequired:levelA1 |
| Exchanging | ✕ No | ✕ No | ABC:Exchanging:FlexFee |
| FrequencyOfUse | ✓ Yes | ✕ No | ABC:FrequencyOfUse:TwiceADay |
| GroupTicket | ✕ No | ✓ Yes ** | ABC:GroupTicket:Sleeper |
| Interchanging | ✕ No | ✕ No | ABC:Interchanging:ThroughFare |
| LuggageAllowance | ✓ Yes | ✕ No | ABC:LuggageAllowance:Bicycle |
| PenaltyPolicy | ✕ No | ✕ No | ABC:PenaltyPolicy:InspectionFee |
| PurchaseWindow | ✓ Yes * | ✕ No | ABC:PurchaseWindow:StandardFromDuration |
| Refunding | ✕ No | ✕ No | ABC:Refunding:NoRefund |
| Replacing | ✕ No | ✕ No | ABC:Replacing:NoReplacing |
| Reselling | ✕ No | ✕ No | ABC:Reselling:NoReselling |
| Reserving | ✕ No | ✕ No | ABC:Reserving:CompulsoryRes |
| RoundTrip | ✓ Yes * | ✕ No | ABC:RoundTrip:TrainRoundTrip |
| SecurityPolicy | ✕ No | ✕ No | ABC:SecurityPolicy:HighLevel |
| Transferability | ✕ No | ✕ No | ABC:Transferability:AllowTransfer |
| UsageValidityPeriod | ✓ Yes * | ✕ No | ABC:UsageValidityPeriod:1Zone |
| UserProfile | ✓ Yes * | ✓ Yes ** | ABC:UserProfile:Adult |
** Either UserProfile or Group are implicitly required, since later we try to assign sales packages to travelers, and remove those that have not had any travelers assigned to them.
Data Types for Temporal Validity Parameters (TVP)
Temporal Validity Parameters (TVP) is reflecting temporal limitations (when e.g. a product may be used). They contain Validity Conditions like 'Valid Between' (to and from dates of which the travel can happen between), 'Day Type' (during what type of day the trip can happen) and 'Timeband' (during what time the trip can happen).
| Data Type | Evaluated in offers | Required in offers | Example (NeTEx ID) |
|---|---|---|---|
| DayType | ✓ Yes | ✕ No | ABC:DayType:abc123 |
| Timeband | ✓ Yes | ✕ No | ABC:Timeband:abc123 |
| ValidBetween | ✓ Yes | ✕ No | ABC:ValidBetween:abc123 |
Data Types for Scoping Validity Parameters (SVP)
We have chosen to divide the SVP data types into "simple data types" and "complex data types" in offers, because it is good to be aware that some data types are slightly more complex and can have their own setups, rules and exceptions. The "simple" data types only contain a text element, either a netex ID or the name of an enum value, while the "Complex" ones have slightly more complex and varied values and associations.
| Data Type | Evaluated in offers | Required in offers | Complexity | Example |
|---|---|---|---|---|
| Authority | ✓ Yes | ✕ No | Simple | ABC:Authority:ABC |
| DistributionChannel | ✓ Yes | ✕ No | Simple | ENT:DistributionChannel:Web |
| Line | ✓ Yes | ✕ No | Simple | ABC:Line:2_800 |
| VehicleMode | ✓ Yes | ✕ No | Simple | RAIL, BUS, WATER |
| TransportSubmode | ✓ Yes | ✕ No | Simple | regionalRail, local, nightBus |
| FacilitySet * | ✕ No | ✕ No | Simple | ABC:ServiceFacilitySet:Seating |
| FareClass * | ✕ No | ✕ No | Simple | STANDARD_CLASS, PREMIUM_CLASS |
| Operator * | ✕ No | ✕ No | Simple | 35, 57 |
| FareZones / tariffZones | ✓ Yes | ✕ No | Complex | ABC:FareZone:123 |
| FareSection | ✓ Yes | ✕ No | Complex | ABC:FareSection:123 |
| ScheduledStopPoint | ✓ Yes | ✕ No | Complex | NSR:StopPlace:374 |
| TopographicPlace | ✓ Yes | ✕ No | Complex | LAN:TopographicPlace:123 |
| GroupOfLines ** | ✕ No | ✕ No | - | - |
| GroupOfTariffZones ** | ✕ No | ✕ No | - | - |
** Not yet implemented.
Data Types that are handled in the various endpoints
There are several different endpoints for generating offers, and they receive different information in requests from clients.
DistributionChannel must always be provided by the client when making a request.
Authority is derived either from the request directly, from the journey pattern or from the FareZone.
All endpoints handle both Authority and DistributionChannel.
Some of the endpoints have implemented functionality to derive more data types than others, see table below.
| Endpoint | Additional data types the endpoint handles | Additional data sources where values are collected from |
|---|---|---|
/search/trip-pattern | All data types, except FacilitySet, FareClass and Operator | Information taken from the specific departure (journey pattern) |
/search/zones | FareZone | |
/search/stop-places (for trains) | FareSection Line ScheduledStopPoint | Detected journey along the rail network |
/search/stop-places (for other modes than trains) | Authority from owner of DME matrix for OriginDestination-products | |
/search/authority |
Operators
Assignments may be combined using logical operators and comparison operators to create composite assignments. GPAs that's on Implementation E does not use comparison operators (EQ is implicitly used).
Fields using operators
| Data Field containing operator | Type of operator | What it validates |
|---|---|---|
| includesGroupingType | logical operator | Describes how the leaf/child GPA nodes of a parent GPA node are to be validated |
| limitationGroupingType | logical operator | Describes data validation of underlying Usage Parameters (UP) |
| validityParameterGroupingType | logical operator | Describes data validation of underlying Scoping (SVP) and Temporal Parameter Assignments (TPA) |
| validityParameterAssignmentType | comparison operator | Describes data validation of underlying Scoping (SVP) and Temporal Parameter Assignments (TPA) |
Logical operators
| Logical operator | Notation of function | Description | Supported for SVP | Supported for TVP | Supported for UP |
|---|---|---|---|---|---|
| AND | Q == P(Q equals P) | The elements in the query (Q) and in the product definition (P) are equal | ✓ Yes | ✓ Yes | ✕ No |
| OR | Q ⊆ P && |Q| > 0(Q is a subset of P and the number of elements in Q is more than 0) | All elements in the query (Q) must also be found in the product definition (P) | ✓ Yes | ✓ Yes | ✓ Yes * |
| XOR (Exclusive OR) | Q ⊆ P && |Q| == 1(Q is a subset of P and the number of elements in Q must be 1) | There is only one element in the query (Q) and it must exist in the product definition (P) | ✓ Yes | ✓ Yes | ✕ No |
| NOT | Q ∩ P == ∅(Q and P have no common elements) | There are no items in the query (Q) that exists in the product definition (P) | ✓ Yes | ✓ Yes | ✕ No |
* GPAs containing Usage Parameters (UP) will only use the operator 'OR'.
Comparison operators
| Comparison operator | Description | Supported for SVP (implementation A) | Supported for SVP (implementation E) | Supported for TVP | Supported for UP |
|---|---|---|---|---|---|
| EQ (Equal) | Parameter value must be equal to the specified element | ✓ Yes | ✓ Yes | ✓ Yes | ✓ Yes |
| NE (Not equal) | Parameter value cannot be equal to the specified element | ✓ Yes | ✕ No | ✓ Yes | ✕ No |
| GT (Greater than) | Parameter value must be greater than the specified element. | ✓ Yes | ✕ No | ✓ Yes | ✕ No |
| GE (Greater than or equal to) | Parameter value must be greater than or equal to the specified element. | ✓ Yes | ✕ No | ✓ Yes | ✕ No |
| LT (Less than) | Parameter value must be less than the specified element. | ✓ No | ✕ No | ✓ Yes | ✕ No |
| LE (Less than or equal to) | Parameter value must be less than or equal to the specified element. | ✓ Yes | ✕ No | ✓ Yes | ✕ No |
Ignore flag 'canIgnoreInOffering'
The ignore flag is set per GPA, as a boolean field (can_ignore_in_offering). Only supported by Implementation E. Setting a GPA to be ignored in offering should mean "does not contribute to the calculation of the result".
Data types not found in an endpoint are handled as an empty set in evaluation. An empty set with the operators AND, OR or XOR will mean that you will not receive an offer.
E.g. a zone-based product with OR [localBus, metro] will not be offered in the /search/zones endpoint because it cannot derive transportSubmode, because the endpoint handles it as OR [{}, {}].
If there is a missing data value for a given data type in the offers search, then the evaluation of the data type and the values must be set to ignored in the GPA so that an offer can still be made in endpoints that does not evaluate them.
The ignore flag should not be allowed to be set on Authority or DistributionChannel (but always set on FareClass and FacilitySet, due to them not yet being evaluated in any endpoint).