Install & Compatibility
Where this runs
tested against v0.24.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.7s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Schema
✓ from marshmallow_jsonapi import Schema
✗ from marshmallow_jsonapi import Schema
This quickstart defines two JSON:API compliant schemas for 'authors' and 'books'. It demonstrates the use of `marshmallow_jsonapi.Schema` for the base schema, standard `marshmallow.fields`, and `marshmallow_jsonapi.fields.Relationship` for defining JSON:API relationships. The crucial `Meta.type_` attribute is set, which is required for JSON:API resource objects. It then serializes example data for both.
import datetime as dt
from marshmallow import fields
from marshmallow_jsonapi import Schema
class AuthorSchema(Schema):
id = fields.Str(dump_only=True)
first_name = fields.Str(required=True)
last_name = fields.Str(required=True)
date_created = fields.DateTime(dump_only=True)
class Meta:
type_ = 'authors'
strict = True
class BookSchema(Schema):
id = fields.Str(dump_only=True)
title = fields.Str(required=True)
pages = fields.Int()
author = fields.Relationship(
related_url='/authors/{author_id}',
related_url_kwargs={'author_id': '<author.id>'},
attribute='author',
type_='authors'
)
class Meta:
type_ = 'books'
strict = True
# Example Usage
author_data = {
'id': '1',
'first_name': 'John',
'last_name': 'Doe',
'date_created': dt.datetime.now()
}
author_schema = AuthorSchema()
serialized_author = author_schema.dump(author_data)
print('Serialized Author:')
print(serialized_author)
book_data = {
'id': '101',
'title': 'The Great Book',
'pages': 300,
'author': author_data # Pass the entire author object for relationship handling
}
book_schema = BookSchema()
serialized_book = book_schema.dump(book_data)
print('\nSerialized Book:')
print(serialized_book)
Debug
Known issues
breakingThe `BaseSchema` class was deprecated and subsequently removed in `marshmallow-jsonapi` version 0.20.0. All JSON:API schemas should now inherit directly from `marshmallow_jsonapi.Schema`.fixUpdate your schema definitions to inherit from `from marshmallow_jsonapi import Schema` instead of `BaseSchema`.
affects: <0.20.0 (BaseSchema used) to >=0.20.0 (BaseSchema removed)
gotchaFailing to define the `type_` attribute within your `Meta` class will lead to serialization errors, as it's a mandatory part of the JSON:API specification for resource objects.fixAlways include `class Meta: type_ = 'your_resource_name'` in your `marshmallow_jsonapi.Schema` definitions.
affects: All versions
breakingCompatibility with `marshmallow` versions: `marshmallow-jsonapi` relies heavily on `marshmallow`. Older versions of `marshmallow-jsonapi` might not be compatible with `marshmallow` v3, leading to import errors or unexpected behavior. Newer versions (e.g., >=0.20.0) generally require `marshmallow>=3.0.0`.fixEnsure your `marshmallow-jsonapi` and `marshmallow` versions are compatible. Check the `install_requires` in `marshmallow-jsonapi`'s `setup.py` or `pyproject.toml` for the exact `marshmallow` version constraint. Upgrade both if necessary.
affects: All versions, depends on marshmallow version
gotchaThe `id` field is handled specially by `marshmallow-jsonapi`. If your client is expected to send `id`s for creation (client-generated IDs), or if you need to expose an `id` that isn't the primary key, you often need to define it explicitly with `fields.Str(dump_only=True)` or handle it carefully in `load_instance`.fixFor client-generated IDs or specific ID handling, explicitly define `id = fields.Str(dump_only=True)` in your schema and ensure your loading/saving logic respects this. For server-generated IDs, it's often omitted from the schema for input and automatically handled on output.
affects: All versions
Upgrade
Version history
0.24.0latest on PyPI · released Dec 27, 2020
Audit
Dependencies
marshmallowrequiredCore serialization library; marshmallow-jsonapi builds directly upon it. Requires marshmallow>=3.0.0.