TariffZoneConstraint / SameZoneEnumeration should add support for new enum value "neighbouring"

[viliket]

SameZoneEnumeration should add support for new enum value "neighbouring" to allow e.g. specifying a FareStructureElement with a GenericParameterAssignment with an EntitlementRequired with EntitlementConstraint with TariffZoneConstraint as neighbouring.

This would allow defining e.g. that one is entitled to purchase a C-zone extension ticket for a season pass valid for zones A and B since zone C is adjacent to season pass zone B. Here is a concrete example:

<FareStructureElement id="tst:Tariff@Extension@prerequisites" version="1.0">
	<Name>Prerequisites for zone extension ticket</Name>
	<GenericParameterAssignment version="1.0" id="tst:Tariff@Extension@prerequisites" order="1">
		<Name>Only available as Add on to season pass</Name>
		<TypeOfAccessRightAssignmentRef version="fxc:v1.0" ref="fxc:prerequisites"/>
		<LimitationGroupingType>AND</LimitationGroupingType>
		<limitations>
			<EntitlementRequired id="tst:Tariff@Extension@prerequisites@Period_pass" version="1.0">
				<Name>Must have a season pass with neighbouring tariff zone</Name>
				<PreassignedFareProductRef version="1.0" ref="atc:Rail@Period_pass"/>
				<EntitlementConstraint>
					<PeriodConstraint>withinSamePeriod</PeriodConstraint>
					<TariffZoneConstraint>neighbouring</TariffZoneConstraint>
				</EntitlementConstraint>
			</EntitlementRequired>
		</limitations>
	</GenericParameterAssignment>
</FareStructureElement>

The proposed naming follows neighbours ("Adjacent FARE ZONEs.") field on FareZone element.

[skinkie]

How can a receiving system know that something is neighbouring? I would be much more happy with actual references. For example neighbouringTariffZones/TariffZoneContraintRef as a clean up in next.

[viliket]

How can a receiving system know that something is neighbouring? I would be much more happy with actual references. For example neighbouringTariffZones/TariffZoneContraintRef as a clean up in next.

The FareZone type has the neighbours property with documentation "Adjacent FARE ZONEs."- so in my mind if e.g. the period pass product has listed its valid fare zones the system can check from each of the listed fare zone's neighbours to see which are the neighbouring fare zones. And then for the neighbouring constraint verifying whether any of the extension ticket's selected zones is a neighbour of the season pass's fare zones.

[skinkie]

@viliket if it already does, that works for me too.

[viliket]

Rethinking the proposed name of the enum value to reduce ambiguity: probably "connected" would make more sense of the intention of this constraint (from graph theory). The intention of this proposed constraint is to state that the zone extension ticket could only be sold as an add on to a season pass where the zones extend the original season pass zones while forming a connected graph so that the traveller can travel between the season pass + extension ticket zones.

<FareStructureElement id="tst:Tariff@Extension@prerequisites" version="1.0">
	<Name>Prerequisites for zone extension ticket</Name>
	<GenericParameterAssignment version="1.0" id="tst:Tariff@Extension@prerequisites" order="1">
		<Name>Only available as Add on to season pass</Name>
		<TypeOfAccessRightAssignmentRef version="fxc:v1.0" ref="fxc:prerequisites"/>
		<LimitationGroupingType>AND</LimitationGroupingType>
		<limitations>
			<EntitlementRequired id="tst:Tariff@Extension@prerequisites@Period_pass" version="1.0">
				<Name>Must have a season pass with connected tariff zones</Name>
				<PreassignedFareProductRef version="1.0" ref="atc:Rail@Period_pass"/>
				<EntitlementConstraint>
					<PeriodConstraint>withinSamePeriod</PeriodConstraint>
					<TariffZoneConstraint>connected</TariffZoneConstraint>
				</EntitlementConstraint>
			</EntitlementRequired>
		</limitations>
	</GenericParameterAssignment>
</FareStructureElement>

Below is a visualization of various examples. Note that the ↔ symbol marks the neighbourhood between the tariff zones. As stated earlier, the neighourhood can already be expressed in NeTEx by the existing neighbours property of the FareZone.

[Aurige]

Looks Ok, to be double checked by @nick-knowles

[Aurige]

Can also be covered by a single step in a zone counting system

[nick-knowles]

Looks fine to me / UML updated

[Aurige]

Solved by #823