Skip to content

Martini Data Model Property Types

Overview

Martini uses data models and properties to define structured data. Property types define what data each property can store, while their meta-properties control behavior during validation, serialization, and API exposure. Understanding these types and meta-properties helps you build robust data structures that integrate seamlessly with XML, JSON, YAML, and REST/SOAP web services.

What You Will Learn

After reading this guide, you'll know how to:

  • Choose from 15 property types and understand their Java equivalents
  • Configure essential meta-properties for naming, validation, and output formatting
  • Set up arrays with proper size limits and validation rules
  • Create smart validation using expressions, ranges, and dropdown choices
  • Handle dates, model inheritance, and integrate custom classes
  • Fix common issues and troubleshoot validation problems

When To Use This

This guide helps you when you're:

  • Creating clean, validated data structures for your REST or SOAP services
  • Ensuring your data looks right in JSON, XML, or YAML with proper naming
  • Setting up smart checks for user input with ranges, lengths, and custom rules
  • Building base templates that other models can extend and customize
  • Handling arrays and lists with the right size limits and validation

Prerequisites

Available Property Types

Martini provides 15 built-in property types that map to standard Java classes. Use this reference to choose the appropriate type for your data requirements.

Property Type Java Equivalent
BigDecimal java.math.BigDecimal
BigInteger java.math.BigInteger
Boolean java.lang.Boolean
Byte java.lang.Byte
ByteArray byte[]
Character java.lang.Character
Date java.util.Date
Double java.lang.Double
Float java.lang.Float
Integer java.lang.Integer
Long java.lang.Long
Model java.util.Map1
Object java.lang.Object
Short java.lang.Short
String java.lang.String

Selecting the Right Property Type

Choose property types based on your data requirements and performance needs:

Numeric Types: Use Integer for whole numbers, Double for decimals, BigDecimal for precise financial calculations, and Long for large numbers or timestamps.

Text and Characters: Use String for text data, Character for single characters, and ByteArray for binary data or file content.

Structured Data: Use Model for nested properties, Object for custom Java/Groovy classes, and Date for temporal data.

Logical Values: Use Boolean for true/false flags and conditional logic.

Meta-Properties Configuration Reference

Meta-properties control how properties behave during validation, serialization, and UI interaction. This reference shows which meta-properties are available for each property type.

Property Type Name Alias Comments Default Value Allow Null Type Array Min Array Size Max Array Size Required Namespace URI XML Attribute Validation Expression Output Expression Deprecated Min Max Min Length Max Length Choices Allow Other Values Date Formats XML Type Allow Extra Properties Reference Throw Error on Extra Property Object Class Name
BigDecimal ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
BigInteger ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Boolean ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Byte ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
ByteArray ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Character ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Date ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Double ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Float ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Integer ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Long ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Model ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Object ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
Short ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
String ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓

Core Identification Meta-Properties

These fundamental meta-properties define how properties are identified and accessed in your code and serialized data.

Name

The Name meta-property defines the identifier for your property as it appears in the Martini UI and Groovy code. This serves as your variable name when manipulating the property programmatically.

When the name contains reserved Java or Groovy keywords or invalid characters, Martini automatically creates an alias and prefixes the name with an underscore for code access. The original name remains in the Alias meta-property for serialization purposes.

Example: If you name a property class (a reserved keyword), Martini creates _class for code access while maintaining class for JSON/XML output.

Alias

The Alias meta-property stores the original property name used during serialization to JSON, XML, YAML, and flat files. This becomes essential when the Name meta-property has been sanitized for code compatibility.

When a property requires an alias, Martini displays it in parentheses after the name in the UI. For example, a property with Name _1invalidProperty and Alias 1invalidProperty appears as _1invalidProperty (1invalidProperty).

Code Access Example: 

1
2
3
4
5
// Access in Groovy code using the sanitized name
myModel._1invalidProperty = "value"

// Serializes using the original alias
// JSON: {"1invalidProperty": "value"}

Comments

The Comments meta-property allows you to add documentation and contextual information about a property. Comments support Markdown formatting and appear after the property name with // in Martini Designer.

Comments automatically transfer to your API documentation, making them valuable for API consumers and team members.

Best Practices:

  • Document the purpose and expected values for the property
  • Include examples of valid data formats
  • Note any business rules or constraints
  • Use Markdown for formatting complex explanations

Value and Validation Meta-Properties

These meta-properties control how properties handle values, defaults, and validation rules.

Default Value

The Default Value meta-property provides a fallback value when a property is null. This works similarly to field initialization in Java and applies to all property types except Data Models.

Example Configuration: 

1
// Equivalent to: Integer myNumber = 4;

Default values help ensure consistent data structure and reduce null-related errors in your services.

Allow Null

The Allow Null meta-property determines whether a property accepts null values. This setting primarily affects input/output validation for services when combined with the service's Validate Input or Validate Output settings.

Validation Behavior:

  • When unchecked (false): Shows error icons ( ) in Martini Designer and throws exceptions at runtime if validation is enabled
  • When checked (true): Permits null values without validation errors

Type

The Type meta-property displays the current property type and serves as a read-only reference. Use this to verify the selected property type matches your data requirements.

Array Configuration Meta-Properties

These meta-properties control array behavior and validation for collection-type properties.

Array

The Array meta-property determines whether the property behaves as a single value or a collection. When enabled, Martini displays an array overlay icon ( ) on the property.

Array Mapping Rules:

  • Array to Non-Array: Maps the first element from the array
  • Non-Array to Array: Clears the array and sets the mapped value as the first element
  • Empty Arrays: Considered valid unless minimum size validation is configured

Min Array Size

The Min Array Size meta-property sets the minimum required number of elements in an array. This validation only applies when the Array meta-property is enabled.

Configuration Example: 

1
Min Array Size: 1

If an array contains fewer elements than specified, Martini throws an exception when service input/output validation is enabled. Leave empty to skip this validation.

Max Array Size

The Max Array Size meta-property sets the maximum allowed number of elements in an array. This validation only applies when the Array meta-property is enabled.

Configuration Example: 

1
Max Array Size: 100

If an array exceeds the specified size, Martini throws an exception when service input/output validation is enabled. Leave empty to allow unlimited array size.

Serialization Control Meta-Properties

These meta-properties control how properties appear in serialized output formats like JSON, XML, and YAML.

Required

The Required meta-property determines whether a property appears in serialized output even when its value is null.

Serialization Behavior:

When Required is unchecked (false): Null properties are omitted from output

When Required is checked (true): Null properties serialize as:

1
2
// JSON
"myProperty": null

1
2
<!-- XML -->
<myProperty />

1
2
# YAML
myProperty:

Namespace URI

The Namespace URI meta-property declares XML namespaces when converting properties to XML format. Use this for XML documents that require specific namespace declarations for validation or processing.

Example Usage: 

1
Namespace URI: http://example.com/schema/v1

XML Attribute

The XML Attribute meta-property controls whether a property serializes as an XML attribute rather than an element. When enabled, Martini displays an XML attribute overlay icon ( ) on the property.

Serialization Comparison:

As Element (default): 

1
2
3
<parent>
    <property>value</property>
</parent>

As Attribute: 

1
2
<parent property="value">
</parent>

Output Expression

The Output Expression meta-property transforms values during serialization to different formats. This enables custom formatting like currency display, date formatting, or conditional output based on the target format.

Available Variables:

  • gloopObject: The actual property instance
  • val: The value to transform
  • index: Array index (null for non-arrays)
  • collection: The java.util.List for arrays (null for single values)
  • type: Target format (xml, json, yaml, csv, txt, xls)

Format-Specific Example: 

1
2
3
4
5
6
7
8
def expressions = [
    xml : val.toString().toLowerCase(),
    json : val.toString().toUpperCase(),
    csv : val.toString().trim(),
    txt : "Hello $val",
    xls : "Excel says $val"
]
return expressions[type]

Universal Formatting: 

1
val.toString().toLowerCase()

Advanced Validation Meta-Properties

These meta-properties provide sophisticated validation capabilities for properties.

Validation Expression

The Validation Expression meta-property enables custom validation logic using any supported scripting language. The expression must return a boolean value where true indicates valid data.

Available Variables:

  • gloopObject: The actual property instance
  • val: The value being validated (use _val in Kotlin)
  • index: Array index (null for non-arrays)
  • collection: The java.util.List for arrays (null for single values)

Example Validations:

Current Year Validation: 

1
new Date().getYear() == val.getYear()

Even Number Validation: 

1
val % 2 == 0

Validation expressions run for each element in arrays and require service input/output validation to be enabled for exception throwing.

Deprecated

The Deprecated meta-property marks properties as outdated and shows warnings when used in model references or mappings. Use this to phase out properties while maintaining backward compatibility.

Range Validation Meta-Properties

These meta-properties provide range validation for applicable property types.

Min

The Min meta-property sets the lowest acceptable value for supported property types. At runtime, values below this threshold trigger exceptions.

Example Configuration: 

1
Min: 0

This ensures minimum acceptable values for properties like quantities, percentages, or character codes.

Max

The Max meta-property sets the highest acceptable value for supported property types. At runtime, values above this threshold trigger exceptions.

Example Configuration: 

1
Max: 100

Combined with Min, this creates bounded ranges like percentages (0-100), ratings (1-5), or valid value ranges.

String Validation Meta-Properties

These meta-properties provide length validation for String properties.

Min Length

The Min Length meta-property sets the minimum character count for String values. Use this to enforce requirements like password length or required field completion.

Example Configuration: 

1
Min Length: 8

Max Length

The Max Length meta-property sets the maximum character count for String values. Use this to prevent data overflow or enforce database field limits.

Example Configuration: 

1
Max Length: 255

Choice-Based Validation Meta-Properties

These meta-properties provide enumeration-like behavior for most property types, restricting values to predefined lists.

Choices

The Choices meta-property creates enum-like behavior by restricting values to a predefined list. Martini displays these choices as dropdown options in the UI instead of text fields.

Configuration Example: 

1
Choices: ["active", "inactive", "pending"]

This ensures data consistency and provides better user experience through guided input.

Allow Other Values

The Allow Other Values meta-property works with Choices to determine whether users can enter values outside the predefined list.

Behavior Options:

  • Unchecked (false): Restricts input to choices only; throws exceptions for other values
  • Checked (true): Shows choices as suggestions but allows custom input via text field

Date-Specific Meta-Properties

These meta-properties handle Date object parsing and XML serialization formats.

Date Formats

The Date Formats meta-property provides a list of Java DateFormat patterns for parsing string values into Date objects. Martini iterates through the patterns until finding one that successfully parses the input.

Example Formats: 

1
Date Formats: ["yyyy-MM-dd", "MM/dd/yyyy", "dd-MM-yyyy HH:mm:ss"]

This enables flexible date input handling from various sources and formats.

XML Type

The XML Type meta-property controls how Date and String values serialize in XML format according to XML Schema standards.

Date XML Types:

  • null
  • dateTime
  • date
  • duration
  • time
  • gYearMonth
  • gMonthDay
  • gYear
  • gMonth
  • gDay

String XML Types:

Model-Specific Meta-Properties

These meta-properties apply exclusively to the Model property type and control inheritance and extensibility.

Allow Extra Properties

The Allow Extra Properties meta-property enables runtime addition of new properties to Data Models. When enabled, Martini displays an allow-extra-properties icon ( ) on the model.

Behavior:

  • Enabled: Permits dynamic property addition at runtime
  • Disabled: Logs warnings when unknown properties are added (default behavior)

Use this for flexible data models that need to accommodate varying input structures.

Reference

The Reference meta-property enables model inheritance by referencing another model's properties. This creates an "extends" relationship similar to class inheritance in object-oriented programming.

When combined with Allow Extra Properties disabled, this creates final class behavior that prevents further extension.

Usage Examples:

1
Reference: "com.acme.crm.models.contacts.Person"

This inheritance structure ensures consistent audit fields across all business entities while allowing specialized models to add domain-specific properties.

Throw Error on Extra Property

The Throw Error on Extra Property meta-property determines whether to throw exceptions when attempting to add unknown properties to models with Allow Extra Properties disabled.

Configuration Logic:

  • Allow Extra Properties enabled + This enabled: No errors thrown
  • Allow Extra Properties disabled + This enabled: Errors thrown for unknown properties
  • Allow Extra Properties disabled + This disabled: Warnings logged for unknown properties

Object-Specific Meta-Properties

This meta-property applies to the Object property type for storing custom Java/Groovy classes.

Object Class Name

The Object Class Name meta-property specifies the fully qualified class name for values stored in Object-type properties. Use this when none of the standard property types meet your requirements.

Example Configuration: 

1
Object Class Name: com.example.CustomDataType

This enables integration with custom Java/Groovy classes while maintaining property benefits.

Troubleshooting

Problem Detection Cause Fix
Nested property accepts null despite unchecked Allow Null No validation errors thrown for null child properties with service input/output validation enabled Parent model has Allow Null enabled, overriding child property validation Uncheck Allow Null on the parent model
Array null validation not working for empty arrays Empty arrays pass validation despite Allow Null unchecked and service input/output validation enabled Array validation checks individual elements for null, not array emptiness Use Min Array Size meta-property to require minimum elements if needed
Validation Expression ignored for null values Validation Expression doesn't execute when property value is null Allow Null is enabled, causing null values to bypass Validation Expression Uncheck Allow Null to proceed to Validation Expression evaluation

Helpful Resources

  1. Although a Model behaves similarly to a Map, it is not a strict Java equivalent. ↩