THE DATANEST APP

Datanest

Application Description

Datanest is used to describe the data structure of an application and to work with it efficiently using standard API calls. From a design perspective, the data base is defined by entities and their relationships, and the API allows their definition and manipulation of their instances, i.e., creation, modification, deletion, or retrieval of data from them, such as listing, schema, paginated entity views, searching, and basic types of aggregations.

Datanest has a special section in the application manifest, datanest:section, where their definitions are placed. During application registration, the structure of the database where entities are stored is automatically modified. If possible, stored data in tables is preserved during modification, but this is not guaranteed.

Entities can be used when designing your own application.

Description of Entities Using Datanest XML Language

Example

<datanest:section xmlns:datanest="https://blueprint.retailys.com/blueprint.xsd">
    <entities>
        <!-- CATEGORIES -->
        <entity name="categories" permissionable="true">
            <label>Categories</label>
            <record>
                <!-- name -->
                <field name="name" type="string">
                    <label>Name</label>
                </field>
            </record>
        </entity>
        <!-- RATINGS -->
        <entity name="ratings" permissionable="true">
            <label>Ratings</label>
            <record>
                <!-- name -->
                <field name="name" type="string">
                    <label>Name</label>
                </field>
            </record>
        </entity>
        <!-- AUTHORS -->
        <entity name="authors" permissionable="true">
            <label>Authors</label>
            <record>
                <!-- name -->
                <field name="name" type="string">
                    <label>Name</label>
                </field>
                <!-- created -->
                <field name="created" type="datetime">
                    <label>Date of creation</label>
                </field>
                <!-- email -->
                <field name="email" type="string">
                    <label>Authors personal mail</label>
                </field>
                <!-- birthdate -->
                <field name="birthdate" type="datetime">
                    <label>Birthdate</label>
                </field>
                <!-- about -->
                <field name="about" type="string">
                    <label>About</label>
                </field>
            </record>
        </entity>
        <!-- BOOKS -->
        <entity name="books" permissionable="true">
            <label>Books</label>
            <record>
                <!-- name -->
                <field name="name" type="string">
                    <label>Name</label>
                </field>
                <!-- created -->
                <field name="created" type="datetime">
                    <label>Date of creation</label>
                </field>
                <!-- isbn -->
                <field name="isbn" type="string">
                    <label>ISBN</label>
                </field>
                <!-- url -->
                <field name="url" type="string">
                    <label>URL</label>
                </field>
                <!-- price -->
                <field name="price" type="number">
                    <label>Last known price</label>
                </field>
                <!-- about -->
                <field name="about" type="string">
                    <label>About</label>
                </field>
                <!-- authors -->
                <field name="authors" type="select" related="authors">
                    <label>Author</label>
                </field>
                <!-- categories -->
                <field name="categories" type="select" related="categories">
                    <label>Category</label>
                </field>
                <!-- ratings -->
                <field name="ratings" type="select" related="ratings">
                    <label>Rating</label>
                </field>
            </record>
        </entity>
    </entities>
</datanest:section>

Element entities

Introduces a list of entities.

Element	Attribute	Description	Required
entities		list of entities in the Datanest section	Yes

Example:

<datanest:section xmlns:datanest="https://blueprint.retailys.com/blueprint.xsd">
    <entities>
        <!-- Entity ... -->
    </entities>
</datanest>

Element entity

Describes an entity, contains field elements that describe the entity's items.

Element	Attribute	Values	Description	Multiple	Required
entity			Entity, contains a list of entity items	Yes	Yes
	name	string	Entity name, limited to 15 characters!		Yes
	permissionable	true/false	Permission to set access rights		No

Contains	Attribute	Description	Multiple	Required
label		Extended name, used for example in the menu	No	No
	lang	ISO language code, e.g. cs, en, es, fr, ...		No
description		Entity description	Yes	No
	lang	ISO language code, e.g. cs, en, es, fr, ...		No
record		Record containing a list of fields, field elements	No	No

Example:

<!-- CATEGORIES -->
<entity name="categories" permissionable="true">
    <label>Categories</label>
    <record>
        <!-- name -->
        <field name="name" type="string">
            <label>Name</label>
        </field>
    </record>
</entity>

Element field

Describes an entity field.

Element	Attribute	Values	Description	Multiple	Required
field			Entity field	Yes	Yes
	name	string	Field name, limited to 15 characters!	No	Yes
	type		Field data type	No	No
		string	UTF-8 string
		number	Float or integer number
		datetime	Date and time in YYYY-MM-DD format
		money	FLOAT number with decimal point
		select	List
		file	File, binary blob
		uuid	UUID format ID

Common field elements

Element	Attribute	Values	Description	Multiple	Required
field			Entity field	Yes	Yes
	name		Field name, limited to 15 characters!	No	Yes
	type		Field data type	No	No
	editable		Allows disabling field editing on the client side	No	No
	multiset	true/false	Transforms the field into a list of values of the given type	No	No
	multilang	true/false	Allows entering different language mutations into the field at once	No	No
	unique	true/false	Field value must be unique within the entity	No	No
	required	true/false	Item must be filled in, cannot be empty	No	No
	related	string	Entity setting in relation	No	No
	cardinality	0, 1	Item must be filled in, cannot be empty	No	No

Note: The cardinality attribute is only meaningful together with the related attribute.

Some of the attributes listed here can only be used with certain field data types, the following table shows their overview:

Attribute	Can be used with data type
multiset	string, number, datetime
multilang	string
related	Data type is internally changed to uuid

Example:

<field name="ident" type="string" maxLength=15 required="true"/>
<field name="phone" type="string" pattern="[0-9]{3}-[0-9]{6}" multiset="true"/>

Relationships between entities through fields with the related and cardinality attributes

How to create relationships using the related and cardinality attributes on the field element:

• Many-to-many relationship

Field type string

Field for storing a UTF-8 string

Allowed parameter combinations besides those common to all fields:

Element	Attribute	Values	Description	Multiple	Required
field			Field of type string	Yes	Yes
	name	string	Entity name, limited to 15 characters!		Yes
	type	"string"	Data type string		Yes
	pattern	regex	Allowed pattern		No
	minLength	int	Minimum string length		No
	maxLength	int	Maximum string length		No

Example:

<field name="ident" type="string" maxLength=15/>
<field name="phone" type="string" pattern="[0-9]{3}-[0-9]{6}"/>

Field type number

Field for storing a FLOAT number.

Allowed parameter combinations besides those common to all fields:

Element	Attribute	Values	Description	Multiple	Required
field			Field of type number	Yes	Yes
	name	string	Entity name, limited to 15 characters!		Yes
	type	"number"	Data type string		No
	minValue	int	Minimum number value		No
	maxValue	int	Maximum number value		No

Example:

<field name="room_size" type="number" minValue="2" maxValue="4"/>

Field type money

Field for storing a currency value

Allowed parameter combinations besides those common to all fields:

Element	Attribute	Values	Description	Multiple	Required
field			Field of type money	Yes	Yes
	name	string	Entity name, limited to 15 characters!		Yes
	type	"money"	Data type money		No
	currency	string	ISO currency code		Yes
	minValue	int	Minimum number value		No
	maxValue	int	Maximum number value		No

Example:

<field name="price" type="money" currency="EUR" maxValue="100.00"/>

Field type datetime

Field for storing date and time, default format is YYYY-MM-DDTHH:MM, which can be changed with the format attribute.

Allowed parameter combinations besides those common to all fields:

Element	Attribute	Values	Description	Multiple	Required
field			Field of type datetime	Yes	Yes
	name	string	Entity name, limited to 15 characters!		Yes
	type	"datetime"	Data type datetime		No
	format	ISO datetime format	ISO date and time format		Yes
	minValue	int	Minimum date and time value in the corresponding format		No
	maxValue	int	Maximum date and time value in the corresponding format		No

Example:

<field name="year" type="datetmie" format="YYYY" minValue="2001"/>

Field type select

Field defining a selection list. It is a list of pairs (code, name).

Allowed parameter combinations besides those common to all fields:

Element	Attribute	Values	Description	Multiple	Required
field			Field of type select	Yes	Yes
	name	string	Entity name, limited to 15 characters!		Yes
	type	"select"	Data type select		No
	default	string	Name of the default selected item		No
	related	int	Minimum date and time value in the corresponding format		Yes
	constraint	"none", "delete", "stop"	How to handle related objects		No

Example:

<!-- Creates a many-to-many relationship between authors and the owner of the field (books) -->
<field name="authors" type="select" related="authors"/>
<!-- Creates a one-to-many relationship between authors and the owner of the field -->
<field name="authors" type="select" related="authors" cardinality="1"/>

Element label

Element defines the field label

Element	Attribute	Values	Description	Multiple	Required
label			Field label	Yes	No
	lang	ISO language code	Language code	No	No

Example:

<field name="field" type="string">
    <label lang="cs">Kategorie</label>
    <label lang="en">Categories</label>
</field>

Element description

Element defines a more detailed description of the field

Element	Attribute	Values	Description	Multiple	Required
desc/description			Field description	Yes	No
	lang	ISO language code	Language code	No	No

Example:

<field name="field" type="string">
    <desc lang="cs">Kategorie</desc>
    <desc lang="en">Categories</desc>
</field>

Element example

Element defines a usage example

Element	Attribute	Values	Description	Multiple	Required
example			Usage example	Yes	No

Example:

<field name="field" type="string">
    <example>Kategorie</example>
    <example>Categories</example>
</field>

Element dependence

Element defines a dependency on another record field

Element	Attribute	Values	Description	Multiple	Required
dependence			Dependency on another field	Yes	No
	on		Dependent item	No	Yes

Example:

<field name="field" type="string">
    <dependence on="category_type"/>
</field>