{"record":{"id":"1b470122e13d8787","repo":"apache/beam","slug":"unable-to-parse-schema","errorCode":null,"errorMessage":"Unable to parse schema {}","messagePattern":"Unable to parse schema (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/JsonUtils.java","lineNumber":218,"sourceCode":"\n  public static Schema beamSchemaFromJsonSchema(String jsonSchemaStr) {\n    org.everit.json.schema.ObjectSchema jsonSchema = jsonSchemaFromString(jsonSchemaStr);\n    return beamSchemaFromJsonSchema(jsonSchema);\n  }\n\n  private static Schema beamSchemaFromJsonSchema(org.everit.json.schema.ObjectSchema jsonSchema) {\n    Schema.Builder beamSchemaBuilder = Schema.builder();\n    Map<String, org.everit.json.schema.Schema> properties =\n        new HashMap<>(jsonSchema.getPropertySchemas());\n    // Properties in a JSON Schema are stored in a Map object and unfortunately don't maintain\n    // order. However, the schema's required properties is a list of property names that is\n    // consistent and is in the same order as when the schema was first created. To create a\n    // consistent Beam Schema from the same JSON schema, we add Schema Fields following this order.\n    // We can guarantee a consistent Beam schema when all JSON properties are required.\n    for (String propertyName : jsonSchema.getRequiredProperties()) {\n      org.everit.json.schema.Schema propertySchema = properties.get(propertyName);\n      if (propertySchema == null) {\n        throw new IllegalArgumentException(\"Unable to parse schema \" + jsonSchema);\n      }\n\n      Boolean isNullable =\n          Boolean.TRUE.equals(propertySchema.getUnprocessedProperties().get(\"nullable\"));\n      beamSchemaBuilder =\n          addPropertySchemaToBeamSchema(\n              propertyName, propertySchema, beamSchemaBuilder, isNullable);\n      // Remove properties we already added.\n      properties.remove(propertyName, propertySchema);\n    }\n\n    // Now we are potentially left with properties that are not required. Add them too.\n    // Note: having more than one non-required properties may result in  inconsistent\n    // Beam schema field orderings.\n    for (Map.Entry<String, org.everit.json.schema.Schema> entry : properties.entrySet()) {\n      String propertyName = entry.getKey();\n      org.everit.json.schema.Schema propertySchema = entry.getValue();\n","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/JsonUtils.java#L200-L236","documentation":"JsonUtils.beamSchemaFromJsonSchema builds a Beam Schema from a JSON Schema. Beam requires a deterministic field ordering, so required properties are processed first from jsonSchema.getRequiredProperties(); if a name listed as required has no corresponding entry in the properties map, this IllegalArgumentException is thrown. The JSON Schema is inconsistent (required references an undefined property).","triggerScenarios":"Parsing a JSON Schema whose 'required' array contains a property name absent from 'properties' — via JsonUtils.beamSchemaFromJsonSchema / fromJsonSchema APIs.","commonSituations":"Hand-written or tool-generated JSON Schemas with a required field listed but never defined; schema evolution where a property was removed from 'properties' but not from 'required'.","solutions":["Remove the undefined name from the JSON Schema's 'required' array, or add a matching 'properties' entry","Validate the JSON Schema (required ⊆ properties) before passing it to Beam","Regenerate the schema from a single source so required and properties stay in sync"],"exampleFix":"// before\n{\"type\":\"object\",\"required\":[\"a\",\"b\"],\"properties\":{\"a\":{\"type\":\"string\"}}}\n// after\n{\"type\":\"object\",\"required\":[\"a\"],\"properties\":{\"a\":{\"type\":\"string\"}}}","handlingStrategy":"validation","validationCode":"static void validateRequiredSubset(JSONObject jsonSchema) {\n  JSONObject props = jsonSchema.getJSONObject(\"properties\");\n  for (Object req : jsonSchema.optJSONArray(\"required\")) {\n    if (!props.has((String) req))\n      throw new IllegalArgumentException(\"required property '\" + req + \"' missing from properties\");\n  }\n}","typeGuard":"static boolean requiredSubsetOfProperties(JSONObject schema) {\n  JSONObject props = schema.optJSONObject(\"properties\");\n  if (props == null) return schema.optJSONArray(\"required\") == null;\n  java.util.stream.StreamSupport.stream(\n      java.util.Spliterators.spliteratorUnknownSize(schema.optJSONArray(\"required\")==null?java.util.Collections.emptyListIterator():schema.optJSONArray(\"required\").iterator(),0),false)\n      .allMatch(r -> props.has((String) r));\n  return true;\n}","tryCatchPattern":"try {\n  Schema s = JsonUtils.beamSchemaFromJsonSchema(jsonSchema);\n} catch (IllegalArgumentException e) {\n  throw new SchemaParseException(\"Invalid JSON Schema (required vs properties mismatch): \" + e.getMessage(), e);\n}","preventionTips":["Keep 'required' and 'properties' synchronized when editing schemas","Run a JSON Schema validator on inputs before conversion","Generate schemas from a single source (e.g. from a Beam Schema) rather than hand-editing"],"tags":["java","json-schema","schemas","validation"],"backgroundTag":"schema-validation-failed","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"}