{"record":{"id":"018687ffe9e10a7d","repo":"apache/beam","slug":"array-schema-is-not-properly-formatted-or-unsupported-note","errorCode":null,"errorMessage":"Array schema is not properly formatted or unsupported ({}). Note that JSON-schema's tuple-like arrays are not supported by Beam.","messagePattern":"Array schema is not properly formatted or unsupported \\((.+?)\\)\\. Note that JSON-schema's tuple-like arrays are not supported by Beam\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/JsonUtils.java","lineNumber":298,"sourceCode":"\n  private static Schema.FieldType beamTypeFromJsonSchemaType(\n      org.everit.json.schema.Schema propertySchema) {\n    if (propertySchema instanceof org.everit.json.schema.ObjectSchema) {\n      return Schema.FieldType.row(beamSchemaFromJsonSchema((ObjectSchema) propertySchema));\n    } else if (propertySchema instanceof org.everit.json.schema.BooleanSchema) {\n      return Schema.FieldType.BOOLEAN;\n    } else if (propertySchema instanceof org.everit.json.schema.NumberSchema) {\n      return ((NumberSchema) propertySchema).requiresInteger()\n          ? Schema.FieldType.INT64\n          : Schema.FieldType.DOUBLE;\n    } else if (propertySchema instanceof org.everit.json.schema.StringSchema) {\n      return Schema.FieldType.STRING;\n    } else if (propertySchema instanceof org.everit.json.schema.ReferenceSchema) {\n      org.everit.json.schema.Schema sch = ((ReferenceSchema) propertySchema).getReferredSchema();\n      return beamTypeFromJsonSchemaType(sch);\n    } else if (propertySchema instanceof org.everit.json.schema.ArraySchema) {\n      if (((ArraySchema) propertySchema).getAllItemSchema() == null) {\n        throw new IllegalArgumentException(\n            \"Array schema is not properly formatted or unsupported (\"\n                + propertySchema\n                + \"). Note that JSON-schema's tuple-like arrays are not supported by Beam.\");\n      }\n      return Schema.FieldType.array(\n          beamTypeFromJsonSchemaType(((ArraySchema) propertySchema).getAllItemSchema()));\n    } else {\n      throw new IllegalArgumentException(\"Unsupported schema type: \" + propertySchema.getClass());\n    }\n  }\n\n  private static org.everit.json.schema.ObjectSchema jsonSchemaFromString(String jsonSchema) {\n    JSONObject parsedSchema = new JSONObject(jsonSchema);\n    org.everit.json.schema.Schema schemaValidator =\n        org.everit.json.schema.loader.SchemaLoader.load(parsedSchema);\n    if (!(schemaValidator instanceof ObjectSchema)) {\n      throw new IllegalArgumentException(\n          String.format(\"The schema is not a valid object schema:%n %s\", jsonSchema));","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/JsonUtils.java#L280-L316","documentation":"JsonUtils.beamTypeFromJsonSchemaType converts a JSON Schema type to a Beam FieldType. For ArraySchema, Beam requires a single item schema (getAllItemSchema()); if the array uses JSON-Schema tuple semantics (items as a list / no single item schema), Beam cannot represent it and this IllegalArgumentException is thrown. The message also fires for any other malformed array schema.","triggerScenarios":"beamSchemaFromJsonSchema/addPropertySchemaToBeamSchema encountering an ArraySchema whose getAllItemSchema() is null — i.e. tuple-style arrays like \"items\":[{...},{...}] or arrays without an items definition.","commonSituations":"Using JSON-Schema tuple arrays (positional elements) in schemas fed to Beam; arrays declared without an 'items' keyword.","solutions":["Replace tuple-style \"items\":[...] with a single item schema (e.g. \"items\":{\"type\":\"string\"}) or use one uniform element type","Always declare 'items' for array properties","If heterogeneous elements are needed, model the field as a Beam row (object schema) with named fields instead of a positional array"],"exampleFix":"// before\n{\"points\":{\"type\":\"array\",\"items\":[{\"type\":\"number\"},{\"type\":\"number\"}]}}\n// after\n{\"points\":{\"type\":\"array\",\"items\":{\"type\":\"number\"}}}","handlingStrategy":"validation","validationCode":"static void validateArraySchemas(JSONObject schema) {\n  JSONObject props = schema.optJSONObject(\"properties\");\n  if (props == null) return;\n  for (String key : props.keySet()) {\n    JSONObject p = props.optJSONObject(key);\n    if (p != null && \"array\".equals(p.optString(\"type\"))) {\n      Object items = p.opt(\"items\");\n      if (!(items instanceof JSONObject))\n        throw new IllegalArgumentException(\"Field '\" + key + \"': tuple-like arrays unsupported by Beam\");\n    }\n  }\n}","typeGuard":"static boolean beamCompatibleArray(JSONObject propertySchema) {\n  return !\"array\".equals(propertySchema.optString(\"type\"))\n      || propertySchema.opt(\"items\") instanceof JSONObject;\n}","tryCatchPattern":"try {\n  Schema s = JsonUtils.beamSchemaFromJsonSchema(jsonSchema);\n} catch (IllegalArgumentException e) {\n  throw new SchemaParseException(\"Array field incompatible with Beam (tuple arrays not supported): \" + e.getMessage(), e);\n}","preventionTips":["Always declare a single 'items' schema for arrays","Avoid positional/tuple arrays in schemas intended for Beam pipelines","Model heterogeneous sequences as rows with named fields","Lint schemas for tuple arrays during CI"],"tags":["java","json-schema","schemas","arrays"],"backgroundTag":"incompatible-source-type","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}