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

.. _datamodel_definition:

Yams *schema*

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

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

defines and handles the data model. It is based on entity types that

are either already defined in `Yams`_ and the *CubicWeb* standard

library; or more specific types defined in cubes. The schema for a

cube is defined in a `schema` python module or package.

.. _`Yams`: http://www.logilab.org/project/yams

.. _datamodel_overview:

Overview

~~~~~~~~

The core idea of the yams schema is not far from the classical

`Entity-relationship`_ model. But while an E/R model (or `logical

model`) traditionally has to be manually translated to a lower-level

data description language (such as the SQL `create table`

sublanguage), also often described as the `physical model`, no such

step is required with |yams| and |cubicweb|.

.. _`Entity-relationship`: http://en.wikipedia.org/wiki/Entity-relationship_model

This is because in addition to high-level, logical |yams| models, one

uses the |rql| data manipulation language to query, insert, update and

delete data. |rql| abstracts as much of the underlying SQL database as

a |yams| schema abstracts from the physical layout. The vagaries of

SQL are avoided.

As a bonus point, such abstraction make it quite comfortable to build

or use different backends to which |rql| queries apply.

So, as in the E/R formalism, the building blocks are ``entities``

(:ref:`EntityType`), ``relationships`` (:ref:`RelationType`,

:ref:`RelationDefinition`) and ``attributes`` (handled like relation

with |yams|).

Let us detail a little the divergences between E/R and |yams|:

* all relationship are binary which means that to represent a

  non-binary relationship, one has to use an entity,

* relationships do not support attributes (yet, see:

  http://www.cubicweb.org/ticket/341318), hence the need to reify it

  as an entity if need arises,

* all entities have an `eid` attribute (an integer) that is its

  primary key (but it is possible to declare uniqueness on other

  attributes)

Also |yams| supports the notions of:

* entity inheritance (quite experimental yet, and completely

  undocumented),

* relation type: that is, relationships can be established over a set

  of couple of entity types (henre the distinction made between

  `RelationType` and `RelationDefinition` below)

Finally |yams| has a few concepts of its own:

* relationships being oriented and binary, we call the left hand

  entity type the `subject` and the right hand entity type the

  `object`

.. note::

   The |yams| schema is available at run time through the .schema

   attribute of the `vregistry`.  It's an instance of

   :class:`cubicweb.schema.Schema`, which extends

   :class:`yams.schema.Schema`.

.. _EntityType:

Entity type

~~~~~~~~~~~

An entity type is an instance of :class:`yams.schema.EntitySchema`. Each entity type has

a set of attributes and relations, and some permissions which define who can add, read,

update or delete entities of this type.

The following built-in types are available: ``String``,

``Int``, ``BigInt``, ``Float``, ``Decimal``, ``Boolean``,

``Date``, ``Datetime``, ``Time``, ``Interval``, ``Byte`` and

``Password``. They can only be used as attributes of an other entity

type.

There is also a `RichString` kindof type:

 .. autoclass:: yams.buildobjs.RichString

The ``__unique_together__`` class attribute is a list of tuples of names of

attributes or inlined relations.  For each tuple, CubicWeb ensures the unicity

of the combination.  For example:

.. sourcecode:: python

  class State(EntityType):

      __unique_together__ = [('name', 'state_of')]

      name = String(required=True)

      state_of = SubjectRelation('Workflow', cardinality='1*',

                                 composite='object', inlined=True)

You can find more base entity types in

:ref:`pre_defined_entity_types`.

.. XXX yams inheritance

.. _RelationType:

Relation type

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

A relation type is an instance of

:class:`yams.schema.RelationSchema`. A relation type is simply a

semantic definition of a kind of relationship that may occur in an

application.

It may be referenced by zero, one or more relation definitions.

It is important to choose a good name, at least to avoid conflicts

with some semantically different relation defined in other cubes

(since there's only a shared name space for these names).

A relation type holds the following properties (which are hence shared

between all relation definitions of that type):

* `inlined`: boolean handling the physical optimization for archiving

  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.

* `symmetric`: boolean indicating that the relation is symmetrical, which

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

.. _RelationDefinition:

Relation definition

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

A relation definition is an instance of

:class:`yams.schema.RelationDefinition`. It is a complete triplet

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

When creating a new instance of that class, the corresponding

:class:`RelationType` instance is created on the fly if necessary.

Properties

``````````

The available properties for relation definitions are enumerated

here. There are several kind of properties, as some relation

definitions are actually attribute definitions, and other are not.

Some properties may be completely optional, other may have a default

value.

Common properties for attributes and relations:

* `description`: a unicode string describing an attribute or a

  relation. By default 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.

* `constraints`: a list of conditions/constraints that the relation has to

  satisfy (c.f. `Constraints`_)

* `cardinality`: a two character string specifying the cardinality of

  the 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...). Default value is '**'. The possible values are

  inspired from regular expression syntax:

    * `1`: 1..1

    * `?`: 0..1

    * `+`: 1..n

    * `*`: 0..n

Attributes properties:

* `unique`: boolean indicating if the value of the attribute has to be

  unique 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 useful

  only if you know that you will have to run numerous searches on the

  value of this attribute.

* `default`: default value of the attribute. In case of date types, the values

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

* `metadata`: Is also accepted as an argument of the attribute contructor. It is

  not really an attribute property. see `Metadata`_ for details.

Properties for `String` attributes:

* `fulltextindexed`: boolean indicating if the attribute is part of

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

  `Byte` as well*)

* `internationalizable`: boolean indicating if the value of the

  attribute is internationalizable (false by default)

Relation properties:

* `composite`: string indicating that the subject (composite ==

  'subject') 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.

* `fulltext_container`: string indicating if the value if the full

  text indexation of the entity on one end of the relation should be

  used to find the entity on the other end. The possible values are

  'subject' or 'object'. For instance the use_email relation has that

  property set to 'subject', since when performing a full text search

  people want to find the entity using an email address, and not the

  entity representing the email address.

Constraints

```````````

By default, the available constraint types are:

General Constraints

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

* `SizeConstraint`: allows to specify a minimum and/or maximum size on

  string (generic case of `maxsize`)

* `BoundaryConstraint`: allows to specify a minimum and/or maximum value

  on numeric types and date

.. sourcecode:: python

   from yams.constraints import BoundaryConstraint, TODAY, NOW, Attribute

   class DatedEntity(EntityType):

      start = Date(constraints=[BoundaryConstraint('>=', TODAY())])

      end = Date(constraints=[BoundaryConstraint('>=', Attribute('start'))])

   class Before(EntityType);

      last_time = DateTime(constraints=[BoundaryConstraint('<=', NOW())])

* `IntervalBoundConstraint`: allows to specify an interval with

  included values

.. sourcecode:: python

     class Node(EntityType):

         latitude = Float(constraints=[IntervalBoundConstraint(-90, +90)])

* `UniqueConstraint`: identical to "unique=True"

* `StaticVocabularyConstraint`: identical to "vocabulary=(...)"

Constraints can be dependent on a fixed value (90, Date(2015,3,23)) or a variable.

In this second case, yams can handle :

* `Attribute`: compare to the value of another attribute.

* `TODAY`: compare to the current Date.

* `NOW`: compare to the current Datetime.

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.

* `RQLConstraint`: allows to specify a RQL query that has to be satisfied

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

  `S` and `O` are reserved for the relation subject and object entities.

* `RQLVocabularyConstraint`: similar to the previous type of constraint except

  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.

* `RQLUniqueConstraint`: allows to the specify a RQL query that ensure that an

  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

  reserved for the relation subject entity. The other variables should be

  specified with the second constructor argument (mainvars). This constraint type

  should be used when __unique_together__ doesn't fit.

.. XXX note about how to add new constraint

.. _securitymodel:

The security model

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

The security model of `CubicWeb` is based on `Access Control List`.

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:

* we associate rights at the entities/relations schema level

* the default groups are: `managers`, `users` and `guests`

* users belong to the `users` group

* there is a virtual group called `owners` to which we can associate only

  `delete` and `update` permissions

  * we can not add users to the `owners` group, they are implicitly added to it

    according to the context of the objects they own

  * the permissions of this group are only checked on `update`/`delete` actions

    if all the other groups the user belongs to do not provide those permissions

Setting permissions is done with the class attribute `__permissions__`

of entity types and relation definitions. The value of this attribute

is a dictionary where the keys are the access types (action), and the

values are the authorized groups or rql expressions.

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

`delete`.

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

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

and they are a refinement of an entity type permission.

.. note::

   By default, the permissions of an entity type attributes are

   equivalent to the permissions of the entity type itself.

   It is possible to provide custom attribute permissions which are

   stronger than, or are more lenient than the entity type

   permissions.

   In a situation where all attributes were given custom permissions,

   the entity type permissions would not be checked, except for the

   `delete` action.

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

provided if the user is in one of the listed groups or if one of the RQL condition

is satisfied.

Default permissions

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

The default permissions for ``EntityType`` are:

.. sourcecode:: python

   __permissions__ = {

        'read': ('managers', 'users', 'guests',),

        'update': ('managers', 'owners',),

        'delete': ('managers', 'owners'),

        'add': ('managers', 'users',)

        }

The default permissions for relations are:

.. sourcecode:: python

   __permissions__ = {'read': ('managers', 'users', 'guests',),

                    'delete': ('managers', 'users'),

                    'add': ('managers', 'users',)}

The default permissions for attributes are:

.. sourcecode:: python

   __permissions__ = {'read': ('managers', 'users', 'guests',),

                      'add': ('managers', ERQLExpression('U has_add_permission X'),

                      'update': ('managers', ERQLExpression('U has_update_permission X')),}

.. note::

   The default permissions for attributes are not syntactically

   equivalent to the default permissions of the entity types, but the

   rql expressions work by delegating to the entity type permissions.

The standard user groups

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

* `guests`

* `users`

* `managers`

* `owners`: virtual group corresponding to the entity's owner.

  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 precreate

script of the cube (``migration/precreate.py``). Defining groups in postcreate

script or later makes them unavailable for security purposes (in this case, an

`sync_schema_props_perms` command has to 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 entity type / relation definitions. An rql expression

is a piece of query (corresponds to the WHERE statement of an RQL query), and the

expression will be considered as satisfied if it returns some results. They can

not be used in `read` permission.

To use RQL expression in entity type permission:

* you have to use the class :class:`~cubicweb.schema.ERQLExpression`

* in this expression, the variables `X` and `U` are pre-defined references

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

  user who send the request

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

the following:

* you have to use the class :class:`~cubicweb.schema.RRQLExpression` instead of

  :class:`~cubicweb.schema.ERQLExpression`

* in the expression, the variables `S`, `O` and `U` are pre-defined references 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

To define security for attributes of an entity (non-final relation), you have to

use the class :class:`~cubicweb.schema.ERQLExpression` in which `X` represents

the entity the attribute belongs to.

It is possible to use in those expression a special relation

`has_<ACTION>_permission` where the subject is the user (eg 'U') and the object

is any variable representing an entity (usually 'X' in

:class:`~cubicweb.schema.ERQLExpression`, 'S' or 'O' in

:class:`~cubicweb.schema.RRQLExpression`), meaning that the user needs to have

permission to execute the action <ACTION> on the entities represented by this

variable. It's recommanded to use this feature whenever possible since it