marshmallow-jsonapi

0.24.0 · active · verified Fri Apr 17

marshmallow-jsonapi provides JSON:API 1.0 (https://jsonapi.org) formatting capabilities on top of the popular marshmallow serialization/deserialization library. It helps developers create schemas that comply with the JSON:API specification for building REST APIs. The current version is 0.24.0, and it generally follows the release cadence of its core dependency, marshmallow, with releases typically tied to marshmallow updates or bug fixes.

Common errors

```
AttributeError: 'YourSchemaName' object has no attribute 'get_attribute'
```
cause This error often occurs when `marshmallow-jsonapi` cannot determine the resource 'type' for serialization, usually because the `type_` attribute is missing in the `Meta` class of your schema.

fix Add `class Meta: type_ = 'your_resource_name'` to your `marshmallow_jsonapi.Schema` definition.
```
ImportError: cannot import name 'BaseSchema' from 'marshmallow_jsonapi.schemas'
```
cause You are trying to import `BaseSchema`, which was removed in `marshmallow-jsonapi` version 0.20.0. Your environment has a newer version installed.

fix Change your import statement from `from marshmallow_jsonapi.schemas import BaseSchema` to `from marshmallow_jsonapi import Schema`. All schemas should now inherit from this `Schema` class.
```
TypeError: __init__ got an unexpected keyword argument 'strict'
```
cause The `strict` keyword argument for schemas was removed in `marshmallow` version 3. If you have `marshmallow-jsonapi` with `marshmallow` v3 installed, using `strict=True` will cause this error.

fix Remove `strict=True` from your `Schema`'s `Meta` class. `marshmallow` v3 is strict by default.

Warnings

breaking The `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`.
Fix: Update your schema definitions to inherit from `from marshmallow_jsonapi import Schema` instead of `BaseSchema`.
gotcha Failing 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.
Fix: Always include `class Meta: type_ = 'your_resource_name'` in your `marshmallow_jsonapi.Schema` definitions.
breaking Compatibility 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`.
Fix: Ensure 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.
gotcha The `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`.
Fix: For 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.

Install

pip install marshmallow-jsonapi Install stable version

Imports

Schema
wrong:
```
from marshmallow_jsonapi.schemas import BaseSchema
```
correct:
```
from marshmallow_jsonapi import Schema
```
`BaseSchema` was deprecated and removed in favor of `Schema` from `marshmallow-jsonapi` version 0.20.0 onwards.
Relationship
```
from marshmallow_jsonapi.fields import Relationship
```
Used specifically for defining JSON:API relationship fields within a schema.
fields
```
from marshmallow import fields
```
Standard marshmallow fields are used for attribute definition, not marshmallow_jsonapi.fields (except for Relationship).

Quickstart

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)

view raw JSON →