{"record":{"id":"eaf0186e65a92509","repo":"Tencent/APIJSON","slug":"put-jsonrequest","errorCode":null,"errorMessage":"PUT {}, {}/{} 必须为 JSONRequest {} ！","messagePattern":"PUT (.+?), (.+?)/(.+?) 必须为 JSONRequest (.+?) ！","errorType":"validation","errorClass":"ConflictException","httpStatus":null,"severity":"error","filePath":"APIJSONORM/src/main/java/apijson/orm/AbstractObjectParser.java","lineNumber":759,"sourceCode":"\n\t\t\ttargetArray = JSON.createJSONArray();\n\t\t}\n\n\t\tfor (int i = 0; i < array.size(); i++) {\n\t\t\tObject obj = array.get(i);\n\t\t\tif (obj == null) {\n\t\t\t\tcontinue;\n\t\t\t}\n\n\t\t\tif (isAdd) {\n\t\t\t\tif (targetArray != null) {\n\t\t\t\t\tif (targetArray.contains(obj)) {\n\t\t\t\t\t\tthrow new ConflictException(\"PUT \" + path + \", \" + key + \"/\" + i + \" 已存在！\");\n\t\t\t\t\t}\n\t\t\t\t\ttargetArray.add(obj);\n\t\t\t\t} else {\n\t\t\t\t\tif (obj != null && obj instanceof Map == false) {\n\t\t\t\t\t\tthrow new ConflictException(\"PUT \" + path + \", \" + key + \"/\" + i + \" 必须为 JSONRequest {} ！\");\n\t\t\t\t\t}\n\t\t\t\t\ttargetObj.putAll((Map) obj);\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tif (targetArray != null) {\n\t\t\t\t\tif (targetArray.contains(obj) == false) {\n\t\t\t\t\t\tthrow new NullPointerException(\"PUT \" + path + \", \" + key + \"/\" + i + \" 不存在！\");\n\t\t\t\t\t}\n\t\t\t\t\ttargetArray.remove(obj);\n\t\t\t\t} else {\n\t\t\t\t\tif (obj instanceof String == false) {\n\t\t\t\t\t\tthrow new ConflictException(\"PUT \" + path + \", \" + key + \"/\" + i + \" 必须为 String 类型 ！\");\n\t\t\t\t\t}\n\t\t\t\t\tif (targetObj.containsKey(obj) == false) {\n\t\t\t\t\t\tthrow new NullPointerException(\"PUT \" + path + \", \" + key + \"/\" + i + \" 不存在！\");\n\t\t\t\t\t}\n\t\t\t\t\ttargetObj.remove(obj);\n\t\t\t\t}","sourceCodeStart":741,"sourceCodeEnd":777,"githubUrl":"https://github.com/Tencent/APIJSON/blob/5284052872898eddc449a58f629e5c8d588b8e22/APIJSONORM/src/main/java/apijson/orm/AbstractObjectParser.java#L741-L777","documentation":"When 'key+' targets a JSONObject-valued column, each element of the argument array is merged into the target via putAll, so every element must itself be a Map (JSONRequest {}). If an element is a non-null non-Map (String, number, etc.), ConflictException is thrown with the key and index, telling you the required form 'key+': [{'key': value, ...}].","triggerScenarios":"PUT { \"settings+\": [\"dark\"] } where settings is a JSON object column — the string element cannot be merged into an object. Same for numbers/booleans/arrays as elements.","commonSituations":"Using the same payload shape for object and array columns; switching a column from array to object without updating clients; docs examples copy-pasted across column types.","solutions":["Send object elements: \"settings+\": [{ \"theme\": \"dark\" }] when the column holds a JSONObject.","Determine the column's JSON type first and shape the payload accordingly (array of strings for arrays, array of objects for objects).","For plain key assignment into the object, a single-element array with one merge object is enough."],"exampleFix":"// before (settings column is a JSON object)\n{ \"User\": { \"id\": 1, \"settings+\": [\"dark\"] } }\n// after\n{ \"User\": { \"id\": 1, \"settings+\": [ { \"theme\": \"dark\" } ] } }","handlingStrategy":"type-guard","validationCode":"Object current = fetchColumnValue(tableName, id, key);\nboolean isObj = current instanceof Map;\nfor (Object o : payload) {\n  if (isObj && !(o instanceof Map)) throw new IllegalArgumentException(key + \"+ element must be a JSONRequest {} for object columns\");\n}","typeGuard":"function payloadMatchesColumnType(current: unknown, payload: unknown[]): boolean {\n  const isObj = current !== null && typeof current === 'object' && !Array.isArray(current);\n  return payload.every(p => isObj ? p !== null && typeof p === 'object' && !Array.isArray(p) : true);\n}","tryCatchPattern":null,"preventionTips":["Object columns take 'key+': [{k: v}] merges; array columns take scalars/objects.","Branch payload shape on the column's JSON type.","Centralize key+/key- payload construction in one helper."],"tags":["apijson","put","json-object","type-check","request-syntax"],"backgroundTag":null,"analyzedSha":"5284052872898eddc449a58f629e5c8d588b8e22","analyzedAt":"2026-08-14T15:15:29.577Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}