{"id":9919,"library":"marshmallow-jsonapi","title":"marshmallow-jsonapi","description":"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.","status":"active","version":"0.24.0","language":"en","source_language":"en","source_url":"https://github.com/marshmallow-code/marshmallow-jsonapi","tags":["serialization","deserialization","jsonapi","api","rest","marshmallow"],"install":[{"cmd":"pip install marshmallow-jsonapi","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core serialization library; marshmallow-jsonapi builds directly upon it. Requires marshmallow>=3.0.0.","package":"marshmallow"}],"imports":[{"note":"`BaseSchema` was deprecated and removed in favor of `Schema` from `marshmallow-jsonapi` version 0.20.0 onwards.","wrong":"from marshmallow_jsonapi.schemas import BaseSchema","symbol":"Schema","correct":"from marshmallow_jsonapi import Schema"},{"note":"Used specifically for defining JSON:API relationship fields within a schema.","symbol":"Relationship","correct":"from marshmallow_jsonapi.fields import Relationship"},{"note":"Standard marshmallow fields are used for attribute definition, not marshmallow_jsonapi.fields (except for Relationship).","symbol":"fields","correct":"from marshmallow import fields"}],"quickstart":{"code":"import datetime as dt\nfrom marshmallow import fields\nfrom marshmallow_jsonapi import Schema\n\n\nclass AuthorSchema(Schema):\n    id = fields.Str(dump_only=True)\n    first_name = fields.Str(required=True)\n    last_name = fields.Str(required=True)\n    date_created = fields.DateTime(dump_only=True)\n\n    class Meta:\n        type_ = 'authors'\n        strict = True\n\n\nclass BookSchema(Schema):\n    id = fields.Str(dump_only=True)\n    title = fields.Str(required=True)\n    pages = fields.Int()\n    author = fields.Relationship(\n        related_url='/authors/{author_id}',\n        related_url_kwargs={'author_id': '<author.id>'}, \n        attribute='author', \n        type_='authors'\n    )\n\n    class Meta:\n        type_ = 'books'\n        strict = True\n\n\n# Example Usage\nauthor_data = {\n    'id': '1',\n    'first_name': 'John',\n    'last_name': 'Doe',\n    'date_created': dt.datetime.now()\n}\nauthor_schema = AuthorSchema()\nserialized_author = author_schema.dump(author_data)\nprint('Serialized Author:')\nprint(serialized_author)\n\nbook_data = {\n    'id': '101',\n    'title': 'The Great Book',\n    'pages': 300,\n    'author': author_data # Pass the entire author object for relationship handling\n}\nbook_schema = BookSchema()\nserialized_book = book_schema.dump(book_data)\nprint('\\nSerialized Book:')\nprint(serialized_book)\n","lang":"python","description":"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."},"warnings":[{"fix":"Update your schema definitions to inherit from `from marshmallow_jsonapi import Schema` instead of `BaseSchema`.","message":"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`.","severity":"breaking","affected_versions":"<0.20.0 (BaseSchema used) to >=0.20.0 (BaseSchema removed)"},{"fix":"Always include `class Meta: type_ = 'your_resource_name'` in your `marshmallow_jsonapi.Schema` definitions.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"All versions, depends on marshmallow version"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Add `class Meta: type_ = 'your_resource_name'` to your `marshmallow_jsonapi.Schema` definition.","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.","error":"AttributeError: 'YourSchemaName' object has no attribute 'get_attribute'"},{"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.","cause":"You are trying to import `BaseSchema`, which was removed in `marshmallow-jsonapi` version 0.20.0. Your environment has a newer version installed.","error":"ImportError: cannot import name 'BaseSchema' from 'marshmallow_jsonapi.schemas'"},{"fix":"Remove `strict=True` from your `Schema`'s `Meta` class. `marshmallow` v3 is strict by default.","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.","error":"TypeError: __init__ got an unexpected keyword argument 'strict'"}]}