{"id":"metric-comparability","title":"Whether two metric definitions measure the same thing, and which fields differ","description":"Compares two structured metric definitions field by field (numerator, denominator, aggregation, weighting, population, filters, exclusions, period grain and calendar, timezone, currency, FX and tax basis, unit) and returns which differences make the numbers not comparable, which are adjustable with raw data, and which fields are missing from one side. In drift mode a is the old and b the new definition: a changed definition under an unchanged name is reported as definition-drift. For agents about to put two dashboards, reports or experiments side by side. It compares descriptions you supply after Unicode and punctuation normalization; it does not read data and cannot tell whether two differently worded definitions are equivalent.","roi":"Stops 'revenue' in one report being compared with 'revenue' in another. Instant, deterministic, $0.005.","audience":"developer","package":"data-contract-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/metric-comparability","path":"/api/v1/metric-comparability","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["a","b"],"properties":{"a":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","maxLength":120},"numerator":{"type":"string","maxLength":300,"description":"What is counted or summed, in words or SQL-free prose."},"denominator":{"type":"string","maxLength":300,"description":"The base of a ratio; omit for counts and sums."},"aggregation":{"type":"string","enum":["sum","count","distinct-count","mean","median","max","min","percentile","ratio-of-sums","mean-of-ratios"]},"weighting":{"type":"string","enum":["none","equal","volume","revenue","custom"]},"population":{"type":"string","maxLength":300,"description":"Who or what is measured (all users, paying accounts, active devices)."},"unit":{"type":"string","maxLength":60},"filters":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":200},"description":"Inclusion filters."},"exclusions":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":200},"description":"Excluded records (test accounts, refunds, internal traffic)."},"period":{"type":"object","additionalProperties":false,"properties":{"granularity":{"type":"string","enum":["hour","day","week","month","quarter","year","rolling"]},"calendar":{"type":"string","enum":["calendar","fiscal","iso-week","us-week","rolling"]},"windowDays":{"type":"integer","minimum":1,"maximum":3660},"timezone":{"type":"string","maxLength":60},"start":{"type":"string","maxLength":40},"end":{"type":"string","maxLength":40}}},"currency":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 alphabetic code."},"fxBasis":{"type":"string","enum":["none","transaction-date","period-average","period-end","fixed-rate"]},"taxBasis":{"type":"string","enum":["gross","net","unspecified"]}}},"definitionVersion":{"type":"string","maxLength":60}}},"b":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","maxLength":120},"numerator":{"type":"string","maxLength":300,"description":"What is counted or summed, in words or SQL-free prose."},"denominator":{"type":"string","maxLength":300,"description":"The base of a ratio; omit for counts and sums."},"aggregation":{"type":"string","enum":["sum","count","distinct-count","mean","median","max","min","percentile","ratio-of-sums","mean-of-ratios"]},"weighting":{"type":"string","enum":["none","equal","volume","revenue","custom"]},"population":{"type":"string","maxLength":300,"description":"Who or what is measured (all users, paying accounts, active devices)."},"unit":{"type":"string","maxLength":60},"filters":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":200},"description":"Inclusion filters."},"exclusions":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":200},"description":"Excluded records (test accounts, refunds, internal traffic)."},"period":{"type":"object","additionalProperties":false,"properties":{"granularity":{"type":"string","enum":["hour","day","week","month","quarter","year","rolling"]},"calendar":{"type":"string","enum":["calendar","fiscal","iso-week","us-week","rolling"]},"windowDays":{"type":"integer","minimum":1,"maximum":3660},"timezone":{"type":"string","maxLength":60},"start":{"type":"string","maxLength":40},"end":{"type":"string","maxLength":40}}},"currency":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 alphabetic code."},"fxBasis":{"type":"string","enum":["none","transaction-date","period-average","period-end","fixed-rate"]},"taxBasis":{"type":"string","enum":["gross","net","unspecified"]}}},"definitionVersion":{"type":"string","maxLength":60}}},"mode":{"type":"string","enum":["compare","drift"],"description":"drift: a is the previous definition and b the current one under the same name."}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"verdict":{"type":"string","enum":["identical","comparable-with-adjustment","not-comparable","incomplete"]},"nameMatch":{"type":"boolean"},"drift":{"type":"boolean","description":"Same name (after normalization) but at least one blocking or adjustable difference."},"differences":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"severity":{"type":"string","enum":["blocking","adjustable","info","missing"]},"a":{"description":"Value in a (null when absent)."},"b":{"description":"Value in b (null when absent)."},"effect":{"type":"string"}}}},"comparedFields":{"type":"integer"},"skippedFields":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"verdict":{"type":"string","enum":["identical","comparable-with-adjustment","not-comparable","incomplete"]},"nameMatch":{"type":"boolean"},"drift":{"type":"boolean","description":"Same name (after normalization) but at least one blocking or adjustable difference."},"differences":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"severity":{"type":"string","enum":["blocking","adjustable","info","missing"]},"a":{"description":"Value in a (null when absent)."},"b":{"description":"Value in b (null when absent)."},"effect":{"type":"string"}}}},"comparedFields":{"type":"integer"},"skippedFields":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"a":{"name":"conversion rate","numerator":"orders","denominator":"sessions","aggregation":"ratio-of-sums","exclusions":["internal traffic"],"period":{"granularity":"week","calendar":"iso-week","timezone":"UTC"}},"b":{"name":"Conversion Rate","numerator":"orders","denominator":"unique visitors","aggregation":"mean-of-ratios","exclusions":["internal traffic","bots"],"period":{"granularity":"week","calendar":"us-week","timezone":"America/New_York"}},"mode":"drift"},"openapiOperation":{"operationId":"metric_comparability","summary":"Whether two metric definitions measure the same thing, and which fields differ","description":"Compares two structured metric definitions field by field (numerator, denominator, aggregation, weighting, population, filters, exclusions, period grain and calendar, timezone, currency, FX and tax basis, unit) and returns which differences make the numbers not comparable, which are adjustable with raw data, and which fields are missing from one side. In drift mode a is the old and b the new definition: a changed definition under an unchanged name is reported as definition-drift. For agents about to put two dashboards, reports or experiments side by side. It compares descriptions you supply after Unicode and punctuation normalization; it does not read data and cannot tell whether two differently worded definitions are equivalent.\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"developer","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/metric-comparability","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["a","b"],"properties":{"a":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","maxLength":120},"numerator":{"type":"string","maxLength":300,"description":"What is counted or summed, in words or SQL-free prose."},"denominator":{"type":"string","maxLength":300,"description":"The base of a ratio; omit for counts and sums."},"aggregation":{"type":"string","enum":["sum","count","distinct-count","mean","median","max","min","percentile","ratio-of-sums","mean-of-ratios"]},"weighting":{"type":"string","enum":["none","equal","volume","revenue","custom"]},"population":{"type":"string","maxLength":300,"description":"Who or what is measured (all users, paying accounts, active devices)."},"unit":{"type":"string","maxLength":60},"filters":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":200},"description":"Inclusion filters."},"exclusions":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":200},"description":"Excluded records (test accounts, refunds, internal traffic)."},"period":{"type":"object","additionalProperties":false,"properties":{"granularity":{"type":"string","enum":["hour","day","week","month","quarter","year","rolling"]},"calendar":{"type":"string","enum":["calendar","fiscal","iso-week","us-week","rolling"]},"windowDays":{"type":"integer","minimum":1,"maximum":3660},"timezone":{"type":"string","maxLength":60},"start":{"type":"string","maxLength":40},"end":{"type":"string","maxLength":40}}},"currency":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 alphabetic code."},"fxBasis":{"type":"string","enum":["none","transaction-date","period-average","period-end","fixed-rate"]},"taxBasis":{"type":"string","enum":["gross","net","unspecified"]}}},"definitionVersion":{"type":"string","maxLength":60}}},"b":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","maxLength":120},"numerator":{"type":"string","maxLength":300,"description":"What is counted or summed, in words or SQL-free prose."},"denominator":{"type":"string","maxLength":300,"description":"The base of a ratio; omit for counts and sums."},"aggregation":{"type":"string","enum":["sum","count","distinct-count","mean","median","max","min","percentile","ratio-of-sums","mean-of-ratios"]},"weighting":{"type":"string","enum":["none","equal","volume","revenue","custom"]},"population":{"type":"string","maxLength":300,"description":"Who or what is measured (all users, paying accounts, active devices)."},"unit":{"type":"string","maxLength":60},"filters":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":200},"description":"Inclusion filters."},"exclusions":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":200},"description":"Excluded records (test accounts, refunds, internal traffic)."},"period":{"type":"object","additionalProperties":false,"properties":{"granularity":{"type":"string","enum":["hour","day","week","month","quarter","year","rolling"]},"calendar":{"type":"string","enum":["calendar","fiscal","iso-week","us-week","rolling"]},"windowDays":{"type":"integer","minimum":1,"maximum":3660},"timezone":{"type":"string","maxLength":60},"start":{"type":"string","maxLength":40},"end":{"type":"string","maxLength":40}}},"currency":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","maxLength":3,"minLength":3,"description":"ISO 4217 alphabetic code."},"fxBasis":{"type":"string","enum":["none","transaction-date","period-average","period-end","fixed-rate"]},"taxBasis":{"type":"string","enum":["gross","net","unspecified"]}}},"definitionVersion":{"type":"string","maxLength":60}}},"mode":{"type":"string","enum":["compare","drift"],"description":"drift: a is the previous definition and b the current one under the same name."}}},"example":{"a":{"name":"conversion rate","numerator":"orders","denominator":"sessions","aggregation":"ratio-of-sums","exclusions":["internal traffic"],"period":{"granularity":"week","calendar":"iso-week","timezone":"UTC"}},"b":{"name":"Conversion Rate","numerator":"orders","denominator":"unique visitors","aggregation":"mean-of-ratios","exclusions":["internal traffic","bots"],"period":{"granularity":"week","calendar":"us-week","timezone":"America/New_York"}},"mode":"drift"}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"verdict":{"type":"string","enum":["identical","comparable-with-adjustment","not-comparable","incomplete"]},"nameMatch":{"type":"boolean"},"drift":{"type":"boolean","description":"Same name (after normalization) but at least one blocking or adjustable difference."},"differences":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"severity":{"type":"string","enum":["blocking","adjustable","info","missing"]},"a":{"description":"Value in a (null when absent)."},"b":{"description":"Value in b (null when absent)."},"effect":{"type":"string"}}}},"comparedFields":{"type":"integer"},"skippedFields":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/metric-comparability/","docsJson":"https://agents.writerslogic.com/docs/metric-comparability.json","sample":"https://agents.writerslogic.com/api/v1/samples/metric-comparability","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}