Resolve conflicting element names in fares: StepLimitUnit, FulfilmentMethodTypes, NumberOfUnits#1043
Resolve conflicting element names in fares: StepLimitUnit, FulfilmentMethodTypes, NumberOfUnits#1043atibaut wants to merge 1 commit into
Conversation
atibaut
added
the
enhancement
There was a problem hiding this comment.
Pull request overview
This PR improves schema clarity in the fares model by resolving three element-name collisions (same element name used with different meanings/types in different contexts). It follows the established compatibility pattern (add correctly named element, deprecate old name, wrap in xsd:choice) to avoid breaking existing instance documents while improving generated bindings and implementer understanding.
Changes:
- Add
StepLimitUnitto STEP LIMIT and deprecateAdjustmentUnitsalias (choice-wrapped). - Add
FulfilmentMethodTypestoDistributionParametersGroupand deprecate singularFulfilmentMethodTypelist alias (choice-wrapped). - Add
NumberOfUnitsto AMOUNT OF PRICE UNIT PRODUCT and deprecate misleadingAmountalias (choice-wrapped); updateNameOfClassfor new names.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| xsd/netex_part_3/part3_fares/netex_usageParameterTravel_version.xsd | Adds StepLimitUnit and deprecates AdjustmentUnits via an optional xsd:choice in StepLimitGroup. |
| xsd/netex_part_3/part3_fares/netex_fareProduct_version.xsd | Adds NumberOfUnits and deprecates Amount via an optional xsd:choice in AmountOfPriceUnitProductGroup. |
| xsd/netex_part_3/part3_fares/netex_accessRightParameter_version.xsd | Adds FulfilmentMethodTypes and deprecates FulfilmentMethodType (list) via an optional xsd:choice in DistributionParametersGroup. |
| xsd/netex_framework/netex_responsibility/netex_entity_support.xsd | Extends NameOfClass enumeration with FulfilmentMethodTypes and StepLimitUnit values. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Are you sure you target the correct branch? |
Yes, the PR #1043 (fix/conflicting-element-names) targets v2.0 — the main development branch. |
This begins to feel like 3.0 work. |
I would like to see such semantical inconsistencies to be fixed sooner, perhaps v2.1-wip or v2.1-efip-wip. What do you think? |
|
100% agreed on sooner. But this will break existing implementation. Since we have released 2.0 this cannot 'just be a fix'. |
…dTypes and NumberOfUnits; deprecate misleadingly named forms
atibaut
force-pushed
the
fix/conflicting-element-names
branch
from
e3037cf to
901b812
Compare
|
@skinkie, base branch changed from Core decisions:
|
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:choiceso a document cannot state the same fact twice. New components are marked+v2.1, deprecations-v2.1.Proposed changes
1.
AdjustmentUnits/ quantity vs unit kindnetex_farePrice_version.xsd)AdjustmentUnitsisxsd:decimal(a step-calculation quantity); unchanged.netex_usageParameterTravel_version.xsd) the same nameAdjustmentUnitswas an enumeration (StepLimitUnitEnumeration: stops, sections, zones, networks, …) defined as 'Geographical parameter limiting the access rights by counts of stops, sections or zones'. New elementStepLimitUnitadded (name follows the enumeration and the owning STEP LIMIT entity);AdjustmentUnitsdeprecated.2.
FulfilmentMethodType/ singular name, list typenetex_salesDistribution_version.xsd) it is a single enumeration value; unchanged (name matches type).DistributionParametersGroup(netex_accessRightParameter_version.xsd) the same nameFulfilmentMethodTypeheld aFulfilmentMethodListOfEnumerations. New elementFulfilmentMethodTypesadded; the singular-named list deprecated.3.
Amounton AMOUNT OF PRICE UNIT / not a monetary amountnetex_farePrice_version.xsd)AmountisCurrencyAmountType(money); unchanged.netex_fareProduct_version.xsd)Amountisxsd:decimaldocumented as "Number of units". New elementNumberOfUnitsadded;Amountdeprecated.Framework
NameOfClassenumeration (netex_entity_support.xsd): valuesFulfilmentMethodTypesandStepLimitUnitadded in alphabetical position (NumberOfUnitsalready present).All four files have a
<Modified>changelog entry added.Related cases checked but not changed
PaymentMethodon 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.PaymentMethodelements onDistributionParametersGroupand 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
xsd:choicewrapping 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 inexamples/), so no example changes are needed.Verification (xmllint)
NeTEx_publication.xsdcompiles (proves the new choice content models are UPA-valid).<Amount>in other (unaffected) contexts:ENTUR-SchoolTwiceADayTripCarnet_2020120.xml,Netex_101.21_TfL_GeographicFares_UnitZone_MultipleProduct.xml,rail/Netex_era_crossborder_de.xml.