.. -*- coding: utf-8 -*-

Yams *schema*

-------------

The **schema** is the core piece of a *CubicWeb* instance as it defines

the handled data model. It is based on entity types that are either already

defined in the *CubicWeb* standard library; or more specific types defined

in cubes. The schema for a cube is defined in a :file:schema.py file or in

one or more Python files under the :file:`schema` directory (python package).

At this point, it is important to make clear the difference between

*relation type* and *relation definition*: a *relation type* is only a relation

*relation definition* is a complete triplet

"<subject entity type> <relation type> <object entity type>".

when the instance is created or upgraded.

`Decimal`, `Boolean`, `Date`, `Datetime`, `Time`, `Interval`, `Byte`

and `Password`.

The instance schema is accessible through the .schema attribute of the

`vregistry`.  It's an instance of :class:`cubicweb.schema.Schema`, which

extends :class:`yams.schema.Schema`.

:note:

  In previous yams versions, almost all classes where available without

Entity type

~~~~~~~~~~~

update or delete entities of this type.

XXX yams inheritance

Relation type

~~~~~~~~~~~~~

relation definitions of that type):

  the relation in the subject entity table, instead of creating a specific

  table for the relation. This applies to relations where cardinality

  of subject->relation->object is 0..1 (`?`) or 1..1 (`1`) for *all* its relation

  definitions.

  means that `X relation Y` implies `Y relation X`.

Relation definition

~~~~~~~~~~~~~~~~~~~

"<subject entity type> <relation type> <object entity type>".

Properties

``````````

    this string will be used in the editing form of the entity, which means

    that it is supposed to help the end-user and should be flagged by the

    function `_` to be properly internationalized.

    satisfy (c.f. `Constraints`_)

    relation. The first character defines the cardinality of the relation on

    the subject, and the second on the object. When a relation can have

    multiple subjects or objects, the cardinality applies to all,

    not on a one-to-one basis (so it must be consistent...). The possible

    * `1`: 1..1

    * `?`: 0..1

    * `+`: 1..n

    * `*`: 0..n

    or not within all entities of the same type (false by default)

    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.

    which could be used correspond to the RQL keywords `TODAY` and `NOW`.

    the full text index (false by default) (*applicable on the type `Byte`

    as well*)

    is internationalizable (false by default)

    is composed of the objects of the relations. For the opposite case (when

    the object is composed of the subjects of the relation), we just set

    'object' as value. The composition implies that when the relation

    is deleted (so when the composite is deleted, at least), the composed are also deleted.

Constraints

```````````

General Constraints

......................

  string (generic case of `maxsize`)

  numeric types

XXX Attribute, TODAY, NOW

RQL Based Constraints

......................

RQL based constraints may take three arguments. The first one is the ``WHERE``

clause of a RQL query used by the constraint. The second argument ``mainvars``

is the ``Any`` clause of the query. By default this include `S` reserved for the

subject of the relation and `O` for the object. Additional variables could be

specified using ``mainvars``. The argument expects a single string with all

variable's name separated by spaces. The last one, ``msg``, is the error message

displayed when the constraint fails. As RQLVocabularyConstraint never fails the

third argument is not available.

  by the subject and/or the object of relation. In this query the variables

  that it does not express a "strong" constraint, which means it is only used to

  restrict the values listed in the drop-down menu of editing form, but it does

  not prevent another entity to be selected.

  attribute is unique in a specific context. The Query must **never** return more

  than a single result to be satisfied. In this query the variables `S` is

  specified with the second constructor argument (mainvars). This constraints

  should be used when UniqueConstraint doesn't fit. Here is a simple example ::

    # Check that in the same Workflow each state's name is unique.  Using

    # UniqueConstraint (or unique=True) here would prevent states in different

    # workflows to have the same name.

    # With: State S, Workflow W, String N ; S state_of W, S name N

    RQLUniqueConstraint('S name N, S state_of WF, Y state_of WF, Y name N',

                        mainvars='Y',

                        msg=_('workflow already have a state of that name'))

XXX note about how to add new constraint

.. _securitymodel:

The security model

~~~~~~~~~~~~~~~~~~

The main principles are:

* users and groups of users

* a user belongs to at least one group of user

* permissions (read, update, create, delete)

* permissions are assigned to groups (and not to users)

For *CubicWeb* in particular:

Setting permissions is done with the attribute `__permissions__` of entities and

(action), and the values are the authorized groups or expressions.

For an entity type, the possible actions are `read`, `add`, `update` and

`delete`.

For a relation type, the possible actions are `read`, `add`, and `delete`.

For each access type, a tuple indicates the name of the authorized groups and/or

one or multiple RQL expressions to satisfy to grant access. The access is

is satisfied.

The standard user groups

````````````````````````

* `guests`

* `users`

* `managers`

  This can only be used for the actions `update` and `delete` of an entity

  type.

It is also possible to use specific groups if they are defined in the

be issued in a CubicWeb shell).

Use of RQL expression for write permissions

```````````````````````````````````````````

It is possible to define RQL expression to provide update permission

(`add`, `delete` and `update`) on relation and entity types.

* you have to use the class `ERQLExpression`

* the used expression corresponds to the WHERE statement of an RQL query

  respectively on the current entity (on which the action is verified) and

  on the user who send the request

* it is possible to use, in this expression, a special relation

  "has_<ACTION>_permission" where the subject is the user and the

  object is any variable, meaning that the user needs to have

  permission to execute the action <ACTION> on the entities related

  to this variable

For RQL expressions on a relation type, the principles are the same except

* you have to use the class `RRQLExpression` in the case of a non-final relation

  to respectively the subject and the object of the current relation (on

  which the action is being verified) and the user who executed the query

* we can also define rights over attributes of an entity (non-final relation),

  - to define RQL expression, we have to use the class `ERQLExpression`

  - the permissions `add` and `delete` are equivalent. Only `add`/`read`

    are actually taken in consideration.

:Note on the use of RQL expression for `add` permission:

  Potentially, the use of an RQL expression to add an entity or a

  relation can cause problems for the user interface, because if the

  expression uses the entity or the relation to create, then we are

  not able to verify the permissions before we actually add the entity

  (please note that this is not a problem for the RQL server at all,

  because the permissions checks are done after the creation). In such

  case, the permission check methods (CubicWebEntitySchema.check_perm

  and has_perm) can indicate that the user is not allowed to create

  this entity but can obtain the permission.

  To compensate this problem, it is usually necessary, for such case,

  to use an action that reflects the schema permissions but which enables

  to check properly the permissions so that it would show up if necessary.

Use of RQL expression for reading rights

````````````````````````````````````````

* we can not use `RRQLExpression` on relation types for reading

* special relations "has_<ACTION>_permission" can not be used

Defining your schema using yams

-------------------------------

Entity type definition

~~~~~~~~~~~~~~~~~~~~~~

When defining a schema using python files, you may use the following shortcuts:

For example:

.. sourcecode:: python

  class Person(EntityType):

    """A person with the properties and the relations necessary for my

    application"""

    last_name = String(required=True, fulltextindexed=True)

    first_name = String(required=True, fulltextindexed=True)

    title = String(vocabulary=('Mr', 'Mrs', 'Miss'))

    date_of_birth = Date()

    works_for = SubjectRelation('Company', cardinality='?*')

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.

An attribute is defined in the schema as follows::

    attr_name = attr_type(properties)

where `attr_type` is one of the type listed above and `properties` is

for more details).

* it is possible to use the attribute `meta` to flag an entity type as a `meta`

  (e.g. used to describe/categorize other entities)

means that you need two separate entities that implement the `ITree` interface and

get the result from `.children()` which ever entity is concerned.

Inheritance

```````````

XXX feed me

Definition of relations

~~~~~~~~~~~~~~~~~~~~~~~

XXX add note about defining relation type / definition

A relation is defined by a Python class heriting `RelationType`. The name

of the class corresponds to the name of the type. The class then contains

a description of the properties of this type of relation, and could as well

contain a string for the subject and a string for the object. This allows to create

new definition of associated relations, (so that the class can have the

definition properties from the relation) for example ::

  class locked_by(RelationType):

    """relation on all entities indicating that they are locked"""

    inlined = True

    cardinality = '?*'

    subject = '*'

    object = 'CWUser'

When a relation is not inlined and not symmetrical, and it does not require