Cinelab Application Model - cam =============================== In this document, QNames are used to abbreviate URLs (by concatenating the namespace with the suffix). We use the following namespaces: * @prefix dc: http://purl.org/dc/elements/1.1/ * @prefix cam: http://advene.org/ns/cinelab/ * @prefix pm: http://advene.org/ns/parser-meta/ Generalities ------------ The Cinelab application model defines some higher-level concepts such as annotation types, relation types and schemas, relying on the data model defined in the hypervideo model. The following figure gives an overview of these new element types. It also specifies more precisely some metadata associated to elements of the model. .. figure:: ../modele_cinelab_uml.png :scale: 70 % :align: center Cinelab specific elements Package ~~~~~~~ In order to ease elements addressing, package elements SHOULD be addressable through the `TALES syntax`_ as in the current Advene version. This syntax offers a uniform access to the data model, that can be stored in various ways (XML file, database, etc). Moreover, it allows to use TALES expressions as URL parts, easing the development of REST-based architectures. .. _`TALES syntax`: http://docs.zope.org/zope2/zope2book/AppendixC.html#tales-overview Any TALES expression must be evaluated in a given context. This context MUST reference a specific package, named *reference package*. It MUST be accessible in TALES through the named ``refpackage``. When the TALES expression is used inside of an element content, the reference package is the package that owns the element. To make them easier to identify, and ease interoperability with other applications, we define a *TALES string* as a character string that can contain TALES expressions identified with the notation ``${...}``. This makes it possible to gracefully degrade TALES expression support: applications without TALES support will display the expression, clearly identified. TALES-supporting systems only have to systematically preprend the ``string:`` prefix to the character string before sending it to the TALES evaluator. Metadata ^^^^^^^^ +--------------------------------------+---------------+--------------+ | Meaning | Element | API property | +======================================+===============+==============+ | prefix/namespace association | pm:namespaces | namespaces | +--------------------------------------+---------------+--------------+ The ``pm:namespaces`` metadata is used to simplify URI use, especially for metadata. Its structure is a set of couples (prefix, namespace URI). Each couple is encoded by concatenating the prefix and its URI, separated with a space. Couples are separated by a newline. Using this information, any time a URI is used, the user interface can replace it with a RDF-like QName. NB: this metadata belongs to a specific namespace, because it has to be specifically processed when seralising/analysing a Cinelab XML package. Instead of being stored as other element metadata, it is encoded/fetched from the XML namespace declarations (*xmlns* attributes). Elements ~~~~~~~~ Common metadata ~~~~~~~~~~~~~~~ Metadata keys MUST be URIs. The package and any package element MUST possess the following Dublin Core metadata: +-------------------------------+----------------+--------------+ | Meaning | Element | API property | +===============================+================+==============+ | Creator | dc:creator | creator | +-------------------------------+----------------+--------------+ | Last contributor | dc:contributor | contributor | +-------------------------------+----------------+--------------+ | Creation date | dc:created | created | +-------------------------------+----------------+--------------+ | Last modification date | dc:modified | modified | +-------------------------------+----------------+--------------+ Dates MUST be encoding according the ISO 8601 norm, with restrictions specified in http://www.w3.org/TR/NOTE-datetime . Optionaly, the following metadata MAY be defined: +-------------+----------------+--------------+ | Meaning | Element | API property | +=============+================+==============+ | Title | dc:title | title | +-------------+----------------+--------------+ | Description | dc:description | description | +-------------+----------------+--------------+ TALES Addressing ^^^^^^^^^^^^^^^^ Any object with metadata MUST expose a TALES attribute ``meta`` that offers an access to its metadata through a TALES expression like ``obj/meta/dc/creator`` where ``dc`` (in the example) is a prefix declared in the ``pm:namespaces`` metadata. More precisely, the ``pm:namespaces`` of the *reference package* for the TALES expression will be used (and not the package owning the element). .. FIXME: rationale? Metadata defined by the applicative model can specify a synonym property in the API column, for instance ``creator`` for ``dc:creator``. In this case, an equivalent TALES expression can be ``obj/creator``. Content ~~~~~~~ A content specifies its MIME type. Some generic MIME types like ``application/xml`` or ``application/json`` may specify additional contraints for some content sub-types (as XML schemas or JSON-schemas for instances). A content MAY specify a *model* attribut that will contain the identifier of a resource whose content will be the appropriate schema. The following schemas MAY be implemented: +------------------------------------------------+-------------------+-------------------------------------+----------------------+ | Schema | Content MIME type | Schema MIME type | Schema content | +------------------------------------------------+-------------------+-------------------------------------+----------------------+ | Perl Compatible Regular Expression (PCRE) | text/* | application/x-advene-schema-pcre | A regular expression | +------------------------------------------------+-------------------+-------------------------------------+----------------------+ | RelaxNG | application/xml | application/relax-ng-compact-syntax | A RelaxNG schema in | | | | | compact notation | +------------------------------------------------+-------------------+-------------------------------------+----------------------+ Elements -------- Media ~~~~~~ Attributes ^^^^^^^^^^ +----------------------------------+--------------+ | Meaning | API property | +==================================+==============+ | URL | url | +----------------------------------+--------------+ | unit (ms, frame...) | unit | +----------------------------------+--------------+ | origin (in specified unit)d | origin | +----------------------------------+--------------+ The only temporal reference that an implementation MUST support uses the "ms" unit (milliseconds), with a 0 origin. A URL is used to specify the designated media. In the specific case of DVDs, there is no standard to define generic URLs. The model specifies the following format: ``dvd://title/chapter`` where ``title`` and ``chapter`` are optional numbers (defaulting to 1 if not specified). Application should convert this URL to the appropriate format for the used multimedia player. Metadata ^^^^^^^^ The following metadata MAY be defined: +-----------------------+--------------+--------------+ | Meaning | Element | API property | +=======================+==============+==============+ | Resource duration | cam:duration | duration | +-----------------------+--------------+--------------+ | URI | cam:uri | uri | +-----------------------+--------------+--------------+ If the URL is not accessible, the URI is used as a key to identify another URL for the same media. Test ~~~~~ A test is a view that returns a value interpretable as a boolean value. It is notably used to express constraints on elements. The following MIME type MAY be implemented: +---------------------------------------+-----------------------------------+ | ``application/x-advene-builtin-test`` | Test défini en interne par Advene | +---------------------------------------+-----------------------------------+ The *builtin* test has for content a number of attributes to check. For instance, ``content-type=text/html``. Such a format has the interesting property of being easily introspected, in order to allow automatic GUI generation. Annotation ~~~~~~~~~~ Metadata ^^^^^^^^ The following metadata MUST be specified. +-----------------------+--------------+--------------+ | Meaning | Element | API property | +=======================+==============+==============+ | Annotation type id | cam:type | type | +-----------------------+--------------+--------------+ The following metadata MAY be defined: +------------------------+-----------+--------------------------------------------+ | Meaning | Element | API property | +========================+===========+============================================+ | Annotation color | cam:color | TALES string that can be evaluated | | | | in the annotation context to get its color | +------------------------+-----------+--------------------------------------------+ Relation ~~~~~~~~~ Metadata ^^^^^^^^ The following metadata MUST be specified. +-----------------------+--------------+--------------+ | Meaning | Element | API property | +=======================+==============+==============+ | Relation type id | cam:type | type | +-----------------------+--------------+--------------+ The following metadata MAY be defined: +------------------------+-----------+--------------------------------------------+ | Meaning | Element | API property | +========================+===========+============================================+ | Relation color | cam:color | TALES string that can be evaluated | | | | in the relation context to get its color | +------------------------+-----------+--------------------------------------------+ Annotation type and relation type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An annotation type (resp. a relation type) is a tag, that has the ``cam:system-type`` metadata, with value "annotation-type" (resp. "relation-type"). An annotation (resp. relation) MUST be associated with exactly one annotation type (resp. relation type), and this association MUST be consistent with the annotation (resp. relation) metadata ``cam:type``. Metadata ^^^^^^^^ The following metadata MAY be defined: +--------------------------------+-------------------------+----------------------------------------------------------+ |Meaning | Name | Content | +================================+=========================+==========================================================+ | Element representation | cam:representation | TALES string that should be evaluated on elements | | | | of the type, to get a compact textual representation | +--------------------------------+-------------------------+----------------------------------------------------------+ | Type color | ca:color | TALES string that should be evaluated on the type | | | | to get its color. | +--------------------------------+-------------------------+----------------------------------------------------------+ | Element color | cam:element-color | TALES string that should be evaluated on elements | | | | of the type, to get their color | +--------------------------------+-------------------------+----------------------------------------------------------+ | Generic constraint | cam:element-constraint | Test view that elements of this type should match | +--------------------------------+-------------------------+----------------------------------------------------------+ | Content type constraint [1]_ | cam:content-mimetype | String specifying the MIME type for elements of the type | +--------------------------------+-------------------------+----------------------------------------------------------+ | Content model constraint [1]_ | cam:content-model | Resource specifying the content model for elements | | | of the type | of the type | +--------------------------------+-------------------------+----------------------------------------------------------+ .. [1] both metadata (Content type constraint and content model constraint) bring no more expressivity than Generic constraint (which is more generic), but they allow to remove one indirection level (the Test view) for most frequently used constraints. Schema ~~~~~~ A schema is a list whose metadata ``cam:system-type`` value is "schema". A schema represents a description schema, grouping a consistent set of annotation types, relation types and possibly other elements related to the description choices (resources containing content models, tests, associated views...). Tag ~~~ Metadata ^^^^^^^^ The following metadata MAY be defined: +------------------------+-----------+--------------------------------------------+ | Meaning | Element | API property | +========================+===========+============================================+ | Tag color | cam:color | TALES string that can be evaluated | | | | in the tag context to get its color | +------------------------+-----------+--------------------------------------------+ Resources ~~~~~~~~~ Core model resources. Some may be hierarchised as in a filesystem. Their identifier will then be prefixed with ``:userfile:`` and will encode their path in the identifier by separating directory names with ``:``. Implementation remarks ~~~~~~~~~~~~~~~~~~~~~~ Any python object that will have to be handled in the Advene model has to be wrapped in a (temporary) Resource object, so that model consistency is preserved. For efficiency reasons, effective wrapping is carried out lazily. For instance, a view produces a resource. But if is is included in another view (through TAL for instance), there is no need to transform it into a resource, since it will be consumed (by the including view) before reaching the Advene model level. The including view has to produce a resource, which will be returned to the application. Dynamic imports ~~~~~~~~~~~~~~~ Attributes ^^^^^^^^^^ +---------+--------------+ | Meaning | API property | +=========+==============+ | URL | url | +---------+--------------+ | URI | uri | +---------+--------------+ If an URL is not accessible, the URI value can be used by the application to identify another URL for the same package. If the package loaded at a given URL declares a URI other than specified by the dynamic import, the application SHOULD notify the user to determine the appropriate way to handle this inconsistency (update the dynamic import, or look for the given URI at another URL).