Cloud Software Group, Inc. EBX®
Documentation > Developer Guide > Data model
Navigation mode Documentation > Developer Guide > Data model

# Data types

This chapter details the data types supported by TIBCO EBX®.

##### See also

- Tables and relationships

## XML Schema built-in simple types

The table below lists all the simple types defined in XML Schema that are supported by EBX®, along with their corresponding Java types.

XML Schema type | Java class | Notes
--- | --- | ---
`xs:string` | `java.lang.String` | The default strategies defined for string fields are detailed in the section Default strategy for string fields.
`xs:boolean` | `java.lang.Boolean` |
`xs:decimal` | `java.math.BigDecimal` | A `totalDigits` facet with a value equal to 15 is added by default to decimal fields that are contained in a mapped table (historized or replicated table). However, this facet can be overwritten with a greater value in the data model.
`xs:dateTime` | `java.util.Date` |
`xs:time` | `java.util.Date` | The date portion of the returned `Date` is always set to '1970/01/01'.
`xs:date` | `java.util.Date` | The time portion of the returned `Date` is always the beginning of the day, that is, '00:00:00'.
`xs:anyURI` | `java.net.URI` |
`xs:Name` (`xs:string` restriction) | `java.lang.String` |
`xs:int` (`xs:decimal` restriction) | `java.lang.Integer` |
`xs:integer` (`xs:decimal` restriction) | `java.lang.Integer` | This mapping does not comply with the XML Schema recommendation. Although the XML Schema specification states that `xs:integer` has no value space limitation, this value space is, in fact, restricted by the Java specifications of the `java.lang.Integer` object.

The mapping between XML Schema types and Java types are detailed in the section Mapping of data types.

## XML Schema named simple types

Named simple types can be defined when designing a data model for redefining an existing built-in simple type. A named simple type can be reused in the data model.

Restrictions:

- In the data model, only the element `restriction` is allowed in a named simple type, and even then, only derivation by restriction is supported. Notably, the elements `list` and `union` are not supported.

- Facet definition is not cumulative. That is, if an element and its named type both define the same kind of facet, then the facet defined in the type is overridden by the local facet definition.

  However, this restriction does not apply to programmatic facets defined by the element `osd:constraint`. For `osd:constraint`, if an element and its named type both define a programmatic facet with different Java classes, the definition of these facets will be cumulative.

  Contrary to the XML Schema Specification, EBX® is not strict regarding the definition of a facet of the same kind in an element and its named type. That is, the value of a same kind of facet defined in an element is not checked according to the one defined in the named type. However, in the case of static enumerations defined both in an element and its type, the local enumeration will be replaced by the intersection between these enumerations.

- It is not possible to define different types of enumerations on both an element and its named type. For instance, you cannot specify a static enumeration in an element and a dynamic enumeration in its named type.

- It is not possible to simultaneously define a pattern facet in both an element and its named type.

## XML Schema complex types

Complex types can be defined when designing a data model. A named complex type can be reused in the data model.

Restrictions:

- In the data model, only the element `sequence` is allowed. Notably, attribute definition is not supported.

- Type extensions are not supported in the current version of EBX®.

## Extended simple types defined by EBX®

EBX® provides pre-defined simple data types:

XML Schema type | Java class
--- | ---
`osd:text` (`xs:string` restriction) | `java.lang.String`
`osd:html` (`xs:string` restriction) | `java.lang.String`
`osd:email` (`xs:string` restriction) | `java.lang.String`
`osd:password` (`xs:string` restriction) | `java.lang.String`
`osd:color` (`xs:string` restriction) | `java.lang.String`
`osd:resource` (`xs:anyURI` restriction) | internal class
`osd:locale` (`xs:string` restriction) | `java.util.Locale`
`osd:dataspaceKey` (`xs:string` restriction) | `java.lang.String`
`osd:datasetName` (`xs:string` restriction) | `java.lang.String`

The above types are defined by the internal schema `common-1.0.xsd`. They are defined as follows:

`osd:text` | This type represents textual information. Its default user interface in EBX® consists of a dedicated editor with several lines for input and display. The use of this data type is intended for very long texts; this is why the `'Text'` search strategy is associated with this type, and cannot be modified. As a consequence, fields of type `osd:text` cannot benefit from sorting; moreover, their indexing strategy and search results differ from those of the `xs:string` type. See Default strategy for string fields for more information.
    <xs:simpleType name="text">
    	<xs:restriction base="xs:string" />
    </xs:simpleType>
`osd:html` | This represents a character string with HTML formatting. A WYSIWYG editor is provided in EBX®.
    <xs:simpleType name="html">
    	<xs:restriction base="xs:string" />
    </xs:simpleType>
`osd:email` | This represents an email address as specified by the RFC822 standard.
    <xs:simpleType name="email">
    	<xs:restriction base="xs:string" />
    </xs:simpleType>
`osd:password` | This represents a hashed or encrypted password. A specific editor is provided in EBX®.
    <xs:element name="password" type="osd:password" />
The default editor performs a hash computation using the SHA-512 algorithm. This encryption function is also available from a Java client using the method `DirectoryDefault.encryptString`. It is also possible for the default editor to use a different encryption mechanism by specifying a class that implements the interface `Encryption`.
    <xs:element name="password" type="osd:password">
    	<xs:annotation>
    		<xs:appinfo>
    			<osd:uiBean class="com.orchestranetworks.ui.UIPassword">
    				<encryptionClass>package.EncryptionClassName</encryptionClass>
    			</osd:uiBean>
    		</xs:appinfo>
    	</xs:annotation>
    </xs:element>
It is possible to specify some salt by referencing a path to another field, and by using a class the implements the interface `HashComputation`.
    <xs:element name="password" type="osd:password">
    	<xs:annotation>
    		<xs:appinfo>
    			<osd:uiBean class="com.orchestranetworks.ui.UIPassword">
    				<encryptionClass>package.HashClassName</encryptionClass>
    				<saltPath>../login</saltPath>
    			</osd:uiBean>
    		</xs:appinfo>
    	</xs:annotation>
    </xs:element>
`osd:locale` | This represents a geographical, political or cultural location. The locale type is translated into Java by the class `java.util.Locale`.
    <xs:simpleType name="locale">
    	<xs:restriction base="xs:string">
    		<xs:enumeration value="ar" osd:label="Arabic" />
    		<xs:enumeration value="ar_AE" osd:label="Arabic (United Arab Emirates)" />
    		<xs:enumeration value="ar_BH" osd:label="Arabic (Bahrain)" />
    		<xs:enumeration value="ar_DZ" osd:label="Arabic (Algeria)" />
    		<xs:enumeration value="ar_EG" osd:label="Arabic (Egypt)" />
    		<xs:enumeration value="ar_IQ" osd:label="Arabic (Iraq)" />
    			...
    		<xs:enumeration value="vi_VN" osd:label="Vietnamese (Vietnam)" />
    		<xs:enumeration value="zh" osd:label="Chinese" />
    		<xs:enumeration value="zh_CN" osd:label="Chinese (China)" />
    		<xs:enumeration value="zh_HK" osd:label="Chinese (Hong Kong)" />
    		<xs:enumeration value="zh_TW" osd:label="Chinese (Taiwan)" />
    	</xs:restriction>
    </xs:simpleType>
`osd:color` | This represents a character string with hexadecimal RGB color formatting. A color picker `UIComponent` is provided in EBX®.
    <xs:simpleType name="color">
    	<xs:restriction base="xs:string" />
    </xs:simpleType>
`osd:resource` | This represents a resource packaged in a module. For more information, see Packaged resources. This type requires the definition of the facet FacetOResource.
    <xs:simpleType name="resource">
    	<xs:restriction base="xs:anyURI" />
    </xs:simpleType>
`osd:dataspaceKey` | This type represents a reference to a dataspace.
    <xs:element name="dataspaceField" type="osd:dataspaceKey" />
A specific editor is provided in EBX® that displays the dataspaces that can be referenced. It is possible to specify the dataspaces that can be referenced using the element `osd:dataspaceSet` under `xs:annotation/xs:appInfo`. If the element `osd:dataspaceSet` is not defined, then by default, only open branches can be referenced.
    <xs:element name="dataspaceField" type="osd:dataspaceKey">
    	<xs:annotation>
    		<xs:appinfo>
    			<osd:dataspaceSet>
    				<include>
    					<pattern>a pattern</pattern>
    					<type>all | branch | version</type>
    					<includeDescendants>none | allDescendants | allBranchDescendants | allSnapshotDescendants | branchChildren | snapshotChildren</includeDescendants>
    				</include>
    				<exclude>
    					<pattern>a pattern</pattern>
    					<type>all | branch | version</type>
    					<includeDescendants>none | allDescendants | allBranchDescendants | allSnapshotDescendants | branchChildren | snapshotChildren</includeDescendants>
    				</include>
    				<filter osd:class="com.foo.MyDataspaceFilter">
    					<param1>...</param1>
    					<param2>...</param2>
    				</filter>
    			</osd:dataspaceSet>
    		</xs:appinfo>
    	</xs:annotation>
    </xs:element>
includes Specifies the dataspaces that can be referenced by this field. An `include` must at least be defined. `pattern`: Specifies a pattern that filters dataspaces. The pattern is checked against the name of the dataspaces. This property is mandatory. `type`: Specifies the type of dataspaces that can be referenced by this field. If not defined, this restriction is applied to branches. If `all` then branches and snapshots are included. If `branch` then only branches are included. If `snapshot` then only snapshots are included. If not set, this property is `branch` by default. `includeDescendants`: Specifies if children or descendants of the dataspaces that match the specified pattern are included in the set. If `none` then neither children nor descendants of the dataspaces that match the specified pattern are included. If `allDescendants` then all descendants of the dataspaces that match the specified pattern are included. If `allBranchDescendants` then all descendant branches of the dataspaces that match the specified pattern are included. If `allSnapshotDescendants` then all descendant snapshots of the dataspaces that match the specified pattern are included. If `directBranchChildren` then only direct branches of the dataspaces that match the specified pattern are included. If `directSnapshotChildren` then only direct snapshots of the dataspaces that match the specified pattern are included. If not set, this property is `none` by default. excludes Specifies the dataspaces that cannot be referenced by this field. Excludes are ignored if no includes are defined. `pattern`: Specifies a pattern that filters dataspaces. The pattern is checked against the name of the dataspaces. This property is mandatory. `type`: Specifies the type of dataspaces that can be referenced by this field. If not defined, this restriction is applied to branches. If `all` then branches and snapshots are excluded. If `branch` then only branches are excluded. If `snapshot` then only snapshots are excluded. If not set, this property is `branch` by default. `includeDescendants`: Specifies if children or descendants of the datasets that match the specified pattern are excluded from the set. If `none` then neither children nor descendants of the dataspaces that match the specified pattern are excluded. If `allDescendants` then all descendants of the dataspaces that match the specified pattern are excluded. If `allBranchDescendants` then all descendant branches of the dataspaces that match the specified pattern are excluded. If `allSnapshotDescendants` then all descendant snapshots of the dataspaces that match the specified pattern are excluded. If `directBranchChildren` then only direct branches of the dataspaces that match the specified pattern are excluded. If `directSnapshotChildren` then only direct snapshots of the dataspaces that match the specified pattern are excluded. If not set, this property is `none` by default. `filter` Specifies a filter to accept or reject dataspaces in the context of a dataset or a record. This filter is only used in the dedicated input component that is associated to this field. That is, this filter is not used when validating this field. A specific constraint can be used to perform specific controls on this field. The attribute `osd:class` specifies a Java bean that implements the interface `DataspaceSetFilter`. It is also possible to customize validation messages and the control policy associated with this type using the element `validation` under `xs:annotation/xs:appInfo/osd:dataspaceSet`. See Facet validation message with severity and Control policy for more information.
`osd:datasetName` | This type represents a reference to a dataset.
    <xs:element name="dataset" type="osd:datasetName" />
A specific editor provided in EBX® displays the datasets that can be referenced. It is also possible to specify the datasets that can be referenced using the element `osd:datasetSet` under `xs:annotation/xs:appInfo`:
    <xs:element name="datasetField" type="osd:datasetName">
    	<xs:annotation>
    		<xs:appinfo>
    			<osd:datasetSet>
    				<branch>productsBranch</branch>
    				<version>productsVersion</version>
    				<dataspaceSelector>../dataspaceField</dataspaceSelector>
    				<pattern>a pattern</pattern>
    				<filter osd:class="com.foo.MyDatasetFilter">
    					<param1>...</param1>
    					<param2>...</param2>
    				</filter>
    			</osd:datasetSet>
    		</xs:appinfo>
    	</xs:annotation>
    </xs:element>
`branch` Specifies the source branch. Only datasets contained in this branch will be able to be selected by a field of the type Dataset identifier (osd:datasetName). `version` Specifies the source snapshot. Only datasets contained in this snapshot will be able to be selected by a field of the type Dataset identifier (osd:datasetName). `dataspaceSelector` Specifies a field in the same data model that defines the dataspace containing the datasets that can be referenced. The specified field must be of type `xs:string` or `osd:dataspaceKey`. The value of this field must comply with the representation of a persistent identifier of a dataspace or snapshot. The referred node must respect the restrictions existing for dynamic facets. ##### See also `HomeKey.format` Dynamic constraints `includes` Specifies the datasets that can be referenced by this field. `pattern`: Specifies a pattern that filters datasets. The pattern is checked against the name of the datasets. This property is mandatory. `includeDescendants`: Specifies if children or descendants of the datasets that match the specified pattern are included in the set. If `none` then neither children nor descendants of the datasets that match the specified pattern are excluded. If `directChildren` then only direct children of the datasets that match the specified pattern are excluded. If `allDescendants` then all descendants of the datasets that match the specified pattern are excluded. If not set, this property is `none` by default. `excludes` Specifies the datasets that cannot be referenced by this field. Excludes are ignored if no includes are defined. `pattern`: Specifies a pattern that filters datasets. The pattern is checked against the name of the datasets. This property is mandatory. `includeDescendants`: Specifies if children or descendants of the datasets that match the specified pattern are included in the set. If `none` then neither children nor descendants of the datasets that match the specified pattern are excluded. If `directChildren` then only direct children of the datasets that match the specified pattern are excluded. If `allDescendants` then all descendants of the datasets that match the specified pattern are excluded. If not set, this property is `none` by default. `filter` Specifies a filter to accept or reject datasets in the context of a dataset or record. This filter is only used in the dedicated input component that is associated to this field. That is, this filter is not used when validating this field. A specific constraint can be used to perform specific controls on this field. The attribute `osd:class` specifies a Java bean that implements the interface `DatasetSetFilter`. A validation message is added to the associated field if an input dataspace reference does not match this filter. One of the elements `branch`, `version` or `dataspaceSelector` must be defined. It is also possible to customize validation messages and the control policy associated with this type using the element `validation` under `xs:annotation/xs:appInfo/osd:datasetSet`. See Facet validation message with severity and Control policy for more information.

## Complex types defined by EBX®

EBX® provides pre-defined complex data types:

XML Schema type | Description
--- | ---
`osd:UDA` | User Defined Attribute: This type allows any user, according to their access rights, to define a value associated with an attribute defined in a dictionary called a UDA Catalog.
`osd:UDACatalog` | Catalog of User Defined Attributes: This type consists of a table in which attributes can be specified. This catalog is used by all `osd:UDA` elements declared in the same data model.

`osd:UDA` | A User Defined Attribute (UDA) supports both the `minOccurs` and `maxOccurs` attributes, as well as the attribute `osd:UDACatalogPath`, which specifies the path of the corresponding catalog.
    <xs:element name="firstUDA" type="osd:UDA" minOccurs="0"
    	maxOccurs="unbounded" osd:UDACatalogPath="//insuranceCatalog" />
    <xs:element name="secondUDA" type="osd:UDA" minOccurs="1" maxOccurs="1"
    	osd:UDACatalogPath="/root/userCatalog" />
    <xs:element name="thirdUDA" type="osd:UDA" minOccurs="0" maxOccurs="1"
    	osd:UDACatalogPath="//userCatalog" />
In the manager, when working with a UDA, the editor will adapt itself to the type of the selected attribute.
`osd:UDACatalog` | Internally, a catalog is represented as a table. The parameters `minOccurs` and `maxOccurs` must be specified. Several catalogs can be defined in the same data model.
    <xs:element name="insuranceCatalog" type="osd:UDACatalog" minOccurs="0" maxOccurs="unbounded">
    	<xs:annotation>
    		<xs:documentation xml:lang="en-US">Insurance Catalog.</xs:documentation>
    		<xs:documentation xml:lang="fr-FR">Catalog assurance.</xs:documentation>
    	</xs:annotation>
    </xs:element>
    <xs:element name="userCatalog" type="osd:UDACatalog" minOccurs="0" maxOccurs="unbounded">
    	<xs:annotation>
    		<xs:documentation xml:lang="en-US">User catalog.</xs:documentation>
    		<xs:documentation xml:lang="fr-FR">Catalogue utilisateur.</xs:documentation>
    	</xs:annotation>
    </xs:element>
Only the following types are available for creating new attributes: xs:string xs:boolean xs:decimal xs:dateTime xs:time xs:date xs:anyURI xs:Name xs:int osd:html osd:email osd:password osd:locale osd:text

### Restrictions on User Defined Attributes and Catalogs

The following features are unsupported on UDA elements:

- Facets

- Functions using the `osd:function` property

- UI bean editors using the `osd:uiBean` property

- The `osd:checkNullInput` property

- History features

- Replication

- Inheritance features, using the `osd:inheritance` property

As UDA catalogs are internally considered to be tables, the restrictions that apply to tables also exist for `UDACatalog` elements.

## Aggregated lists

In XML Schema, the maximum number of times an element can occur is determined by the value of the `maxOccurs` attribute in its declaration. If this value is strictly greater than 1 or is `unbounded`, the data can have multiple occurrences. If no `osd:table` declaration is included, this element is called an aggregated list.

In Java, it is then represented as an instance of the class `java.util.List`.

The following is an example of an aggregated list that defines the pricing of a loan product, depending on the amount borrowed.

    <xs:element name="pricing" minOccurs="0" maxOccurs="unbounded"
    	osd:access="RW">
    	<xs:annotation>
    		<xs:documentation>
    			<osd:label>Pricing</osd:label>
    			<osd:description>Pricing grid </osd:description>
    		</xs:documentation>
    	</xs:annotation>
    	<xs:complexType>
    		<xs:sequence>
    			<xs:element name="amount" type="xs:int">
    				<xs:annotation>
    					<xs:documentation>
    						<osd:label>Amount borrowed</osd:label>
    					</xs:documentation>
    				</xs:annotation>
    			</xs:element>
    			<xs:element name="monthly" type="xs:int">
    				<xs:annotation>
    					<xs:documentation>
    						<osd:label>Monthly payment </osd:label>
    					</xs:documentation>
    				</xs:annotation>
    			</xs:element>
    			<xs:element name="cost" type="xs:int">
    				<xs:annotation>
    					<xs:documentation>
    						<osd:label>Cost</osd:label>
    					</xs:documentation>
    				</xs:annotation>
    			</xs:element>
    		</xs:sequence>
    	</xs:complexType>
    </xs:element>

Aggregated lists have a dedicated editor in EBX®. This editor allows you to add or to delete occurrences.

##### Attention

The addition of an `osd:table` declaration to an element with `maxOccurs > 1` is a very important consideration that must be taken into account during the design process. An aggregated list is severely limited with respect to the many features that are supported by tables. Some features unsupported on aggregated lists that are supported on tables are:

- Performance and memory optimization;

- Lookups, filters and searches;

- Sorting, view and display in hierarchies;

- Identity constraints (primary keys and uniqueness constraints);

- Detailed permissions for creation, modification, deletion and particular permissions at the record level;

- Detailed comparison and merge.

Thus, aggregated lists should be used only for small volumes of simple data (one or two dozen occurrences), with no advanced requirements. For larger volumes of data or more advanced functionalities, it is strongly advised to use an `osd:table` declaration.

For more information on table declarations, see Tables and relationships.

## Including external data models

Including another data model in your current model allows you to use the reusable types that are defined in that data model. You can thus use the inclusion of external data models to share data types between multiple XML Schema Documents.

To include another XML Schema Document in your model, thereby including the data types that it defines, specify the `xs:include` element as follows:

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    		xmlns:osd="urn:ebx-schemas:common_1.0" xmlns:fmt="urn:ebx-schemas:format_1.0">
      	<xs:include 	schemaLocation="./schemaToInclude.xsd"/>
    	...
    </xs:schema>

The attribute `schemaLocation` is mandatory and must specify either an absolute or a relative path to the XML Schema Document to include.

The inclusion of XML Schema Documents is not namespace aware, thus all included data types must belong to the same namespace. As a consequence, including XML Schema Documents that define data types of the same name is not supported.

EBX® includes extensions with specific URNs for including embedded data models and data models packaged in modules.

To include an embedded data model in a model, specify the URN defined by EBX®. For example:

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    		xmlns:osd="urn:ebx-schemas:common_1.0" xmlns:fmt="urn:ebx-schemas:format_1.0">
    	<xs:include schemaLocation="urn:ebx:publication:myPublication"/>
    	...
    </xs:schema>

To include a data model packaged in a module, specify the specific URN defined by EBX®. For example:

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    		xmlns:osd="urn:ebx-schemas:common_1.0" xmlns:fmt="urn:ebx-schemas:format_1.0">
    	<xs:include schemaLocation="urn:ebx:module:aModuleName:/WEB-INF/ebx/schema/myDataModel.xsd"/>
    	...
    </xs:schema>

See `SchemaLocation` for more information about specific URNs supported by EBX®.

##### Note

If the packaged data model uses Java resources, the class loader of the module containing the data model will be used at runtime for resolving these resources.

Documentation > Developer Guide > Data model