apache/beam · error · IllegalArgumentException

Array schema is not properly formatted or unsupported ({}).

Error message

Array schema is not properly formatted or unsupported ({}). Note that JSON-schema's tuple-like arrays are not supported by Beam.

What it means

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.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/JsonUtils.java:298

  private static Schema.FieldType beamTypeFromJsonSchemaType(
      org.everit.json.schema.Schema propertySchema) {
    if (propertySchema instanceof org.everit.json.schema.ObjectSchema) {
      return Schema.FieldType.row(beamSchemaFromJsonSchema((ObjectSchema) propertySchema));
    } else if (propertySchema instanceof org.everit.json.schema.BooleanSchema) {
      return Schema.FieldType.BOOLEAN;
    } else if (propertySchema instanceof org.everit.json.schema.NumberSchema) {
      return ((NumberSchema) propertySchema).requiresInteger()
          ? Schema.FieldType.INT64
          : Schema.FieldType.DOUBLE;
    } else if (propertySchema instanceof org.everit.json.schema.StringSchema) {
      return Schema.FieldType.STRING;
    } else if (propertySchema instanceof org.everit.json.schema.ReferenceSchema) {
      org.everit.json.schema.Schema sch = ((ReferenceSchema) propertySchema).getReferredSchema();
      return beamTypeFromJsonSchemaType(sch);
    } else if (propertySchema instanceof org.everit.json.schema.ArraySchema) {
      if (((ArraySchema) propertySchema).getAllItemSchema() == null) {
        throw new IllegalArgumentException(
            "Array schema is not properly formatted or unsupported ("
                + propertySchema
                + "). Note that JSON-schema's tuple-like arrays are not supported by Beam.");
      }
      return Schema.FieldType.array(
          beamTypeFromJsonSchemaType(((ArraySchema) propertySchema).getAllItemSchema()));
    } else {
      throw new IllegalArgumentException("Unsupported schema type: " + propertySchema.getClass());
    }
  }

  private static org.everit.json.schema.ObjectSchema jsonSchemaFromString(String jsonSchema) {
    JSONObject parsedSchema = new JSONObject(jsonSchema);
    org.everit.json.schema.Schema schemaValidator =
        org.everit.json.schema.loader.SchemaLoader.load(parsedSchema);
    if (!(schemaValidator instanceof ObjectSchema)) {
      throw new IllegalArgumentException(
          String.format("The schema is not a valid object schema:%n %s", jsonSchema));

View on GitHub (pinned to 12126d8942)

Solutions

1. Replace tuple-style "items":[...] with a single item schema (e.g. "items":{"type":"string"}) or use one uniform element type
2. Always declare 'items' for array properties
3. If heterogeneous elements are needed, model the field as a Beam row (object schema) with named fields instead of a positional array

Example fix

// before
{"points":{"type":"array","items":[{"type":"number"},{"type":"number"}]}}
// after
{"points":{"type":"array","items":{"type":"number"}}}

static void validateArraySchemas(JSONObject schema) {
  JSONObject props = schema.optJSONObject("properties");
  if (props == null) return;
  for (String key : props.keySet()) {
    JSONObject p = props.optJSONObject(key);
    if (p != null && "array".equals(p.optString("type"))) {
      Object items = p.opt("items");
      if (!(items instanceof JSONObject))
        throw new IllegalArgumentException("Field '" + key + "': tuple-like arrays unsupported by Beam");
    }
  }
}

static boolean beamCompatibleArray(JSONObject propertySchema) {
  return !"array".equals(propertySchema.optString("type"))
      || propertySchema.opt("items") instanceof JSONObject;
}

try {
  Schema s = JsonUtils.beamSchemaFromJsonSchema(jsonSchema);
} catch (IllegalArgumentException e) {
  throw new SchemaParseException("Array field incompatible with Beam (tuple arrays not supported): " + e.getMessage(), e);
}

When it happens

Trigger: beamSchemaFromJsonSchema/addPropertySchemaToBeamSchema encountering an ArraySchema whose getAllItemSchema() is null — i.e. tuple-style arrays like "items":[{...},{...}] or arrays without an items definition.

Common situations: Using JSON-Schema tuple arrays (positional elements) in schemas fed to Beam; arrays declared without an 'items' keyword.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Tuple-like arrays are unsupported. Expected a single item ty
• Unsupported Beam to JSON type: {}
• Unable to parse schema {}
• Unsupported field type {} in field {}
• We currently only support wildcards at terminal parts of sel

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/018687ffe9e10a7d. Report an issue: GitHub.