Schema guide¶
django-jsonform currently implements a custom JSON Schema spec written specifically for Django.
You should also read the standard spec at https://json-schema.org.
At present, certain features from the standard spec are not supported by django-jsonform. However, we’ve also implemented a few extra features which are not in the standard spec.
For some complex schema examples, see Examples page.
Types¶
Currently, only these six types are supported:
array
(alias list
)¶
A JSON array (similar to Python list).
Keywords:
items
(required) - Specifies the type of items allowed in the list.minItems
(aliasmin_items
) - Limit the minimum number of items in a list.maxItems
(aliasmax_items
) - Limit the maximum number of items in a list.title
- Specify a title for the list.default
- A list containing all the default initial values for the array.
Changed in version 2.8: Support for setting initial array data using default
keyword was added.
This example shows a schema of a list containing string items:
# Schema
{
'type': 'list', # or 'array'
'items': {
'type': 'string',
'default': 'Hello', # default value for new items
'readonly': True, # make all items readonly
},
'min_items': 1,
'max_items': 5,
'default': ['One', 'Two', 'Three'], # initial value for the whole list
}
# Output data
['one', 'two', 'three', ...]
object
(alias dict
)¶
A JSON object (similar to Python dict).
Keywords:
properties
(aliaskeys
; required) - Specifies the keys (or fields) in a dict/object.additionalProperties
- Allow users to add extra keys not delclared in the schema.title
- Specify a title for the dict.
This example shows a schema of a basic dict:
# Schema
{
'type': 'dict': # or 'object'
'keys': { # or 'properties'
'name': {
'type': 'string'
},
'email': {
'type': 'string'
},
'age': {
'type': 'number',
'title': 'Age in years',
'default': 50, # default value for age
'readonly': True, # make it readonly
}
}
}
# Output data
{
'name': 'John Doe',
'email': 'john@example.com',
'age': 99
}
Additional keys¶
By default, an object’s data can only contain keys declared in the schema.
But you can allow users to add extra keys using the additionalProperties
key:
# Schema
{
'type': 'dict': # or 'object'
'keys': { # or 'properties'
'name': {
'type': 'string'
},
},
'additionalProperties': True
}
# Output data
{
'name': 'John Doe', # declared in the schema
'gender': 'Male', # added by the user
}
The keys added by the user will only be of string
type.
string
¶
A string.
This can’t be at the top level of the schema. If you only want to save
a string, you should use Django’s CharField
.
Keywords:
title
- Specify the label for the input field.choices
- Specify choices for the field. Aselect
input will be rendered. See the document on Choices for details.format
- Use this to specify the input field type. See Inputs for string type for more.widget
- Use this to specify the input field type, such as a textarea. For most use cases, prefer theformat
keyword.default
- Specify a default value for this input field.readonly
(aliasreadOnly
) - Make this input field readonly
Changed in version 2.6: Support for default
and readonly
keywords was added.
number
¶
A number (including floats).
This can’t be at the top level of the schema. If you only want to save a number,
you should use Django’s FloatField
.
Keywords:
title
- Specify the label for the input field.choices
- Specify choices for the field. Aselect
input will be rendered. See the document on Choices for details.default
- Specify a default value for this input field. The value must be of numerical type.readonly
(aliasreadOnly
) - Make this input field readonly
It gets a number
HTML input by default. It can’t be overriden.
Changed in version 2.6: Support for default
and readonly
keywords was added.
integer
¶
An integer.
This can’t be at the top level of the schema. If you only want to save an integer,
you should use Django’s IntegerField
.
Keywords:
title
- Specify the label for the input field.choices
- Specify choices for the field. Aselect
input will be rendered. See the document on Choices for details.default
- Specify a default value for this input field. The value must be an integer.readonly
(aliasreadOnly
) - Make this input field readonly
It gets a number
HTML input by default. It can’t be overriden.
Changed in version 2.6: Support for default
and readonly
keywords was added.
boolean
¶
A boolean.
This can’t be at the top level of the schema. If you only want to save an boolean,
you should use Django’s BooleanField
.
Keywords:
title
- Specify the label for the input field.default
- Specify a default value for this input field. Must be a boolean.readonly
(aliasreadOnly
) - Make this input field readonly
It gets a checkbox
HTML input by default. It can’t be overriden.
Changed in version 2.6: Support for default
and readonly
keywords was added.
Unsupported features¶
Recursion and validation are the two major features which are not supported at present.