{"record":{"id":"b9f7c1d14dd4f0ad","repo":"ComposioHQ/composio","slug":"dynamic-key-schema-reference-reference-r-must-be","errorCode":null,"errorMessage":"Dynamic-key schema reference {reference!r} must be a local JSON Pointer","messagePattern":"Dynamic-key schema reference (.+?) must be a local JSON Pointer","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/composio/utils/schema_converter.py","lineNumber":344,"sourceCode":"    \"\"\"Whether Pydantic must run after validation to materialize a default.\"\"\"\n    if isinstance(schema, list):\n        return any(_contains_default(item) for item in schema)\n    if not isinstance(schema, dict):\n        return False\n    return \"default\" in schema or any(\n        _contains_default(value) for value in schema.values()\n    )\n\n\ndef _resolve_local_json_pointer(\n    reference: str,\n    root_schema: t.Dict[str, t.Any],\n) -> t.Any:\n    \"\"\"Resolve a local JSON Pointer or fail while the model is constructed.\"\"\"\n    if reference == \"#\":\n        return root_schema\n    if not reference.startswith(\"#/\"):\n        raise ValueError(\n            f\"Dynamic-key schema reference {reference!r} must be a local JSON Pointer\"\n        )\n\n    current: t.Any = root_schema\n    for raw_token in unquote(reference[2:]).split(\"/\"):\n        token = raw_token.replace(\"~1\", \"/\").replace(\"~0\", \"~\")\n        if isinstance(current, dict) and token in current:\n            current = current[token]\n            continue\n        if isinstance(current, list):\n            try:\n                current = current[int(token)]\n                continue\n            except (ValueError, IndexError):\n                pass\n        raise ValueError(f\"Unresolvable dynamic-key schema reference: {reference!r}\")\n    return current\n","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/python/composio/utils/schema_converter.py#L326-L362","documentation":"schema_converter.py only supports local JSON Pointer references (\"#\" or \"#/path/...\") when resolving dynamic-key schemas. If a $ref is an external/absolute URL or a plain fragment without \"#/\", _resolve_local_json_pointer raises this ValueError during model construction because the converter has no mechanism to fetch external references.","triggerScenarios":"A tool input schema contains \"$ref\": \"https://example.com/schema.json\" (external), \"#/definitions\" without the leading slash form, or an anchor-style ref like \"#myAnchor\". The converter hits it while building the dynamic-key policy for a dict whose keys map to schemas.","commonSituations":"Tool schemas imported from external OpenAPI documents that keep remote $refs; specs using JSON Schema 2019-09 $anchor style; specs authored with $id-based instead of pointer-based refs; converted OpenAPI whose \"#/components/schemas/...\" refs were mangled during transformation.","solutions":["Inline the external schema at the referencing site, or convert the $ref into a local pointer (\"#/definitions/X\") by embedding the target under definitions/$defs in the same document","Replace anchor refs with JSON Pointer refs like \"#/definitions/anchor-name\"","If the schema is backend-generated, report it — external refs are not supported by the converter"],"exampleFix":"# before\n{\"$ref\": \"https://schemas.example.com/user.json\"}\n# after\n{\"$defs\": {\"user\": {...}}, \"$ref\": \"#/$defs/user\"}","handlingStrategy":"validation","validationCode":"def refs_are_local(schema):\n    if isinstance(schema, dict):\n        r = schema.get(\"$ref\")\n        if r is not None and not (r == \"#\" or r.startswith(\"#/\")):\n            return False\n        return all(refs_are_local(v) for v in schema.values())\n    if isinstance(schema, list):\n        return all(refs_are_local(i) for i in schema)\n    return True\nassert refs_are_local(schema)","typeGuard":null,"tryCatchPattern":"try:\n    build_model(schema)\nexcept ValueError as e:\n    if \"must be a local JSON Pointer\" in str(e):\n        schema = inline_external_refs(schema)","preventionTips":["Inline or localize all $refs before passing schemas to the SDK","Avoid $anchor-style refs; use #/definitions/... pointers","Run a quick recursive ref check on schemas from external sources"],"tags":["json-schema","ref-resolution","dynamic-keys"],"backgroundTag":"unresolvable-json-schema-ref","analyzedSha":"64b1b85502b1beeb2379e6c9e8bf1104504fa637","analyzedAt":"2026-08-28T15:39:33.623Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}