Skip to content

Resolve conflicting element names in fares: StepLimitUnit, FulfilmentMethodTypes, NumberOfUnits#1049

Open
atibaut wants to merge 1 commit into
v2.1-wipfrom
fix/conflicting-element-names
Open

Resolve conflicting element names in fares: StepLimitUnit, FulfilmentMethodTypes, NumberOfUnits#1049
atibaut wants to merge 1 commit into
v2.1-wipfrom
fix/conflicting-element-names

Conversation

@atibaut

@atibaut atibaut commented Jul 19, 2026

Copy link
Copy Markdown
Contributor

Following my semantic wave... because better machine reasoning depends on humans describing semantics with precision and without ambiguity.

Several fares elements share a name with an element of a different type or meaning in another context, which misleads implementers and produces confusing generated bindings. This PR resolves the three genuine cases without breaking existing documents, using the same pattern as #1041: the correctly named element is added, the old one is deprecated, and both are wrapped in an xsd:choice so a document cannot state the same fact twice. New components are marked +v2.1, deprecations -v2.1.

Proposed changes

1. AdjustmentUnits / quantity vs unit kind

  • On RULE STEP RESULT (netex_farePrice_version.xsd) AdjustmentUnits is xsd:decimal (a step-calculation quantity); unchanged.
  • On STEP LIMIT (netex_usageParameterTravel_version.xsd) the same name AdjustmentUnits was an enumeration (StepLimitUnitEnumeration: stops, sections, zones, networks, …) defined as 'Geographical parameter limiting the access rights by counts of stops, sections or zones'. New element StepLimitUnit added (name follows the enumeration and the owning STEP LIMIT entity); AdjustmentUnits deprecated.

2. FulfilmentMethodType / singular name, list type

  • On FULFILMENT METHOD (netex_salesDistribution_version.xsd) it is a single enumeration value; unchanged (name matches type).
  • In DistributionParametersGroup (netex_accessRightParameter_version.xsd) the same name FulfilmentMethodType held a FulfilmentMethodListOfEnumerations. New element FulfilmentMethodTypes added; the singular-named list deprecated.

3. Amount on AMOUNT OF PRICE UNIT / not a monetary amount

  • On FARE PRICE (netex_farePrice_version.xsd) Amount is CurrencyAmountType (money); unchanged.
  • On AMOUNT OF PRICE UNIT PRODUCT (netex_fareProduct_version.xsd) Amount is xsd:decimal documented as "Number of units". New element NumberOfUnits added; Amount deprecated.

Framework

  • NameOfClass enumeration (netex_entity_support.xsd): values FulfilmentMethodTypes and StepLimitUnit added in alphabetical position (NumberOfUnits already present).

All four files have a <Modified> changelog entry added.

Related cases checked but not changed

  • PaymentMethod on REFUNDING (netex_usageParameterAfterSales_version.xsd) also carries a list type under a singular name, but it is already deprecated in the schema ("DEPRECATED - use PaymentMethods on RESELLING"), so no change is needed.
  • The single-valued PaymentMethod elements on DistributionParametersGroup and fare table cells are internally consistent (singular name, singular type); whether they should allow multiple values is a modelling question for the team, not a naming defect, so they were left as-is.

Backwards compatibility

  • Old element names remain valid; the xsd:choice wrapping only prevents using both the old and new name simultaneously. No example uses the affected elements in the changed contexts (checked: no <AmountOfPriceUnit>, <AdjustmentUnits> or <FulfilmentMethodType> instances in examples/), so no example changes are needed.
  • Generated bindings gain new members but lose none.

Verification (xmllint)

  • NeTEx_publication.xsd compiles (proves the new choice content models are UPA-valid).
  • Examples validate unchanged, including those with <Amount> in other (unaffected) contexts: ENTUR-SchoolTwiceADayTripCarnet_2020120.xml, Netex_101.21_TfL_GeographicFares_UnitZone_MultipleProduct.xml, rail/Netex_era_crossborder_de.xml.

Supersedes #1043

Closes and replaces #1043: rebuilt as a single commit on the current v2.1-wip tip (was 11 commits behind, causing conflicts), resolving two context conflicts (fareProduct, usageParameterTravel) that arose purely from line-shift against unrelated intervening changes, no semantic changes to the resolution itself.

…dTypes and NumberOfUnits; deprecate misleadingly named forms
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants