{"record":{"id":"52c0abcc664c3425","repo":"ComposioHQ/composio","slug":"dynamic-key-schema-reference-reference-r-does-no","errorCode":null,"errorMessage":"Dynamic-key schema reference {reference!r} does not target a schema","messagePattern":"Dynamic-key schema reference (.+?) does not target a schema","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/composio/utils/schema_converter.py","lineNumber":618,"sourceCode":"    ``examples`` hold instance data, so a ``$ref``-shaped value stored there is\n    a payload rather than a reference and must not block tool wrapping.\n    \"\"\"\n    if checked_references is None:\n        checked_references = set()\n    if isinstance(schema, list):\n        for item in schema:\n            _check_dynamic_references(item, root_schema, checked_references)\n        return\n    if not isinstance(schema, dict):\n        return\n\n    reference = schema.get(\"$ref\")\n    if reference is not None:\n        if not isinstance(reference, str):\n            raise ValueError(\"Dynamic-key schema `$ref` must be a string\")\n        resolved = _resolve_local_json_pointer(reference, root_schema)\n        if not isinstance(resolved, (dict, bool)):\n            raise ValueError(\n                f\"Dynamic-key schema reference {reference!r} does not target a schema\"\n            )\n        if reference not in checked_references:\n            checked_references.add(reference)\n            _check_dynamic_references(resolved, root_schema, checked_references)\n\n    for keyword, value in schema.items():\n        if keyword in _SCHEMA_VALUED_KEYWORDS or keyword in _SCHEMA_LIST_KEYWORDS:\n            _check_dynamic_references(value, root_schema, checked_references)\n        elif keyword in _SCHEMA_MAP_KEYWORDS:\n            if isinstance(value, dict):\n                for entry in value.values():\n                    _check_dynamic_references(entry, root_schema, checked_references)\n        elif keyword == \"items\":\n            # A schema, or a list of schemas for tuple validation.\n            _check_dynamic_references(value, root_schema, checked_references)\n        elif keyword == \"dependencies\":\n            # Each entry is either a schema or a list of required property names.","sourceCodeStart":600,"sourceCodeEnd":636,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/python/composio/utils/schema_converter.py#L600-L636","documentation":"The local $ref resolved successfully but pointed at something that is not a schema — not a dict and not a boolean (e.g. a string, number, or array of values). Dynamic-key references must target JSON Schema nodes, so _check_dynamic_references raises ValueError at construction time.","triggerScenarios":"\"$ref\": \"#/definitions/label\" where definitions.label is the string \"user\" (an enum value leaked into definitions); pointers aimed at examples, descriptions, or other metadata nodes instead of schema nodes.","commonSituations":"Schemas that also store constants/enums under definitions and a ref accidentally points there; pointer off-by-one errors landing on a sibling key; LLM- or template-authored schemas confusing values with schemas.","solutions":["Retarget the $ref to a node that is an actual schema object (or boolean)","Move non-schema constants out of definitions, or wrap the referenced value in {\"enum\": [...]} and point at that","Re-validate the document structure before conversion"],"exampleFix":"# before\n{\"$defs\": {\"role\": \"admin\"}, \"$ref\": \"#/$defs/role\"}\n# after\n{\"$defs\": {\"role\": {\"enum\": [\"admin\"]}}, \"$ref\": \"#/$defs/role\"}","handlingStrategy":"validation","validationCode":"def ref_targets_schema(ref, root):\n    cur = root\n    for tok in ref[2:].split(\"/\"):\n        tok = tok.replace(\"~1\", \"/\").replace(\"~0\", \"~\")\n        cur = cur.get(tok) if isinstance(cur, dict) else (cur[int(tok)] if isinstance(cur, list) and tok.isdigit() and int(tok) < len(cur) else None)\n        if cur is None: return False\n    return isinstance(cur, (dict, bool))","typeGuard":null,"tryCatchPattern":"try:\n    build_model(schema)\nexcept ValueError as e:\n    if \"does not target a schema\" in str(e):\n        schema = retarget_or_wrap_ref_target(schema)","preventionTips":["Keep constants/enums out of definitions, or wrap them in {\"enum\": [...]}","Unit-test that every $ref resolves to a dict or boolean","Generate refs programmatically from the target's location"],"tags":["json-schema","ref-resolution","malformed-schema"],"backgroundTag":"unresolvable-json-schema-ref","analyzedSha":"64b1b85502b1beeb2379e6c9e8bf1104504fa637","analyzedAt":"2026-08-28T15:39:33.623Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}