{"id":"enum-canonicalize","title":"Map free-text values onto a closed set of allowed values, or abstain","description":"Maps each input string onto one member of a closed caller-supplied set using, in order: exact match, caller aliases, a deterministic normal form (Unicode NFKC, case and accent folding, punctuation and underscore collapse), then bounded edit distance (optimal string alignment, so a swapped pair of letters costs 1). Returns the canonical value, the method, the distance and the nearest candidates; it abstains (null) when nothing is within the threshold or when two allowed values tie, and it never guesses. For agents cleaning status, country, category or unit fields before writing them to a typed column. It does not translate, use synonyms beyond your aliases, or infer meaning.","roi":"A closed-set normalizer with an abstain path. 200 values against 500 allowed entries per $0.005 call.","audience":"developer","package":"data-contract-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/enum-canonicalize","path":"/api/v1/enum-canonicalize","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["values","allowed"],"properties":{"values":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"string","maxLength":100},"description":"Strings to canonicalize."},"allowed":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","maxLength":100},"description":"The closed set of canonical values."},"aliases":{"type":"array","maxItems":500,"items":{"type":"object","additionalProperties":false,"required":["alias","canonical"],"properties":{"alias":{"type":"string","maxLength":100},"canonical":{"type":"string","maxLength":100}}},"description":"Caller synonyms; each canonical must be in allowed."},"maxDistance":{"type":"integer","minimum":0,"maximum":5,"description":"Largest edit distance accepted (default 2). The effective limit is also capped at one third of the normalized input length."},"caseSensitive":{"type":"boolean","description":"Skip case, accent and punctuation folding (only NFKC and whitespace collapse). Default false."}}},"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."},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"input":{"type":"string"},"canonical":{"anyOf":[{"type":"string"},{"type":"null"}]},"method":{"type":"string","enum":["exact","alias","normalized","fuzzy","ambiguous","no-match"]},"distance":{"anyOf":[{"type":"integer"},{"type":"null"}]},"threshold":{"type":"integer","description":"Largest distance that would have been accepted for this input."},"candidates":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"distance":{"type":"integer"}}}}}}},"allowedCollisions":{"type":"array","items":{"type":"object","properties":{"normalized":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}},"description":"Allowed values that share a normal form; inputs landing there are ambiguous."},"counts":{"type":"object","properties":{"resolved":{"type":"integer"},"ambiguous":{"type":"integer"},"noMatch":{"type":"integer"}}},"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."},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"input":{"type":"string"},"canonical":{"anyOf":[{"type":"string"},{"type":"null"}]},"method":{"type":"string","enum":["exact","alias","normalized","fuzzy","ambiguous","no-match"]},"distance":{"anyOf":[{"type":"integer"},{"type":"null"}]},"threshold":{"type":"integer","description":"Largest distance that would have been accepted for this input."},"candidates":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"distance":{"type":"integer"}}}}}}},"allowedCollisions":{"type":"array","items":{"type":"object","properties":{"normalized":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}},"description":"Allowed values that share a normal form; inputs landing there are ambiguous."},"counts":{"type":"object","properties":{"resolved":{"type":"integer"},"ambiguous":{"type":"integer"},"noMatch":{"type":"integer"}}},"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":{"values":["Unted States","usa","U.S. of America","Atlantis"],"allowed":["United States","Canada","Mexico"],"aliases":[{"alias":"usa","canonical":"United States"},{"alias":"u s of america","canonical":"United States"}]},"openapiOperation":{"operationId":"enum_canonicalize","summary":"Map free-text values onto a closed set of allowed values, or abstain","description":"Maps each input string onto one member of a closed caller-supplied set using, in order: exact match, caller aliases, a deterministic normal form (Unicode NFKC, case and accent folding, punctuation and underscore collapse), then bounded edit distance (optimal string alignment, so a swapped pair of letters costs 1). Returns the canonical value, the method, the distance and the nearest candidates; it abstains (null) when nothing is within the threshold or when two allowed values tie, and it never guesses. For agents cleaning status, country, category or unit fields before writing them to a typed column. It does not translate, use synonyms beyond your aliases, or infer meaning.\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/enum-canonicalize","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["values","allowed"],"properties":{"values":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"string","maxLength":100},"description":"Strings to canonicalize."},"allowed":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","maxLength":100},"description":"The closed set of canonical values."},"aliases":{"type":"array","maxItems":500,"items":{"type":"object","additionalProperties":false,"required":["alias","canonical"],"properties":{"alias":{"type":"string","maxLength":100},"canonical":{"type":"string","maxLength":100}}},"description":"Caller synonyms; each canonical must be in allowed."},"maxDistance":{"type":"integer","minimum":0,"maximum":5,"description":"Largest edit distance accepted (default 2). The effective limit is also capped at one third of the normalized input length."},"caseSensitive":{"type":"boolean","description":"Skip case, accent and punctuation folding (only NFKC and whitespace collapse). Default false."}}},"example":{"values":["Unted States","usa","U.S. of America","Atlantis"],"allowed":["United States","Canada","Mexico"],"aliases":[{"alias":"usa","canonical":"United States"},{"alias":"u s of america","canonical":"United States"}]}}}},"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."},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"input":{"type":"string"},"canonical":{"anyOf":[{"type":"string"},{"type":"null"}]},"method":{"type":"string","enum":["exact","alias","normalized","fuzzy","ambiguous","no-match"]},"distance":{"anyOf":[{"type":"integer"},{"type":"null"}]},"threshold":{"type":"integer","description":"Largest distance that would have been accepted for this input."},"candidates":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"distance":{"type":"integer"}}}}}}},"allowedCollisions":{"type":"array","items":{"type":"object","properties":{"normalized":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}},"description":"Allowed values that share a normal form; inputs landing there are ambiguous."},"counts":{"type":"object","properties":{"resolved":{"type":"integer"},"ambiguous":{"type":"integer"},"noMatch":{"type":"integer"}}},"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/enum-canonicalize/","docsJson":"https://agents.writerslogic.com/docs/enum-canonicalize.json","sample":"https://agents.writerslogic.com/api/v1/samples/enum-canonicalize","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"}}