(MODAClouds) Descriptors

Warning

This document is abandoned!

2   Concepts

The concepts below are a blend of ideas from various sources:

Application (architecture and deployment)

(self explanatory; called "service" in TOSCA;) ...

("architecture" is a synonym for "type"; "deployment" is a synonym for "instance";) ...

Component (type and instance)

(called "node" in TOSCA; called "artifact" in Models@RunTime; called "component" in mOSAIC;) ...

Resource (type and instance)

(called "node" in TOSCA; no equivalent in Models@RunTime; called "resource" in mOSAIC;) ...

Relation (type and instance)

(called "relation" in TOSCA; called "binding" in Models@RunTime; no equivalent in mOSAIC;) ...

Service (type and instance)

(called "support service" in ModaClouds; called "node" in TOSCA; no equivalent in mOSAIC; not strictly related with the application;) ...

Partition (type and instance)

(called "node" in TOSCA; called "provider" in Models@RunTime; no equivalent in mOSAIC;) ...

Configuration

(see ...) ...

Policy

(see ...) ...

Annotation

(see ...) ...

Descriptor

(called "template" in TOSCA; called "descriptor" in mOSAIC;) ...

3   Descriptors

3.1   Meta language

In what follows we'll use a tweaked variant of BNF geared towards describing JSON-based languages. A more detailed description of the syntax is found here: JSON BNF.

As constraints applied to JSON we have:

  • all documents must conform to the JSON syntax specified in [RFC-4627];
  • all documents must be encoded in UTF-8;
  • the following characters are disallowed: the null character (\0), any control characters (from 0x01 to 0x1f) except new line (\n) and tab (\t);
  • inside strings none of the control characters are allowed (thus the exceptions above don't apply); however they can be denoted by using the escaping syntax;
  • (the bottom line: looking at the stream of bytes it must be decodable as a valid UTF-8 sequence, where no control characters except new line or tab are used; however inside strings these characters can appear if they are properly escaped;)
  • all documents must contain a single JSON construct (having as attribute values any other valid JSON construct); i.e. the files, request or reply bodies, blobs, etc. must contain a single JSON object;
  • the names of JSON attributes must contain only ASCII letters (upper case or lower case), digits and the following symbols: hyphen (-), underline (_), dollar ($), slash (/) or colon (:); however they must start with a letter, digit or dollar ($); all other characters must be escaped by using an algorithm using the symbol dollar ($) as discriminator;
  • there are a few attributes that break the previous rule, however they are defined in the current document and when used they must have the designated semantic;

3.5   Miscellaneous descriptors

Policies

<policy-descriptor> ::= {
    @<selfdescribing-entity-attributes>,
    @<standalone-entity-attributes> ?,
    ...
}

<policies-attribute> ::= {
    "policies" : {
        <alias> : <policy-descriptor> *,
    },
}

Annotations

<annotation-descriptor> ::= {
    @<selfdescribing-entity-attributes>,
    @<standalone-entity-attributes> ?,
    ...
}

<annotations-attribute> ::= {
    "annotations" : {
        <alias> : <annotation-descriptor> *,
    },
}

3.6   Standalone entities

Summary

Some of the descriptors presented in the following sections could be used as standalone documents, for example for storage in files or databases, or for sending in HTTP-based requests. For those accustomed with XML, the standalone usage relates to having a particular element be the root element of the document, thus needing certain meta attributes to identify its syntax and semantic, such as namespaces, schema, etc. Thus also for JSON documents it is important to identify the enclosed syntax and semantic just by looking at certain attributes.

Moreover in addition to identifying the syntax and semantic, i.e. the schema, for our purpose it could prove useful to also identify the following properties of the enclosed entity:

  • an identifier that uniquely qualifies the entity all others of the same type, and possibly all types, such as a primary key that could pin-point it in the database; for example an UUID (v4 or v5) could be used;
  • a revision that uniquely qualifies the variant of the document in the context of its timeline or history, which could be used in case of eventually consistent scenarios; for example an incrementing counter (obtained from a central authority), or a MD5 or SHA obtained by hashing the previous revision and the current contents (or some random data) could be used; by the same rationale a previous revision could prove useful to establish its timeline; (another more involving option is to use vector clocks;)

It must be also noted that sometimes a document may contain an entity that could nest other entities that are could make sense as standalone documents (for example a descriptor about a VM cluster could contain the descriptor of each VM). In such cases the attributes described below could be used in these nested entities for referencing, however they shouldn't change the semantic of the root entity in any way.

Syntax

The following attributes should be added to all entities that would make sense to be used as standalone entities:

<selfdescribing-entity-attributes> ::= {
    "_schema" : <schema-identifier>,
    "_schema/version" : <schema-version>,
}

<standalone-entity-attributes> ::= {
    @<selfdescribing-entity-attributes>,
    "_identifier" : <entity-identifier>,
    "_revision" : <revision>,
    "_revision/previous" : (<revision> | null)?,
    "_revision/originator" : (<url> | null)?,
}

Where:

<schema-identifier> and <schema-version>
<schema-identifier> ::= /^#([a-z0-9](?:[a-z0-9.-]*[a-z0-9])?):([a-z0-9](?:[a-z0-9.-]*[a-z0-9])?)$/ | <url>
<schema-version> ::= <<positive-integer>>

The schema identifier could thus take a form similar to #modaclouds:generic-component. It is easy trivial to disambiguate between the identifier and URL because no valid URL can start with the symbol sharp #; they can however contain it.

As noted the schema version is mandatory, and even if not applicable it should be the value 1; for example in cases where the version could be encoded in the schema identifier. However it is strongly advised to keep the schema identifier constant and vary the schema version.

There is no concept of minor change in schema versioning, thus any change in either syntax or semantic must increment the version. This stems mainly from two observations: in most cases no changes are actually forward compatible (i.e. older implementations can read newer schemas), and it is simpler to just compare two integer values than to go into string parsing and component-vise comparison.

<identifier>
<entity-identifier> ::= <hex-string> | <ascii-string>

As noted it is preferable to use a constant length binary identifier that is encoded as sequence of hex digits.

Two identifiers are equivalent if and only if they have exactly the same character sequences (after decoding the escaped characters); i.e. equal in terms of the strcmp POSIX function, and thus the implication of ASCII only characters.

<revision>
<revision> ::= <hex-string> | <json>

As noted it is preferable to use a constant length binary identifier that is encoded as a sequence of hex digits.

If two revisions are or not equivalent is up to the implementation to decide.

3.7   Miscellaneous syntaxes

Network related non-terminals

<url> ::= ...

<fqdn> ::= ...
<ipv4> ::= ...
<ipv6> ::= ...

Various string-based non-terminals

<alias> ::= ...

<ascii-string> ::= ...

<hex-string> ::= ...

Various integer-based non-terminals

<positive-integer> ::= ...