Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Ticket 11971 -- Documentation of the serialization formats #815

Merged
merged 1 commit into from over 1 year ago

2 participants

Horst Gutmann Aymeric Augustin
Horst Gutmann

This adds a bit of documentation about the serialization formats (YAML, XML, JSON) including some simple examples on how relations are handled.

https://code.djangoproject.com/ticket/11971

Aymeric Augustin aaugustin merged commit b6aede3 into from
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Showing 1 unique commit by 1 author.

Feb 24, 2013
Horst Gutmann zerok Added more details about the various serialization formats. 5612f54
This page is out of date. Refresh to see the latest.

Showing 1 changed file with 91 additions and 5 deletions. Show diff stats Hide diff stats

  1. +91 5 docs/topics/serialization.txt
96 docs/topics/serialization.txt
@@ -162,11 +162,82 @@ Identifier Information
162 162 .. _json: http://json.org/
163 163 .. _PyYAML: http://www.pyyaml.org/
164 164
165   -Notes for specific serialization formats
166   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  165 +XML
  166 +~~~
  167 +
  168 +The basic XML serialization format is quite simple::
  169 +
  170 + <?xml version="1.0" encoding="utf-8"?>
  171 + <django-objects version="1.0">
  172 + <object pk="123" model="sessions.session">
  173 + <field type="DateTimeField" name="expire_date">2013-01-16T08:16:59.844560+00:00</field>
  174 + <!-- ... -->
  175 + </object>
  176 + </django-objects>
  177 +
  178 +The whole collection of objects that is either serialized or de-serialized is
  179 +represented by a ``<django-objects>``-tag which contains multiple
  180 +``<object>``-elements. Each such object has two attributes: "pk" and "model",
  181 +the latter being represented by the name of the app ("sessions") and the
  182 +lowercase name of the model ("session") separated by a dot.
  183 +
  184 +Each field of the object is serialized as a ``<field>``-element sporting the
  185 +fields "type" and "name". The text content of the element represents the value
  186 +that should be stored.
  187 +
  188 +Foreign keys and other relational fields are treated a little bit differently::
  189 +
  190 + <object pk="27" model="auth.permission">
  191 + <!-- ... -->
  192 + <field to="contenttypes.contenttype" name="content_type" rel="ManyToOneRel">9</field>
  193 + <!-- ... -->
  194 + </object>
  195 +
  196 +In this example we specify that the auth.Permission object with the PK 24 has
  197 +a foreign key to the contenttypes.ContentType instance with the PK 9.
  198 +
  199 +ManyToMany-relations are exported for the model that binds them. For instance,
  200 +the auth.User model has such a relation to the auth.Permission model::
  201 +
  202 + <object pk="1" model="auth.user">
  203 + <!-- ... -->
  204 + <field to="auth.permission" name="user_permissions" rel="ManyToManyRel">
  205 + <object pk="46"></object>
  206 + <object pk="47"></object>
  207 + </field>
  208 + </object>
  209 +
  210 +This example links the given user with the permission models with PKs 46 and 47.
  211 +
  212 +JSON
  213 +~~~~
  214 +
  215 +When staying with the same example data as before it would be serialized as
  216 +JSON in the following way::
  217 +
  218 + [
  219 + {
  220 + "pk": "4b678b301dfd8a4e0dad910de3ae245b",
  221 + "model": "sessions.session",
  222 + "fields": {
  223 + "expire_date": "2013-01-16T08:16:59.844Z",
  224 + ...
  225 + }
  226 + }
  227 + ]
  228 +
  229 +The formatting here is a bit simpler than with XML. The whole collection
  230 +is just represented as an array and the objects are represented by JSON objects
  231 +with three properties: "pk", "model" and "fields". "fields" is again an object
  232 +containing each field's name and value as property and property-value
  233 +respectively.
  234 +
  235 +Foreign keys just have the PK of the linked object as property value.
  236 +ManyToMany-relations are serialized for the model that defines them and are
  237 +represented as a list of PKs.
167 238
168   -json
169   -^^^^
  239 +Date and datetime related types are treated in a special way by the JSON
  240 +serializer to make the format compatible with `ECMA-262`_.
170 241
171 242 Be aware that not all Django output can be passed unmodified to :mod:`json`.
172 243 In particular, :ref:`lazy translation objects <lazy-translations>` need a
@@ -175,14 +246,29 @@ In particular, :ref:`lazy translation objects <lazy-translations>` need a
175 246 import json
176 247 from django.utils.functional import Promise
177 248 from django.utils.encoding import force_text
  249 + from django.core.serializers.json import DjangoJSONEncoder
178 250
179   - class LazyEncoder(json.JSONEncoder):
  251 + class LazyEncoder(DjangoJSONEncoder):
180 252 def default(self, obj):
181 253 if isinstance(obj, Promise):
182 254 return force_text(obj)
183 255 return super(LazyEncoder, self).default(obj)
184 256
185 257 .. _special encoder: http://docs.python.org/library/json.html#encoders-and-decoders
  258 +.. _ecma-262: http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15
  259 +
  260 +YAML
  261 +~~~~
  262 +
  263 +YAML serialization looks quite similar to JSON. The object list is serialized
  264 +as a sequence mappings with the keys "pk", "model" and "fields". Each field is
  265 +again a mapping with the key being name of the field and the value the value::
  266 +
  267 + - fields: {expire_date: !!timestamp '2013-01-16 08:16:59.844560+00:00'}
  268 + model: sessions.session
  269 + pk: 4b678b301dfd8a4e0dad910de3ae245b
  270 +
  271 +Referential fields are again just represented by the PK or sequence of PKs.
186 272
187 273 .. _topics-serialization-natural-keys:
188 274

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.