PLAT-287894: Add uncapped paid-media calculated-rate fields; deprecate capped originals#2202
Open
ejsuncy wants to merge 1 commit into
Open
PLAT-287894: Add uncapped paid-media calculated-rate fields; deprecate capped originals#2202ejsuncy wants to merge 1 commit into
ejsuncy wants to merge 1 commit into
Conversation
…e capped originals The maximum:1.0 cap on several calculated-rate fields rejects legitimate values >1.0. Rates whose numerator and denominator come from different event populations can exceed 1.0 (e.g. Google Ads all-conversions/clicks, multiple engagements per impression, spend overrunning budget). These fields are now stable, so the cap cannot be removed or relaxed in place (breaking change, and blocked by the xed-validation restricted-property gate). Instead, add new uncapped sibling fields (minimum:0, no maximum) and mark the capped originals meta:status:deprecated with a pointer to the replacement: ctr -> ctrUncapped conversionRate -> conversionRateUncapped engagementRate -> engagementRateUncapped budgetUtilization -> budgetUtilizationUncapped dailyBudgetUtilization -> dailyBudgetUtilizationUncapped negativeActionRate -> negativeActionRateUncapped positiveActionRate -> positiveActionRateUncapped crossDeviceConversionRate -> crossDeviceConversionRateUncapped Non-breaking: purely additive. Capped fields retain minimum:0, maximum:1 untouched. Examples updated to exercise the new fields (with >1.0 values where the metric can legitimately exceed 1.0). Validation: npm test 2406 passing; lint clean; incompatibility-check clean; xed-validation "No disallowed changes detected" + "All good". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ejsuncy
force-pushed
the
feature-2201-paid-media-rate-caps
branch
from
ac52479 to
1bba6ef
Compare
ejsuncy
changed the title
Contributor
Author
|
This is now ready |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #2201
Jira: PLAT-287894
Adds new uncapped paid-media calculated-rate fields and deprecates the capped originals. Non-breaking — purely additive; the capped fields are retained unchanged (
minimum: 0,maximum: 1), so existing data and producers keep working.Motivation
Ingesting Google Ads summary metrics failed because
paidMedia.conversionMetrics.conversionRate(mapped to Google Adsmetrics.conversions_from_interactions_rate=all_conversions / interactions) returned2.0, exceeding themaximum: 1.0cap. These rates have a numerator and denominator drawn from different event populations (numerator is not a subset of the denominator), so they can legitimately exceed 1.0. Multiple conversions can be attributed to a single click, and networks can similarly inflate CTR and engagement counts.Approach
These fields are now
meta:status: stable. Removing or relaxing themaximumin place is a breaking change and is blocked by thexed-validationrestricted-property gate (check_properties.jsflags any change to an existingmaximum/minimum). Per CONTRIBUTING/CLAUDE guidance ("deprecate, don't remove or rename"), this PR instead:minimum: 0, nomaximum,meta:status: stable), andmeta:status: deprecatedwith a description pointer to its replacement.This is the same pattern used elsewhere in the repo (e.g.
pushdetailblacklisted→blocklisted).ctrctrUncappedconversionRateconversionRateUncappedengagementRateengagementRateUncappedbudgetUtilizationbudgetUtilizationUncappeddailyBudgetUtilizationdailyBudgetUtilizationUncappednegativeActionRatenegativeActionRateUncappedpositiveActionRatepositiveActionRateUncappedcrossDeviceConversionRatecrossDeviceConversionRateUncappedTrue subset/total proportions that are mathematically bounded at 1.0 are untouched and keep their cap:
viewabilityRate, video view/completion/skip rates,fraudRate,validationRate,leadFormCompletionRate, invalid/bot/human traffic rates, theimpressionShareset, attribution weights/confidence/contribution, and statistical indices.Changes
core-paid-media-conversion-metrics.schema.json— deprecateconversionRate, addconversionRateUncappedcore-paid-media-metrics.schema.json— deprecatectr/engagementRate, addctrUncapped/engagementRateUncappedcore-paid-media-cost-metrics.schema.json— deprecatebudgetUtilization/dailyBudgetUtilization, addbudgetUtilizationUncapped/dailyBudgetUtilizationUncappedcore-paid-media-quality-metrics.schema.json— deprecatenegativeActionRate/positiveActionRate, addnegativeActionRateUncapped/positiveActionRateUncappedcore-paid-media-attribution-metrics.schema.json— deprecatecrossDeviceConversionRate, addcrossDeviceConversionRateUncapped*.example.1.jsonfiles updated to exercise the new fields (with >1.0 values where the metric can legitimately exceed 1.0)Validation
npm test— 2406 passingnpm run lint— clean (prettier added no extra changes)npm run incompatibility-check— clean (exit 0)npm run xed-validation—No disallowed changes detected+All goodBreaking changes
None.