Field-level annotations for semantic types

In the Progress Developer Studio for OpenEdge Online Help, under the "Data Service Catalog schema properties" topic, a "Field property" topic describes how to code field-level annotations in a Business Entity (which in the existing documentation are referred to as field property annotations) as follows, indicating that a field property annotation, @openapi.openedge.entity.field.property, takes the following name/value parameters:

Parameter	Description
field	Specifies the name of the field in the schema.
name	Specifies the name of the property to be added at the field level.
value	Specifies the value of the property as a string. The value can also be a comma-delimited list of strings.
type	(Optional) Indicates the JSON data type used to generate the property in the Data Service Catalog file. The type parameter value can be "string", "integer", "boolean, or "array". Note: The default type value is "string". If type is "array", the generated JSON for value is a JSON array of strings, where each item in the array corresponds to each item in any comma-delimited list of strings specified for value.

@openapi.openedge.entity.field.property (field="Balance", name="readOnly", value="true", type="boolean")

In Release 11.6.3, you can use these field-level annotations to annotate the temp-tables that are part of the schema for a Business Entity with semantic types. A semantic type specifies the functional usage for a particular temp-table field, such as to store currency or date and time values. The following table describes the built-in semantic types provided by OpenEdge to annotate temp-table fields:

Table 1. The built-in semantic types available to annotate a temp-table field
Semantic type	Function
Boolean	Two (2) values
Currency	Decimal with currency symbol With localization override
Date	Date with no time With localization override
Datetime	Date and time with timezone support With localization override
Email	Text with single @ character delimiter
Integer	Integer value With localization override
Internal	Fields marked as internal are not displayed to the user
Number	Decimal with formatting options (separator, decimal points, etc.) With localization override
Password	Text displayed as hidden characters
Percent	Decimal x 100 (with % sign) Example: value in database = 0.255, represented as 25.5%
PercentValue	Decimal (with % sign) Example: value in database = 25.5, represented as 25.5%
PhoneNumber	Numbers, alpha characters, parentheses, and dashes With localization override
RichText	Multi-line, formatted text
Text	Single line of text Note: Data Object Services use UTF-8 as the content type.
URL	Click through hyperlink with alternate text

For example, to assign the semantic type named PhoneNumber to a temp-table field named Phone, you code the following semantic type annotation directly above the temp-table definition, as shown for a temp-table named ttCustomer (using bold to indicate the corresponding elements):

@openapi.openedge.entity.field.property (field="Phone", name="semanticType", value="PhoneNumber")

DEFINE TEMP-TABLE ttCustomer
FIELD Address AS CHARACTER LABEL "Address"
FIELD Balance AS DECIMAL INITIAL "0" LABEL "Balance"
FIELD City AS CHARACTER LABEL "City"
FIELD CustNum AS INTEGER INITIAL "0" LABEL "Cust Num"
FIELD Name AS CHARACTER LABEL "Name"
FIELD Phone AS CHARACTER LABEL "Phone"
FIELD State AS CHARACTER LABEL "State"
INDEX CustNum CustNum
INDEX Name Name.

You annotate ABL array (EXTENT) fields with exactly the same semantic type annotation as a scalar field (with any EXTENT). The maximum size of any array field is determined from the temp-table definition and saved as part of the field's schema in the Data Service Catalog.

All ABL field data types that are supported as part of the schema for a Data Object resource have a default semantic type. This means that if you accept the default semantic type for a given temp-table field, you have no need to specify a semantic type annotation for that field

Table 2. Default semantic types for the supported ABL field data types
ABL field data type	Semantic type default
CHARACTER	Text
CLOB	RichText
COM-HANDLE	Number
DATE	Date
DATETIME or DATETIME-TZ	DateTime
DECIMAL	Number
HANDLE	Number
INT64 or INTEGER	Integer
LOGICAL	Boolean
ROWID	Text

You can also use the Define Service Interface wizard in Developer Studio to add any semantic type annotations to a Business Entity temp-table definition, avoiding the need to manually code them. For more information, see Annotating Business Entity for Data Object Service.

Note: OpenEdge supports the option to create customized semantic types for use by the Kendo UI Builder to define data sources for web apps that are built with it. For more information, see Kendo UI Builder by Progress: Application Modernization.