CDT Naming Convention: The CDT name should closely match the underlying database table/view name using camel case.

Example: For a database table named AV_APPIAN_VERSE, the CDT name would be AV_appianVerse.

Data Store Entity Name: The data store entity name must match the CDT name exactly.

Example: If the CDT is named avAppianVerse, the data store entity is also named avAppianVerse.

CDT Mapped to a View: For a view, the CDT name should use camel case, exclude the VW prefix (if applicable), and end with the suffix View.

Example: For a database view named VW_USER_ACCOUNT, the CDT name would be userAccountView.

Column Name Length: Specify column names no more than 27 characters to maintain clarity and readability and avoid automatic truncation by the system.

Example: Instead of transaction_identification_number, use transactionIdNum or transactionIdentifier.

CDT Namespace: Use a custom namespace to group CDTs for a specific application.

Example: urn:usac:av (where usac is the organization and av is the Appian Verse application prefix).

CDT Description: Include the source database Table or View name in the CDT description for clarity.

Example: In the CDT properties, the description field would contain Mapped to database table AV_APPIAN_VERSE.

CDT Field Names: Field names should match the table/view column names and be camel cased.

Example: A database column FIRST_NAME maps to the CDT field name firstName.

CDT Implementation Best Practices

JPA Annotations: CDTs should use JPA annotations (@Table, @Column, @JoinColumn) to explicitly map the CDT and its elements to the database, which avoids issues with automatic naming and truncation.
Example: In the XSD, use the @Column annotation:

xml

<xsd:element name="firstName" nillable="true" type="xsd:string">

<xsd:annotation>

<xsd:appinfo source="appian.jpa">@Column(name="FIRST_NAME")</xsd:appinfo>

</xsd:annotation>

</xsd:element>

Use code with caution.

Nesting CDTs: Avoid nesting CDTs more than one level deep unless specifically reviewed with a technical lead. Prefer flat relationships for performance.

Example (Preferred Flat Design): Instead of nesting the entire Address CDT within the Employee CDT, include only the primary key reference (e.g., addressId as an Integer) and use a separate Address CDT for address details.

Querying Multiple Criteria: When creating a query with multiple optional criteria, use a single expression rule with the ignoreFiltersWithEmptyValues parameter set to true on the logical expression (e.g., a!queryLogicalExpression(logicalOperator: "AND", filters: { ... }, ignoreFiltersWithEmptyValues: true)).

Limit Field Count: All CDTs should contain no more than 50-100 fields to avoid performance issues and make them easier to maintain. Consider breaking larger data structures into smaller, related CDTs.

Avoid Primitive Type Arrays: Do not use arrays of primitive types (like integer or string arrays) within a CDT mapped to a database, as they are treated as one-to-many relationships and cannot be updated correctly. Instead, create a new CDT to hold the array data and link it with a foreign key relationship.