--- a/doc/book/en/B0012-schema-definition.en.txt	Fri Apr 24 16:48:38 2009 +0200
+++ b/doc/book/en/B0012-schema-definition.en.txt	Fri Apr 24 17:04:14 2009 +0200
@@ -6,7 +6,9 @@
 An entity type is defined by a Python class which inherits from `EntityType`.
 The class definition contains the description of attributes and relations
 for the defined entity type.
-The class name corresponds to the entity type name.
+The class name corresponds to the entity type name. It is exepected to be
+defined in the module ``mycube.schema``.
+
 
 For example ::
 
@@ -21,14 +23,36 @@
     works_for = SubjectRelation('Company', cardinality='?*')
 
 
-* the name of the Python attribute corresponds to the name of the attribute
-  or the relation in `CubicWeb` application.
+The entity described above defines three attributes of type String,
+last_name, first_name and title, an attribute of type Date for the date of
+birth and a relation that connects a `Person` to another entity of type
+`Company` through the semantic `works_for`.
+
+The name of the Python attribute corresponds to the name of the attribute
+or the relation in `CubicWeb` application.
+
+Built-in types for attributes
+`````````````````````````````
 
-* all `CubicWeb` built-in types are available : `String`, `Int`, `Float`,
-  `Boolean`, `Date`, `Datetime`, `Time`, `Byte`; they are and implicitely
-  imported (as well as the special the function "_").
+All `CubicWeb` built-in types are available : `String`, `Int`, `Float`,
+`Decimal`, `Boolean`, `Date`, `Datetime`, `Time`, `Interval`, `Byte` 
+and `Password`.
+They are implicitely imported (as well as the special the function "_"
+for translation :ref:`internationalization`).
+
+An attribute is defined in the schema as follows::
+    
+    attr_name = attr_type(properties*)
 
-* each entity type has at least the following meta-relations :
+where `attr_type` is one of the type listed above and `properties` is
+a list of  the attribute needs to statisfy (see :ref:`properties`
+for more details). 
+
+
+Meta-data
+`````````
+
+Each entity type has at least the following meta-relations :
 
   - `eid` (`Int`)
   
@@ -41,7 +65,7 @@
   - `owned_by` (`CWUser`) (to whom the entity belongs; by default the 
      creator but not necessary, and it could have multiple owners)
      
-  - `is` (`CWEType`)
+  - `is` (`CWEType`) (of which type the entity is)
 
 
 * relations can be defined by using `ObjectRelation` or `SubjectRelation`.
@@ -62,6 +86,11 @@
 * it is possible to use the attribute `meta` to flag an entity type as a `meta`
   (e.g. used to describe/categorize other entities)
 
+Optionnal properties
+````````````````````
+.. _properties:
+
+
 * optional properties for attributes and relations : 
 
   - `description` : a string describing an attribute or a relation. By default
@@ -95,7 +124,7 @@
     or not within all entities of the same type (false by default)
 
   - `indexed` : boolean indicating if an index needs to be created for this 
-    attribute in the database (false by default). This is usefull only if
+    attribute in the database (false by default). This is useful only if
     you know that you will have to run numerous searches on the value of this
     attribute.