Schema class in Ninja defines how to group typed fields together into serializable objects. The
ModelSchema class allows for the definition of a
Schema based on an existing Django ORM object, minimizing the amount of code necessary to serialize your database objects.
Serialization Through Schema and ModelSchema Classes
In the previous lesson, I showed you how arguments are handled in Ninja. In this lesson, I’ll dive into serialization with
00:11 So far, you’ve seen strings turned into JSON strings. Exciting it may be, but in the real world, you’re typically going to have to turn data into JSON objects.
00:21 This process is called serialization. Ninja is built on top of a serialization library called Pydantic. Pydantic uses the type annotation features of Python to describe objects, which it calls models.
This can be a bit confusing in the Django world, as Django already has something called a model. To get around this, Ninja renames Pydantic models as schemas. A
Schema is a Python class used to describe some fields with type information.
This is very similar to Django ORM models. When an API needs to respond with some data, it uses a
Schema to describe the payload.
To play with some data, I’ll need some data. So another lesson, another Django app. This time, I’ll be playing with dragon fire. The data in question will be a
Person. The model for it is on the screen here.
It can also be found in the sample code if you want to just grab it. If you’re coding along with me, you’ll need to create a
targaryen Django app, add the
Person class in the
models file, and of course, register all this stuff … so, add it to installed apps in your settings, register an API route, and of course, because you’re adding a model, you’ll need to do migrations as well.
Inside of my
targaryen app, I’ve created
schemas.py. Ninja doesn’t care where you create this, and if you’re only doing a little bit, sticking your schemas in
models.py actually makes a little more sense. But for larger projects, you may want to organize your schemas together, like I’ve done here.
My first schema has nothing to do with the
Person model. I’ll come back to those later. I’ve defined something called
This is a schema containing two fields:
birth_year. The type annotations indicate what type of data will be in those two fields.
I named this
DragonOut out of habit. Quite commonly in APIs, you’re going to need to have data coming in from a POST and going out from a GET.
Most of the time, this will be describing the same kind of object, but usually will contain different fields. Stuff going out has an ID field, whereas stuff you’re creating, something new, typically doesn’t have an ID field. One way of handling this is to use two different serialization classes, one for
In and one for
02:51 This is the pattern used in most of Ninja’s documentation, so I’ve stuck with it.
Inside of the
targaryen API file, I’ve defined the
dragons view. I tell the
dragons view what I want to return by setting the response parameter in the GET decorator.
As this is going to return a list of
DragonOut objects, the response type is set to
list[DragonOut]. Inside of the view, I can create an instance of a
DragonOut data object, or like I’ve done here, three of them.
03:27 I then return that list, and Ninja takes care the rest.
And taking a look at the
curl output, you see the resulting JSON, a list with three serialized objects.
03:54 Since Ninja is a library for Django, the most likely thing you’re going to need to serialize is Django ORM models. As an ORM model already has type information inside of it, Ninja can do most of the work for you.
ModelSchema class works a lot like a form object in Django. You inherit from the base class. Then in a subclass, you indicate what ORM model to serialize. In this case, I’m serializing the
targaryen Person model.
model_fields attribute indicates which of the fields from
Person I’m going to include in the output. In addition to using fields from
Person, you can also add new ones simply by declaring them.
I’ve declared the
full_name attribute and then created a magical little method called
.resolve_full_name(). Ninja automatically looks for static methods that start with
resolve and will use them to populate a field. A
resolve method takes an object as an argument, the thing being serialized, and then it returns the value of the field in question. Here, I’ve created
full_name by combining the name and title of the
Person object into a single string.
That’s why I didn’t include
"title" in the
Now inside of the API endpoint, I declare that I’m returning a
PersonOut as a response, then return a
Person object. Ninja takes the
Person ORM object, uses the
PersonOut ModelSchema and serializes it all into JSON. Note that what I’ve done here isn’t the best coding practice.
05:37 If an ID is given that doesn’t correspond to a person, you’ll get a 500 error. Better practice is to kick out a 404, but I’ll show you that later. Let’s take a look at the call …
05:59 and there you go. One serialized Stormborn lady, which of course I had created in the database earlier using the admin.
If you want to take advantage of the serialization feature, but you’re not in a view, you can get at it directly from the
Let me show you an example copied from Django’s REPL. I got there by running the
manage shell command, imported a
Person, then import the corresponding schema.
Now I’ll query a
Person from a previously loaded fixture, and then I use the
.from_orm() method of the
PersonOut object to turn my person into a data object. Here’s the result.
I can use the
.dict() method to see the serialization as a Python dictionary or the
.json() method to see it as a JSON string.
06:55 You’ve got all the pieces you need now to build a proper API. Next up, I’ll show you a typical CRUD use case where you create, read, update, and delete your data.
I wish I knew an easy answer for you. I haven’t done this myself. I took a quick look through the docs and couldn’t find an example that matched yours. Ninja is built on top of Pydantic, so I took a look through theirs as well, and it implies it might be able to be done, but the examples provided are single nesting like you’ve seen.
A few things you might try:
- Add another layer of indirection: have a CategoryListingSchema which is built on a list of Categories.
- Check the Pydantic documentation in detail to see if their “list” types can solve your problem
- Post to the Ninja guys posing the question (django-ninja.rest-framework.com/help/). The one time I had a question they were pretty responsive.
Sorry I couldn’t be more help. If you figure it out, post back here in case others have the same question.
Thank you Christopher. I will do some more research.
I have one following question if you don’t mind. Apart from nesting, is there any other obvious way to use multiple schemas in a single response? So, 200 would return both product ProductSchema and CategorySchema regardles if one is nested in the other?
Your sample code is using ModelSchemas, which are actually shortcuts so you don’t have to write as much code when your Schema maps to a Django Model nicely. There is also a more basic component called just a Schema (it’s been a while since I wrote this course I can’t recall whether I cover it or not).
With a regular Schema you can build whatever you like, including multiple model references. It just means more work. There is also a mechanism called a resolver function that allows you to write a function in a schema that dictates how a field is populated, so you can do some very fine grained control.
I’m a big fan of Ninja, it does the common stuff quickly and well. The Django REST Framework (DRF) is far more comprehensive though, so if you’re finding you’re hitting limitations of what you’re trying to accomplish, the DRF might be a better fit for you. Much more coding there though.
There is a course on the DRF as well, as long as you’re not tired of listening to me talk :)
Chris, I’ve done your DRF first and I believe you directed me to Ninja which seems far better suited to my needs. Thanks for that!
The problem is now solved. Nesting a list of schemas requires just two steps. Correct declaration in Schema is, in my case:
category: List[CategorySchema] =  Second step is in the api function, I had to convert the queryset to a list of dicts with
categories = [category.__dict__ for category in categories] before passing it to the response as otherwise I received
value is not a valid list (type=type_error.list) error.
Glad it worked out. Post a code snippet if you’ve got a minute, would definitely be helpful to others trying to accomplish the same thing. …ct
Become a Member to join the conversation.
TomDevUK on April 28, 2023
Hi, I may be missing something very obvious but I’m struggling with nested schema in Django Ninja. Let’s consider 2 models:
Ninja documentation shows only one nested example, applied to my models, it would look something like that:
The issue I have is that it only works if there is one unique category. I tried to change it to
category = List[CategorySchema]but it doesn’t work. What am I missing? How to write a Schema that will return list of nested objects within an object?