What causes "The schema is not a valid object schema:%n %s" in apache/beam?

Make the top-level JSON Schema an object schema: {"type": "object", "properties": {...}}.

apache/beam · error · IllegalArgumentException

The schema is not a valid object schema:%n

Error message

The schema is not a valid object schema:%n %s

What it means

jsonSchemaFromString loads a JSON Schema document via org.everit.json.schema SchemaLoader and requires the result to be an ObjectSchema (a top-level 'type': 'object' schema), because JsonUtils builds Beam Rows from object schemas. If the loaded schema is any other type (string, array, boolean, number schema), it throws this IllegalArgumentException containing the offending schema text.

Solutions

Make the top-level JSON Schema an object schema: {"type": "object", "properties": {...}}.
If your data is an array of records, define the element schema as the object schema and let JsonUtils handle the array wrapper (jsonRowsToRows expects a top-level array of objects matching this schema).
Verify the schema parses as an object by loading it with org.everit.json.schema.loader.SchemaLoader yourself before calling JsonUtils.

Example fix

// before
String schema = "{\"type\": \"array\", \"items\": {\"type\": \"object\", ...}}";
// after
String schema = "{\"type\": \"object\", \"properties\": {\"id\": {\"type\": \"integer\"}}}";

Defensive patterns

Strategy: validation

Validate before calling

org.everit.json.schema.Schema loaded =
    org.everit.json.schema.loader.SchemaLoader.load(new JSONObject(jsonSchemaString));
if (!(loaded instanceof org.everit.json.schema.ObjectSchema)) {
  throw new IllegalArgumentException("Top-level schema must be {\"type\": \"object\", ...}");
}

Try / catch

try {
  JsonUtils.jsonSchema(jsonSchemaString);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("not a valid object schema")) {
    // wrap the schema: {"type":"object","properties":{"value": <original>}}
  } else throw e;
}

Prevention

Always define the record schema itself at the top level, not the array or the value schema.
Unit-test schema strings with SchemaLoader before wiring them into pipelines.
Keep schema fragments in 'definitions' and reference them inside a top-level object schema.

When it happens

Trigger: Calling JsonUtils.jsonSchema(jsonSchema) / JsonUtils.jsonRowsToRows with a top-level schema like {"type": "string"}, {"type": "array", ...}, or a bare true/false schema; the loaded validator is not an ObjectSchema.

Common situations: Users pass a schema describing individual values rather than records, accidentally nest the object definition under 'properties' or 'definitions' at the wrong level, or copy a schema fragment instead of the whole object schema.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

      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));
    }
    return (org.everit.json.schema.ObjectSchema) schemaValidator;
  }

  private abstract static class JsonToRowFn<T> extends SimpleFunction<T, Row> {
    final RowJson.RowJsonDeserializer deserializer;
    final ObjectMapper objectMapper;

    private JsonToRowFn(Schema beamSchema) {
      deserializer = RowJson.RowJsonDeserializer.forSchema(beamSchema);
      objectMapper = RowJsonUtils.newObjectMapperWith(deserializer);
    }
  }

  private abstract static class RowToJsonFn<T> extends SimpleFunction<Row, T> {
    final RowJson.RowJsonSerializer serializer;
    final ObjectMapper objectMapper;

View on GitHub (pinned to 12126d8942)