Data Models

A Data Model defines the shape of information entering or leaving decision logic. It gives authors a shared vocabulary, drives field selection throughout the designers, validates test payloads, and documents the JSON contract used by API consumers.

Data Models do not execute on their own. Decision Tables, Rulesets, Scorecards, Workflows, HTTP Clients, and Coding HubItems refer to them.

When to create a Data Model

Create a reusable model when several assets exchange the same business object, when an external application needs a stable request or response contract, or when you want designers to offer field paths instead of relying on manually typed names.

For example, a lending solution might use three models:

• LoanApplication for the incoming application;
• Applicant as a nested reusable business structure;
• LoanDecision for the public response.

Avoid one enormous model for the entire organization. Smaller contracts make mappings, tests, and change impact easier to understand.

Build a model

Create Data Model from The Hub and open its Designer. Add attributes at the root, then add children beneath objects and collections.

Each attribute has the following concepts:

Setting	Purpose	Example
Name	JSON property name used by rules and API callers	requestedAmount
Type	The kind of value the property accepts	Number
Required	The property must be supplied	applicant
Nullable	The property may explicitly contain null	middleName
Children	Fields contained by an object or collection item	address.city

The type list is filtered by the current editor and can include text, number, Boolean, date/time, object, and collection structures. Use object children to represent nested JSON and collection children to describe each entry in an array.

Worked example: loan application

Build this hierarchy:

applicationId       Text, required
requestedAmount     Number, required
termMonths          Number, required
applicant           Object, required
  age               Number, required
  annualIncome      Number, required
  existingDebt      Number, required
  country           Text, required
  tags              Collection of Text

A valid payload is:

{
  "applicationId": "APP-1042",
  "requestedAmount": 25000,
  "termMonths": 36,
  "applicant": {
    "age": 34,
    "annualIncome": 78000,
    "existingDebt": 8500,
    "country": "NZ",
    "tags": ["existing-customer", "salary-verified"]
  }
}

An appropriate output model might be:

applicationId       Text, required
approved            Boolean, required
riskBand            Text, required
approvedAmount      Number, nullable
reasons             Collection of Text

That separation prevents internal calculation fields from accidentally becoming part of the public response.

Required and nullable are different

Required describes whether the property must exist. Nullable describes whether its value may be null. A property can therefore be optional but, when supplied, non-null. Test all combinations that matter to your business logic:

{}

{"middleName": null}

{"middleName": "Aroha"}

Rules should not assume an optional path exists. Add null/presence conditions or define a fallback before using it.

Import and export

The designer can create a model from JSON and export the current definition. Import is useful when you already have a representative payload:

1. Remove personal data and secrets from the example.
2. Include every important object and collection shape.
3. Import the example and review the proposed hierarchy.
4. Correct inferred types, required fields, and nullability.
5. Save and test with more than one payload.

One sample cannot reveal every optional field or every possible collection entry, so imported models always require review. Export is useful for peer review, backup, and moving a definition through controlled processes.

Use a model in a HubItem

Open the executable HubItem's Settings and select its input and output models. Workflow and integration nodes can also select payload or response models. The platform then uses those selections to populate field pickers and Rich Editor suggestions.

Auto-map Input to Output initializes compatible output fields from the input before the asset writes its results. For example, if both models contain applicationId, auto-map can carry it through without a separate result rule. Do not use auto-map as a substitute for an intentional public response contract.

Use a model in workflows

Mappings connect paths exposed by the source model to paths accepted by the target model. Given the loan input above, a Rule node can receive:

Input.applicant.annualIncome → AffordabilityRule.annualIncome
Input.applicant.existingDebt → AffordabilityRule.existingDebt

If you rename annualIncome, those mappings and any rule expressions that use the old path need attention. Dependency warnings help locate affected HubItems, but saved payloads and external callers must also be updated.

Evolve a model safely

Adding an optional field is usually safer than renaming, removing, or changing a type. For a contract change:

1. Create a new version boundary for affected HubItems.
2. Review dependencies and workflow mappings.
3. Update Decision Table columns, Ruleset actions, Scorecard attributes, and code paths.
4. Update saved payloads and expected results.
5. Test old and new payload shapes when backward compatibility is required.
6. Deploy the Data Model and dependent executable versions together.
7. Coordinate the change with API consumers before removing old fields.

Common problems

Problem	Likely cause	Resolution
Field does not appear in a picker	Wrong model selected or unsaved model change	Save the model and confirm the node/HubItem model selection
Test payload is rejected	Missing required property or incompatible scalar type	Compare the JSON hierarchy with the deployed input model
Mapping becomes invalid	Attribute renamed, removed, or changed from scalar to object	Recreate the mapping and retest downstream nodes
Empty collection behaves unexpectedly	No explicit empty-list test	Save cases for empty, one-item, and multiple-item arrays
API response contains unexpected copied fields	Auto-map is enabled	Disable it or narrow the output model