marshmallow-jsonschema

Releases

1. ▸▾0.16.026 Apr 2026

   Polymorphic schema support (marshmallow_oneofschema.OneOfSchema), top-level array envelopes, by-value string enums, and a handful of correctness fixes

   Polymorphic schema support (marshmallow_oneofschema.OneOfSchema), top-level array envelopes, by-value string enums, and a handful of correctness fixes from the issue backlog. All changes are additive or bug fixes; one behavior change in how fields.Raw is emitted (see Backward compatibility). Python 3.9+, marshmallow 3.13+ / marshmallow 4 requirements unchanged.

   New:
   - Support `marshmallow_oneofschema.OneOfSchema`. Dumping a
     `OneOfSchema` (or a `Nested(SomeOneOfSchema)`) emits a JSON
     Schema `oneOf` over each variant, with the discriminator field
     pinned to its `const` value. The generated schema actually
     validates the wire format that `OneOfSchema.dump()` produces -
     regression-tested via `jsonschema.validate(...)`. Honors
     `many=True`, custom `type_field`, and the OneOfSchema's own
     `Meta.title` / `Meta.description`. Empty `type_schemas`,
     discriminator-name collisions, and recursive variants raise
     `UnsupportedValueError` with fix-it messages instead of
     producing broken schemas. Optional install via
     `pip install marshmallow-jsonschema[oneofschema]`. (#141, #205)
   - `Schema(many=True)` at the document root now emits a Draft-7
     array envelope (`{"type": "array", "items": {"$ref": ...}}`)
     instead of a single-instance schema. Previously consumers had
     to post-process the output to describe a list. (#92, #204)
   - `marshmallow.fields.Enum(MyEnum, by_value=True)` is supported
     when every member's value is a string - the common
     `class MyEnum(str, Enum)` pattern. Mixed-type or non-string
     enum values continue to raise `NotImplementedError`. The same
     handling is applied to `marshmallow_enum.EnumField` configured
     with `LoadDumpOptions.value`. (#156, #204)
   
   Fixes:
   - `fields.Raw` now emits a schema with no `type` constraint, so
     the dumped schema actually accepts the "any value" wire format
     the field describes. Previously routed through `str` and emitted
     `type: string`, which silently rejected dicts, lists, numbers,
     etc. on the consumer side. See Backward compatibility below.
     (#120, #206)
   - `Schema(partial=True)` and `Schema(partial=("name1", "name2"))`
     are now honored when computing the `required` list - previously
     the partial setting was ignored and required fields were always
     emitted. (#112, #202)
   - `UnsupportedValueError` raised for an unmappable custom field
     now points the user at the fix: subclass an existing field type,
     or add a `_jsonschema_type_mapping` method. (#157, #203)
   - README build-status badge fixed (was pointing at the old Travis
     CI URL).
   
   Backward compatibility:
   - `fields.Raw` output changed from `{"type": "string"}` to a
     type-less schema. Anyone relying on the previous shape was
     already getting incorrect validation - the field accepts any
     JSON value but the schema only allowed strings. User subclasses
     of `Raw` (`class CustomRaw(fields.Raw): ...`) still flow through
     the existing `_get_python_type` path and emit `{"type":
     "string"}` for backwards compatibility; only the literal
     `fields.Raw` type is special-cased.
   
   
   Feature batch from the open-PR backlog plus marshmallow 4 support.
   All changes are additive or bug fixes; no public API removed or
   renamed. Python 3.9+ requirement unchanged. The `marshmallow<4` upper
   bound from 0.14.0 is dropped - this release works on both
   marshmallow 3 (>=3.13) and marshmallow 4.
   
   marshmallow 4 support:
   - Drop the `from marshmallow.utils import _Missing` import (the
     symbol is gone in m4); derive it from `type(missing)` instead.
   - Read marshmallow's version via `importlib.metadata` rather than
     `marshmallow.__version__` (also gone in m4).
   - When dumping a `Nested` schema, pass `context=obj.context` only
     when both attributes exist - m4 removed `Schema.context` and the
     `context=` constructor kwarg in favor of `contextvars.ContextVar`.
   - Expose `MARSHMALLOW_MAJOR` from `marshmallow_jsonschema.base` for
     consumers that need to branch on the installed version.
   - New cross-version test suite `tests/test_marshmallow_compat.py`
     asserts identical JSON Schema output on both major
     versions for the patterns we care about: scalars, defaults,
     metadata, `dump_only`, `allow_none`, recursive nesting,
     `data_key` rewriting, every validator handler, native Enum,
     `INCLUDE/EXCLUDE/RAISE`, schema-level Meta options, and an
     end-to-end `jsonschema.validate(...)` round-trip.
   - CI matrix now tests Python 3.9-3.13 against both marshmallow 3
     and marshmallow 4 separately.
   
   New:
   - Emit schema-level `title` and `description` from `class Meta`.
     Non-string values raise `UnsupportedValueError`. (#41, #99)
   - Add `definitions_path` constructor kwarg (default `"definitions"`)
     so subclasses can rename the JSON pointer segment used for nested
     schema refs. Must be a single segment - multi-segment paths are
     rejected because they'd produce a flat dict key rather than the
     nested structure consumers expect. Propagates to nested schemas.
     (#179)
   - Honor `allow_none=True` on `Nested` fields: emits
     `anyOf: [<nested>, {"type": "null"}]`. (#101, #121, #122)
   - Apply `metadata={...}` and `dump_default` to fields that expose a
     `_jsonschema_type_mapping`. Previously dropped silently. (#21)
   - A custom field's `_jsonschema_type_mapping` can now optionally
     accept `(json_schema, obj)` extra parameters to re-enter the
     dumping machinery - useful for wrapper-style fields that need to
     emit a `$ref` to a recursive schema. Zero-arg implementations
     continue to work. (#165)
   - Add a `ContainsOnly` validator handler: a `List` field with
     `validate=ContainsOnly([...])` emits `items.anyOf: [{const}, ...]`
     and `uniqueItems: true`. (#96)
   - Add support for three more field types that previously raised
     `UnsupportedValueError`:
       * `fields.Tuple` - emits Draft-7 positional `items` plus
         `min/maxItems` so wrong-arity inputs are rejected. (#162)
       * `fields.Constant` - emits `const` plus a matching `type`
         when the constant maps cleanly. (#115)
       * `fields.Pluck` - emits the picked field's schema directly
         instead of a `$ref` to the whole nested definition; honors
         `many=True` by wrapping in a `type: array` envelope.
   
   Typing:
   - Ship a PEP 561 `py.typed` marker so downstream pyright / mypy
     users actually see this package's type annotations. Without it
     every annotation we have was being silently dropped at the
     consumer's type checker.
   - Narrow `JSONSchema.dump()`'s return type from `dict | list | None`
     (inherited from `Schema.dump`) to `Dict[str, Any]`. The wrap
     step always produces a single root dict, so callers no longer
     need to defensively narrow.
   - Add explicit type annotations on the `MARSHMALLOW_MAJOR`,
     `ALLOW_UNIONS`, `ALLOW_MARSHMALLOW_ENUM`, `ALLOW_NATIVE_ENUM`,
     and `ALLOW_ENUMS` module-level constants.
   
   Other fixes:
   - Propagate `props_ordered` from the outer JSONSchema into nested
     schemas. Previously nested fields were always alphabetically
     sorted regardless of the outer `props_ordered=True`. (#109, #129)
   - Fix a duplicate-keyword-argument bug in
     `ReactJsonSchemaFormJSONSchema.dump_with_uischema` and
     `dump_uischema`: the previous signatures interleaved `*args`
     with an explicit `many=` keyword, so passing `many` positionally
     raised `TypeError: got multiple values for keyword argument`.
     Made `many` keyword-only and dropped the unused `*args`.
   - Skip `default` emission when the value isn't JSON-serializable
     (e.g. `dump_default=uuid.uuid4()` passing a UUID instance). The
     old behavior produced a schema dict that crashed downstream
     `json.dumps`. (motivated by #181)
   - The Integer-type regression test from #118 finally landed.
     (The underlying `int -> "integer"` mapping fix shipped in 0.13.0
     via #152; this adds the `jsonschema.validate(...)` assertion that
     guards against future drift.)