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

# Labels and messages

TIBCO EBX® allows to have custom labels and error messages for data models to be displayed in the interface.

## Label and description

A label and a description can be added to each node in a data model. In EBX®, each node is displayed with its label. If no label is defined, the name of the element is used.

Two different notations can be used:

Full | The label and description are defined by the elements `<osd:label>` and `<osd:description>` respectively.
Simple | The label is extracted from the text content, ending at the first period ('`.`'), with a maximum of 60 characters. The description uses the remainder of the text.

The description may also have a hyperlink, either a standard HTML `href` to an external document, or a link to another node of the adaptation within EBX®.

- When using the `href` notation or any other HTML, it must be properly escaped.

- EBX® link notation is not escaped and must specify the path of the target, for example:

  `<osd:link path="../misc1">Link to another node in the adaptation</osd:link>`

Example:

    <xs:element name="misc1" type="xs:string">
    	<xs:annotation>
    		<xs:documentation>
    			Miscellaneous 1. This is the description of miscellaneous element #1.
    			Click <a href="https://www.tibco.com" target="_blank">here</a>
    			to learn more.
    		</xs:documentation>
    	</xs:annotation>
    </xs:element>
    <xs:element name="misc2" type="xs:string">
    	<xs:annotation>
    		<xs:documentation>
    			<osd:label>
    				Miscellaneous 2
    			</osd:label>
    			<osd:description>
    				This is the miscellaneous element #2 and here is a
    				<osd:link path="../misc1"> link to another node in the
    					adaptation</osd:link>.
    			</osd:description>
    		</xs:documentation>
    	</xs:annotation>
    </xs:element>

If a node points to a named type, then the label of the node replaces the label of the named type. The same mechanism applies to the description of the node (element `osd:description`).

##### Note

Regarding whitespace management, the label of a node is always collapsed when displayed. That is, contiguous sequences of blanks are collapsed to a single blank, and leading and trailing blanks are removed. In descriptions, however, whitespaces are always preserved.

### Dynamic labels and descriptions

As an alternative to statically defining the localized labels and descriptions for each node, it is possible to specify a Java class that programmatically determines the labels and descriptions for the nodes of the data model. To define the class, include the element `osd:documentation`, with the attribute `class` in the data model. It is possible to pass JavaBean properties using nested parameter elements.

Example:

    <xs:schema ...>
    	<xs:annotation>
    		<xs:appinfo>
    			<osd:documentation class="com.foo.MySchemaDocumentation">
    				<param1>...</param1>
    				<param2>...</param2>
    			</osd:documentation>
    		</xs:appinfo>
    	</xs:annotation>
    	...
    </xs:schema ...>

The labels and descriptions that are provided programmatically take precedence over the ones defined locally on individual nodes.

##### See also

- `SchemaDocumentation`

## Enumeration labels

In an enumeration, a simple, non-localized label can be added to each enumeration element, using the attribute `osd:label`.

##### Attention

Labels defined for an enumeration element are always `collapsed` when displayed.

Example:

    <xs:element name="Service" maxOccurs="unbounded">
    	<xs:simpleType>
    		<xs:restriction base="xs:string">
    			<xs:enumeration value="1" osd:label="Blue" />
    			<xs:enumeration value="2" osd:label="Red" />
    			<xs:enumeration value="3" osd:label="White" />
    		</xs:restriction>
    	</xs:simpleType>
    </xs:element>

It is also possible to fully localize the labels using the standard `xs:documentation` element. If both non-localized and localized labels are added to an enumeration element, the non-localized label will be displayed in any locale that does not have a label defined.

Example:

    <xs:element name="access" minOccurs="0">
    	<xs:simpleType>
    		<xs:restriction base="xs:string">
    			<xs:enumeration value="readOnly">
    				<xs:annotation>
    					<xs:documentation xml:lang="en-US">
    						read only
    					</xs:documentation>
    					<xs:documentation xml:lang="fr-FR">
    						lecture seule
    					</xs:documentation>
    				</xs:annotation>
    			</xs:enumeration>
    			<xs:enumeration value="readWrite">
    				<xs:annotation>
    					<xs:documentation xml:lang="en-US">
    						read/write
    					</xs:documentation>
    					<xs:documentation xml:lang="fr-FR">
    						lecture écriture
    					</xs:documentation>
    				</xs:annotation>
    			</xs:enumeration>
    			<xs:enumeration value="hidden">
    				<xs:annotation>
    					<xs:documentation xml:lang="en-US">
    						hidden
    					</xs:documentation>
    					<xs:documentation xml:lang="fr-FR">
    						masqué
    					</xs:documentation>
    				</xs:annotation>
    			</xs:enumeration>
    		</xs:restriction>
    	</xs:simpleType>
    </xs:element>

## Mandatory error message (osd:mandatoryErrorMessage)

If the node specifies the attribute `minOccurs="1"` (default behavior), then an error message, which must be provided, is displayed if the user does not complete the field. This error message can be defined specifically for each node using the element `osd:mandatoryErrorMessage`.

Example:

    <xs:element name="birthDate" type="xs:date">
    	<xs:annotation>
    		<xs:documentation>
    			<osd:mandatoryErrorMessage>
    				Please give your birth date.
    			</osd:mandatoryErrorMessage>
    		</xs:documentation>
    	</xs:annotation>
    </xs:element>

The mandatory error message can be localized:

    <xs:documentation>
    	<osd:mandatoryErrorMessage xml:lang="en-US">
    		Name is mandatory
    	</osd:mandatoryErrorMessage>
    	<osd:mandatoryErrorMessage xml:lang="fr-FR">
    		Nom est obligatoire
    	</osd:mandatoryErrorMessage>
    </xs:documentation>

##### Note

Regarding whitespace management, the enumeration labels are always collapsed when displayed.

## Conversion error message

For each predefined XML Schema element, it is possible to define a specific error message if the user entry has an incorrect format.

Example:

    <xs:element name="email" type="xs:string">
    	<xs:annotation>
    		<xs:documentation>
    			<osd:ConversionErrorMessage xml:lang="en-US">
    				Please enter a valid email address.
    			</osd:ConversionErrorMessage>
    			<osd:ConversionErrorMessage xml:lang="fr-FR">
    				Saisissez un e-mail valide.
    			</osd:ConversionErrorMessage>
    		</xs:documentation>
    	</xs:annotation>
    </xs:element>

## Facet validation message with severity

The validation message that is displayed when the value of a field does not comply with a constraint can define a custom severity, a default non-localized message, and localized message variants. If no severity is specified, the default level is `error`. Blocking constraints must have the severity `error`.

### XML Schema facet (osd:validation)

The validation message is described by the element `osd:validation` in `annotation/appinfo` under the definition of the facet.

Example:

    <xs:element name="zipCode">
    	<xs:simpleType>
    		<xs:restriction base="xs:string">
    			<!--facet is not localized, but validation message is localized-->
    			<xs:minInclusive value="01000">
    				<xs:annotation>
    					<xs:appinfo>
    						<osd:validation>
    							<severity>error</severity>
    							<message>Non-localized message.</message>
    							<message xml:lang="en-US">English error message.</message>
    							<message xml:lang="fr-FR">Message d'erreur en français.</message>
    						</osd:validation>
    					</xs:appinfo>
    				</xs:annotation>
    			</xs:minInclusive>
    		</xs:restriction>
    	</xs:simpleType>
    </xs:element>

### XML Schema enumeration facet (osd:enumerationValidation)

The validation message is described by the element `osd:enumerationValidation` in `annotation/appinfo` under the definition of the field.

Example:

    <xs:element name="Gender">
    	<xs:annotation>
    		<xs:appinfo>
    			<osd:enumerationValidation>
    				<severity>error</severity>
    				<message>Non-localized message.</message>
    				<message xml:lang="en-US">English error message.</message>
    				<message xml:lang="fr-FR">Message d'erreur en français.</message>
    			</osd:enumerationValidation>
    		</xs:appinfo>
    	</xs:annotation>
    	<xs:simpleType>
    		<xs:restriction base="xs:string">
    			<xs:enumeration value="0" osd:label="male" />
    			<xs:enumeration value="1" osd:label="female" />
    		</xs:restriction>
    	</xs:simpleType>
    </xs:element>

### EBX® facet (osd:validation)

The validation message is described by the element `osd:validation` under the definition of the facet (which is defined in `annotation/appinfo/otherFacets`).

Example:

    <xs:element name="price" type="xs:decimal">
    	<xs:annotation>
    		<xs:appinfo>
    			<osd:otherFacets>
    				<osd:minInclusive path="../priceMin">
    					<osd:validation>
    						<severity>error</severity>
    						<message>Non-localized message.</message>
    						<message xml:lang="en-US">English error message.</message>
    						<message xml:lang="fr-FR">Message d'erreur en français.</message>
    					</osd:validation>
    				</osd:minInclusive>
    			</osd:otherFacets>
    		</xs:appinfo>
    	</xs:annotation>
    </xs:element>

Documentation > Developer Guide > Data model