apache/beam · error · ValueError

Object type must have either properties or…

Error message

Object type must have either properties or additionalProperties, got {json_type}.

What it means

When json_type_to_beam_type sees an object-typed JSON schema, it needs either 'properties' (to build a row type) or 'additionalProperties' (to build a map type). An object schema with neither leaves the Beam mapping undefined, so ValueError is raised listing the offending schema.

Solutions

Declare the nested fields: add a 'properties' mapping to the nested object schema
If the nested value is a string->X map, add "additionalProperties": {"type": ...}
Remove the empty nested object if the field is unused

Example fix

// before
{"type": "object", "properties": {"meta": {"type": "object"}}}
// after
{"type": "object", "properties": {"meta": {"type": "object", "properties": {"created": {"type": "string"}}}}}

Defensive patterns

Strategy: validation

Validate before calling

def assert_object_defined(s):
    if isinstance(s, dict) and s.get('type') == 'object' and 'properties' not in s and 'additionalProperties' not in s:
        raise ValueError(f'Nested object schema {s!r} needs properties or additionalProperties')

Type guard

def is_defined_object(s) -> bool:
    return not (isinstance(s, dict) and s.get('type') == 'object' and 'properties' not in s and 'additionalProperties' not in s)

Try / catch

try:
    beam_type = json_type_to_beam_type(s)
except ValueError as e:
    raise ValueError(f'Undeclared nested object in schema: {e}') from e

Prevention

Declare every nested record's fields explicitly
Use additionalProperties for free-form maps at nested levels
Run schema validation over the whole document, including nested schemas

When it happens

Trigger: A nested schema like {"type": "object"} inside 'properties' with no 'properties' and no 'additionalProperties' key, converted via json_type_to_beam_type (reachable from json_schema_to_beam_schema).

Common situations: Nested record fields left undeclared in hand-written schemas; schema generated from records that were all null/empty; copying an incomplete schema fragment into a pipeline YAML.

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/3bf938525eb82a5c. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/yaml/json_utils.py:107

    return schema_pb2.FieldType(
        atomic_type=JSON_ATOMIC_TYPES_TO_BEAM[type_name])
  elif type_name == 'array':
    return schema_pb2.FieldType(
        array_type=schema_pb2.ArrayType(
            element_type=json_type_to_beam_type(json_type['items'])))
  elif type_name == 'object':
    if 'properties' in json_type:
      return schema_pb2.FieldType(
          row_type=schema_pb2.RowType(
              schema=json_schema_to_beam_schema(json_type)))
    elif 'additionalProperties' in json_type:
      return schema_pb2.FieldType(
          map_type=schema_pb2.MapType(
              key_type=schema_pb2.FieldType(atomic_type=schema_pb2.STRING),
              value_type=json_type_to_beam_type(
                  json_type['additionalProperties'])))
    else:
      raise ValueError(
          f'Object type must have either properties or additionalProperties, '
          f'got {json_type}.')
  else:
    raise ValueError(f'Unable to convert {json_type} to a Beam schema.')


def beam_schema_to_json_schema(
    beam_schema: schema_pb2.Schema) -> dict[str, Any]:
  return {
      'type': 'object',
      'properties': {
          field.name: beam_type_to_json_type(field.type)
          for field in beam_schema.fields
      },
      'additionalProperties': False
  }

View on GitHub (pinned to 12126d8942)