Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Merge pull request #815 from zerok/tickets/11971

Fixed #11971 -- Documented the serialization formats
  • Loading branch information...
commit b6aede326803bfdf18f932ec2fa8b9304467d29f 2 parents f56ca3f + 5612f54
@aaugustin aaugustin authored
Showing with 91 additions and 5 deletions.
  1. +91 −5 docs/topics/serialization.txt
View
96 docs/topics/serialization.txt
@@ -162,11 +162,82 @@ Identifier Information
.. _json: http://json.org/
.. _PyYAML: http://www.pyyaml.org/
-Notes for specific serialization formats
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+XML
+~~~
+
+The basic XML serialization format is quite simple::
+
+ <?xml version="1.0" encoding="utf-8"?>
+ <django-objects version="1.0">
+ <object pk="123" model="sessions.session">
+ <field type="DateTimeField" name="expire_date">2013-01-16T08:16:59.844560+00:00</field>
+ <!-- ... -->
+ </object>
+ </django-objects>
+
+The whole collection of objects that is either serialized or de-serialized is
+represented by a ``<django-objects>``-tag which contains multiple
+``<object>``-elements. Each such object has two attributes: "pk" and "model",
+the latter being represented by the name of the app ("sessions") and the
+lowercase name of the model ("session") separated by a dot.
+
+Each field of the object is serialized as a ``<field>``-element sporting the
+fields "type" and "name". The text content of the element represents the value
+that should be stored.
+
+Foreign keys and other relational fields are treated a little bit differently::
+
+ <object pk="27" model="auth.permission">
+ <!-- ... -->
+ <field to="contenttypes.contenttype" name="content_type" rel="ManyToOneRel">9</field>
+ <!-- ... -->
+ </object>
+
+In this example we specify that the auth.Permission object with the PK 24 has
+a foreign key to the contenttypes.ContentType instance with the PK 9.
+
+ManyToMany-relations are exported for the model that binds them. For instance,
+the auth.User model has such a relation to the auth.Permission model::
+
+ <object pk="1" model="auth.user">
+ <!-- ... -->
+ <field to="auth.permission" name="user_permissions" rel="ManyToManyRel">
+ <object pk="46"></object>
+ <object pk="47"></object>
+ </field>
+ </object>
+
+This example links the given user with the permission models with PKs 46 and 47.
+
+JSON
+~~~~
+
+When staying with the same example data as before it would be serialized as
+JSON in the following way::
+
+ [
+ {
+ "pk": "4b678b301dfd8a4e0dad910de3ae245b",
+ "model": "sessions.session",
+ "fields": {
+ "expire_date": "2013-01-16T08:16:59.844Z",
+ ...
+ }
+ }
+ ]
+
+The formatting here is a bit simpler than with XML. The whole collection
+is just represented as an array and the objects are represented by JSON objects
+with three properties: "pk", "model" and "fields". "fields" is again an object
+containing each field's name and value as property and property-value
+respectively.
+
+Foreign keys just have the PK of the linked object as property value.
+ManyToMany-relations are serialized for the model that defines them and are
+represented as a list of PKs.
-json
-^^^^
+Date and datetime related types are treated in a special way by the JSON
+serializer to make the format compatible with `ECMA-262`_.
Be aware that not all Django output can be passed unmodified to :mod:`json`.
In particular, :ref:`lazy translation objects <lazy-translations>` need a
@@ -175,14 +246,29 @@ In particular, :ref:`lazy translation objects <lazy-translations>` need a
import json
from django.utils.functional import Promise
from django.utils.encoding import force_text
+ from django.core.serializers.json import DjangoJSONEncoder
- class LazyEncoder(json.JSONEncoder):
+ class LazyEncoder(DjangoJSONEncoder):
def default(self, obj):
if isinstance(obj, Promise):
return force_text(obj)
return super(LazyEncoder, self).default(obj)
.. _special encoder: http://docs.python.org/library/json.html#encoders-and-decoders
+.. _ecma-262: http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15
+
+YAML
+~~~~
+
+YAML serialization looks quite similar to JSON. The object list is serialized
+as a sequence mappings with the keys "pk", "model" and "fields". Each field is
+again a mapping with the key being name of the field and the value the value::
+
+ - fields: {expire_date: !!timestamp '2013-01-16 08:16:59.844560+00:00'}
+ model: sessions.session
+ pk: 4b678b301dfd8a4e0dad910de3ae245b
+
+Referential fields are again just represented by the PK or sequence of PKs.
.. _topics-serialization-natural-keys:

0 comments on commit b6aede3

Please sign in to comment.
Something went wrong with that request. Please try again.