apache/beam · error · ValueError

Prohibited property: '{name}'; perhaps additionalProperties:

Error message

Prohibited property: '{name}'; perhaps additionalProperties: False is missing?

What it means

If the weak schema declares a property that is not present in the strong schema's 'properties', and the strong schema disallows extra properties (additionalProperties falsy), the property is prohibited and this ValueError is raised. The hint suggests the strong schema likely intended to declare additionalProperties: False-based strictness elsewhere or the property should be declared.

Source

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

      if not strong_schema.get('additionalProperties', True):
        raise ValueError('Incompatible types: map vs object')
      _validate_compatible(
          weak_schema['additionalProperties'],
          strong_schema['additionalProperties'])
    for required in strong_schema.get('required', []):
      if required not in weak_schema['properties']:
        raise ValueError(f"Missing or unknown property '{required}'")
    for name, spec in weak_schema.get('properties', {}).items():

      if name in strong_schema['properties']:
        try:
          _validate_compatible(spec, strong_schema['properties'][name])
        except Exception as exn:
          raise ValueError(f"Incompatible schema for '{name}'") from exn
      elif not strong_schema.get('additionalProperties', True):
        # The property is not explicitly in the strong schema, and the strong
        # schema does not allow for extra properties.
        raise ValueError(
            f"Prohibited property: '{name}'; "
            "perhaps additionalProperties: False is missing?")


def row_validator(beam_schema: schema_pb2.Schema,
                  json_schema: dict[str, Any]) -> Callable[[Any], Any]:
  """Returns a callable that will fail on elements not respecting json_schema.
  """
  if not json_schema:
    return lambda x: None

  # Validate that this compiles, but avoid pickling the validator itself.
  _ = jsonschema.validators.validator_for(json_schema)(json_schema)
  _validate_compatible(beam_schema_to_json_schema(beam_schema), json_schema)
  validator = None

  convert = row_to_json(
      schema_pb2.FieldType(row_type=schema_pb2.RowType(schema=beam_schema)))

View on GitHub (pinned to 12126d8942)

Solutions

Add the property to the strong schema's 'properties' with the appropriate type spec.
Set 'additionalProperties': True (or a spec) in the strong schema if extra fields are acceptable.
Remove the extra property from the producing transform's output if it should not exist.
Check for typos: the property may exist under a slightly different name in the strong schema.

Example fix

# before
strong = {'type': 'object', 'properties': {'a': {'type': 'string'}}}
# after
strong = {'type': 'object', 'properties': {'a': {'type': 'string'}, 'extra': {'type': 'integer'}}}

Defensive patterns

Strategy: validation

Validate before calling

def prohibited_props(weak, strong):
    if strong.get('additionalProperties', True):
        return []
    return [n for n in weak.get('properties', {}) if n not in strong.get('properties', {})]
extra = prohibited_props(weak_schema, strong_schema)
assert not extra, f'prohibited: {extra}'

Type guard

def strong_schema_accepts(strong, prop):
    return strong.get('additionalProperties', True) or prop in strong.get('properties', {})

Try / catch

try:
    row_validator(beam_schema, json_schema)
except ValueError as e:
    if str(e).startswith('Prohibited property'):
        log.error('Producer emits undeclared field: %s', e)
    raise

Prevention

Update the strong schema whenever a transform gains a new output field.
Avoid additionalProperties: False unless strict field control is genuinely required.
Run schema compatibility checks in CI on every schema edit.

When it happens

Trigger: row_validator with weak_schema containing property 'x' that strong_schema['properties'] lacks and strong_schema.get('additionalProperties') is False/absent.

Common situations: Producer emits extra fields the strict consumer schema doesn't enumerate; adding a new output field to a transform without updating the validating schema; typos in property names between the two schemas.

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/16fa90937822dd59. Report an issue: GitHub.