What causes "{}/{}:value 中 value 必须为依赖路径String 或 SQL子查询JSONObject ！" in Tencent/APIJSON?

Use 'key@': "/Path/to/field" for path references, or a subquery object for 'key{}@'.

Tencent/APIJSON · error · IllegalArgumentException

{}/{}:value 中 value 必须为依赖路径String 或 SQL子查询JSONObject ！

Error message

{}/{}:value 中 value 必须为 依赖路径String 或 SQL子查询JSONObject ！

What it means

The 'key@' reference syntax expects its value to be either a String dependency path (e.g. "/User/userId") or a JSONObject SQL subquery. This error is thrown in the else branch when the value is any other type — typically a number, boolean, JSONArray, or null.

Source

Thrown at APIJSONORM/src/main/java/apijson/orm/AbstractObjectParser.java:534

//					//非查询关键词 @key 不影响查询，直接跳过
//					if (isTable && (key.startsWith("@") == false || apijson.JSONMap.TABLE_KEY_LIST.contains(key))) {
//						Log.e(TAG, "onParse  isTable && (key.startsWith(@) == false"
//								+ " || apijson.JSONMap.TABLE_KEY_LIST.contains(key)) >>  return null;");
//						return false;//获取不到就不用再做无效的query了。不考虑 Table:{Table:{}}嵌套
//					} else {
//						Log.d(TAG, "onParse  isTable(table) == false >> return true;");
//						return true;//舍去，对Table无影响
//					}
//				}

				// 直接替换原来的 key@: path 为 key: target
				Log.i(TAG, "onParse    >>  key = replaceKey; value = target;");
				key = replaceKey;
				value = target;
				Log.d(TAG, "onParse key = " + key + "; value = " + value);
			}
			else {
				throw new IllegalArgumentException(path + "/" + key + ":value 中 value 必须为 依赖路径String 或 SQL子查询JSONObject ！");
			}
		}

		if (key.endsWith("()")) {
			if (value instanceof String == false) {
				throw new IllegalArgumentException(path + "/" + key + ":value 中 value 必须为函数String！");
			}

			String k = key.substring(0, key.length() - 2);

			String type; //远程函数比较少用，一般一个Table:{}内用到也就一两个，所以这里用 "-","0","+" 更直观，转用 -1,0,1 对性能提升不大。
			boolean isMinus = k.endsWith("-");
            boolean isPlus = isMinus == false && k.endsWith("+");
			if (isMinus) { //不能封装到functionMap后批量执行，否则会导致非Table内的 key-():function() 在onChildParse后执行！
				type = "-";
				k = k.substring(0, k.length() - 1);
			}
			else if (isPlus) {

View on GitHub (pinned to 5284052872)

Solutions

Use 'key@': "/Path/to/field" for path references, or a subquery object for 'key{}@'.
For plain values just drop the '@': "userId": 123.
For IN conditions use 'key{}': [...] or a 'key{}@' subquery object instead of an array under 'key@'.

Example fix

// before
"Comment": { "userId@": [1, 2] }
// after
"Comment": { "userId{}": [1, 2] }

Defensive patterns

Strategy: type-guard

Validate before calling

Object v = request.get(key + "@");
if (v != null && !(v instanceof String) && !(v instanceof Map)) {
  throw new IllegalArgumentException("key@ value must be a path String or subquery JSONObject");
}

Type guard

function isValidRefValue(v: unknown): boolean {
  return typeof v === 'string' || (v !== null && typeof v === 'object' && !Array.isArray(v));
}

Prevention

Use 'key@' only with "/path/to/field" strings or subquery objects.
For plain values drop the '@'; for IN-lists use 'key{}'.
Lint requests for non-string values under keys ending in '@'.

When it happens

Trigger: "userId@": 123, "userId@": ["a","b"], or "userId@": true inside any table object. Only String values (path references) and Map values (subqueries with key ending in '{}@' handled earlier) are accepted here.

Common situations: Confusing 'key@' (reference/association) with plain 'key' assignment; sending an array expecting IN-behavior (that is 'key{}@' with a subquery, or 'key{}': []); client serializers emitting null for missing values.

Related errors

AI-assisted analysis of Tencent/APIJSON@5284052872 (2026-08-14). Data as JSON: /api/errors/92b96a59444b4780. Report an issue: GitHub.

{}/{}:value 中 value 必须为 依赖路径String 或 SQL子查询JSONObject ！