+### Scope of the `serialize` annotation
+
+`serialize` can annotate class definitions, modules and attributes:
+
+* The annotation on a class applies only to the class definition,
+ only attributes declared locally will be serialized.
+ However, each definition of a class (a refinement or specialization) can be annotated with `serialize`.
+
+* A module declaration annotated with `serialize` states that all its class definitions
+ and locally declared attributes are serializable.
+
+ ~~~
+ module shared_between_clients is serialize
+ ~~~
+
+* Attribute annotated with `serialize` states that it is to be serialized, when the rest of the class does not.
+ The class will become subclass to `Serializable` but its attributes are not to be serialized by default.
+ Only the attributes with the `serialize` annotation will be serialized.
+
+ ~~~
+ # Only serialize the `name`
+ class UserCredentials
+ var name: String is serialize
+ var avatar_path: String = "/somepath/"+name is lazy
+ end
+ ~~~
+
+## The `noserialize` annotation
+
+The `noserialize` annotation mark an exception in a `serialize` module or class definition.
+
+* By default a module is `noserialize`. There is no need to declare it as such.
+
+* A class definition annotated with `noserialize` within a `serialize` module will not be made serializable.
+
+* A `noserialize` attribute within a class or module annotated with `serialize` will not serialize this attribute.
+ The class will still be made subclass of `Serializable` and it won't affect the other attributes.
+ The `noserialize` attribute will not be set at deserialization.
+ Usually, it will also be annotated with `lazy` to get its value by another mean after the object has been deserialized.
+
+ ~~~
+ # Once again, only serialize the `name`
+ class UserCredentials
+ serialize
+
+ var name: String
+ var avatar_path: String = "/somepath/"+name is noserialize, lazy
+ end
+ ~~~
+
+## The `serialize_as` annotation
+
+By default, an attribute is identified in the serialization format by its Nit name.
+The `serialize_as` attribute changes this behavior and sets the name of an attribute in the serialization format.
+
+This annotation can be useful to change the name of an attribute to what is expected by a remote service.
+Or to use identifiers in the serialization format that are reserved keywords in Nit (like `class` and `type`).
+
+~~~
+class UserCredentials
+ serialize
+
+ # Rename to "username" in JSON for compatibility with remote service
+ var name: String is serialize_as "username"
+
+ # Rename to a shorter "ap" for a smaller JSON file
+ var avatar_path: String = "/somepath/"+name is lazy, serialize_as "ap"
+end
+~~~