# Nested Struct-Array Field Names
CBValidation provides powerful shortcuts for validating nested data structures without requiring complex constraint definitions. Using dot notation for structs and asterisk (`*`) notation for arrays, you can validate deeply nested objects with clean, readable constraint definitions.
## Why Use Field Name Shortcuts?
Traditional nested validation would require defining complex constraint structures that mirror your data. Field name shortcuts allow you to:
* **Simplify constraint definitions** - Use flat, dot-notation paths instead of nested structures
* **Improve readability** - Clear field paths like `user.profile.email` are self-documenting
* **Reduce complexity** - Avoid deeply nested constraint objects
* **Handle dynamic structures** - Validate arrays of unknown length with `*` notation
## Nested Struct Shorthand
For a nested struct, this is done by defining the field as a dot-delimited field name following the nested structure.
```javascript
var validationResult = validate(
target = {
"address": {
"streetOne" : "123 Elm Street",
"streetTwo" : "",
"city" : "Anytown",
"state" : "IL",
"zip" : "60606"
}
},
constraints = {
"address": { "required": true, "type": "struct" },
"address.streetOne": { "required": true, "type": "string" },
"address.streetTwo": { "required": false, "type": "string" },
"address.city": { "required": true, "type": "string" },
"address.state": { "required": true, "type": "string", "size": 2 },
"address.zip": { "required": true, "type": "numeric", "size": 5 }
}
);
```
This can be continued as many levels deep as necessary.
```javascript
var validationResult = validate(
target = {
"owner": {
"firstName": "John",
"lastName": "Doe",
"address": {
"streetOne" : "123 Elm Street",
"streetTwo" : "",
"city" : "Anytown",
"state" : "IL",
"zip" : "60606"
}
}
},
constraints = {
"owner.firstName": { "required": true, "type": "string" },
"owner.lastName": { "required": true, "type": "string" },
"owner.address.streetOne": { "required": true, "type": "string" },
"owner.address.streetTwo": { "required": false, "type": "string" },
"owner.address.city": { "required": true, "type": "string" },
"owner.address.state": { "required": true, "type": "string", "size": 2 },
"owner.address.zip": { "required": true, "type": "numeric", "size": 5 }
}
);
```
## Array Validation Shortcuts
### Simple Array Validation
Use the asterisk (`*`) notation to validate all items in an array:
```javascript
// Validate array of numbers
var validationResult = validate(
target = {
"luckyNumbers": [ 7, 11, 21, 42 ],
"favoriteColors": [ "red", "blue", "green" ],
"scores": [ 85, 92, 78, 96 ]
},
constraints = {
"luckyNumbers.*": { "type": "numeric", "range": "1..100" },
"favoriteColors.*": { "type": "string", "size": "3..20" },
"scores.*": { "type": "numeric", "range": "0..100" }
}
);
```
### Array of Structs
Validate objects within arrays by combining dot notation with asterisk:
```javascript
var validationResult = validate(
target = {
"employees": [
{ "name": "John Doe", "email": "john@example.com", "age": 30 },
{ "name": "Jane Smith", "email": "jane@example.com", "age": 25 }
]
},
constraints = {
"employees.*.name": { "required": true, "type": "string", "size": "2..50" },
"employees.*.email": { "required": true, "type": "email" },
"employees.*.age": { "required": true, "type": "numeric", "range": "18..65" }
}
);
```
### Complex Nested Arrays
Handle deeply nested structures with multiple array levels:
```javascript
var validationResult = validate(
target = {
"departments": [
{
"name": "Engineering",
"teams": [
{
"name": "Backend",
"members": ["John", "Jane", "Bob"]
},
{
"name": "Frontend",
"members": ["Alice", "Charlie"]
}
]
}
]
},
constraints = {
"departments.*.name": { "required": true, "type": "string" },
"departments.*.teams.*.name": { "required": true, "type": "string" },
"departments.*.teams.*.members.*": { "type": "string", "size": "2..30" }
}
);
```
## Combined Struct and Array Examples
### User Profile with Multiple Addresses
```javascript
var validationResult = validate(
target = {
"user": {
"profile": {
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com"
},
"addresses": [
{
"type": "home",
"streetOne": "123 Elm Street",
"city": "Anytown",
"state": "IL",
"zip": "60606"
},
{
"type": "work",
"streetOne": "456 Oak Avenue",
"city": "Business City",
"state": "CA",
"zip": "90210"
}
],
"phoneNumbers": [
{ "type": "mobile", "number": "555-123-4567" },
{ "type": "home", "number": "555-987-6543" }
]
}
},
constraints = {
// Profile validation
"user.profile.firstName": { "required": true, "type": "string", "size": "2..50" },
"user.profile.lastName": { "required": true, "type": "string", "size": "2..50" },
"user.profile.email": { "required": true, "type": "email" },
// Address validation
"user.addresses.*.type": { "required": true, "inList": "home,work,other" },
"user.addresses.*.streetOne": { "required": true, "type": "string", "size": "5..100" },
"user.addresses.*.city": { "required": true, "type": "string", "size": "2..50" },
"user.addresses.*.state": { "required": true, "type": "string", "size": "2" },
"user.addresses.*.zip": { "required": true, "regex": "^\d{5}(-\d{4})?$" },
// Phone number validation
"user.phoneNumbers.*.type": { "required": true, "inList": "mobile,home,work" },
"user.phoneNumbers.*.number": { "required": true, "regex": "^\d{3}-\d{3}-\d{4}$" }
}
);
```
### E-commerce Order Structure
```javascript
var validationResult = validate(
target = {
"order": {
"customer": {
"name": "John Doe",
"email": "john@example.com"
},
"items": [
{
"productId": "PROD123",
"name": "Widget",
"quantity": 2,
"price": 19.99
},
{
"productId": "PROD456",
"name": "Gadget",
"quantity": 1,
"price": 49.99
}
],
"shipping": {
"method": "standard",
"address": {
"street": "123 Main St",
"city": "Anytown",
"zip": "12345"
}
}
}
},
constraints = {
// Customer validation
"order.customer.name": { "required": true, "type": "string", "size": "2..100" },
"order.customer.email": { "required": true, "type": "email" },
// Order items validation
"order.items.*.productId": { "required": true, "type": "string", "regex": "^PROD\d+$" },
"order.items.*.name": { "required": true, "type": "string", "size": "1..200" },
"order.items.*.quantity": { "required": true, "type": "numeric", "min": "1" },
"order.items.*.price": { "required": true, "type": "numeric", "min": "0.01" },
// Shipping validation
"order.shipping.method": { "required": true, "inList": "standard,express,overnight" },
"order.shipping.address.street": { "required": true, "type": "string" },
"order.shipping.address.city": { "required": true, "type": "string" },
"order.shipping.address.zip": { "required": true, "regex": "^\d{5}$" }
}
);
```
## Error Message Context
When validation fails on nested fields, the error messages include the full field path for precise error identification:
```javascript
var result = validate(target=orderData, constraints=orderConstraints);
if (result.hasErrors()) {
for (var error in result.getAllErrors()) {
// Examples of nested error fields:
// "user.profile.email" - Invalid email format
// "user.addresses.0.zip" - Invalid zip code (first address)
// "order.items.1.price" - Price must be positive (second item)
writeOutput("Field: #error.getField()# - #error.getMessage()#
");
}
}
```
## Best Practices
### 1. Use Descriptive Field Names
```javascript
// ❌ Hard to understand
"data.items.*.val": { "required": true }
// ✅ Clear and descriptive
"products.items.*.price": { "required": true, "type": "numeric", "min": "0.01" }
```
### 2. Group Related Constraints
```javascript
// ❌ Mixed up constraint definitions
constraints = {
"user.email": { "required": true, "type": "email" },
"user.addresses.*.zip": { "required": true },
"user.name": { "required": true },
"user.addresses.*.city": { "required": true }
};
// ✅ Logically grouped
constraints = {
// User basic info
"user.name": { "required": true, "type": "string" },
"user.email": { "required": true, "type": "email" },
// Address validation
"user.addresses.*.city": { "required": true, "type": "string" },
"user.addresses.*.zip": { "required": true, "regex": "^\d{5}$" }
};
```
### 3. Validate Array Container and Items
```javascript
constraints = {
// Validate the array itself
"user.addresses": { "required": true, "type": "array", "size": "1..5" },
// Validate array items
"user.addresses.*.street": { "required": true, "type": "string" },
"user.addresses.*.city": { "required": true, "type": "string" }
};
```
## Common Use Cases
### API Request Validation
Perfect for validating complex JSON payloads:
```javascript
// POST /api/users - Create user with profile and preferences
var apiConstraints = {
"name": { "required": true, "type": "string", "size": "2..100" },
"email": { "required": true, "type": "email" },
"profile.bio": { "type": "string", "size": "0..500" },
"profile.socialLinks.*.platform": { "inList": "twitter,linkedin,github" },
"profile.socialLinks.*.url": { "type": "url" },
"preferences.notifications.*.type": { "required": true },
"preferences.notifications.*.enabled": { "type": "boolean" }
};
```
### Form Data Processing
Handle complex form submissions with nested data:
```javascript
// Registration form with emergency contacts
var formConstraints = {
"personal.firstName": { "required": true, "size": "2..50" },
"personal.lastName": { "required": true, "size": "2..50" },
"contacts.*.name": { "required": true, "type": "string" },
"contacts.*.relationship": { "required": true, "inList": "spouse,parent,sibling,friend" },
"contacts.*.phone": { "required": true, "regex": "^\d{3}-\d{3}-\d{4}$" }
};
```
### Configuration Validation
Validate application configuration files:
```javascript
// App config with database connections and feature flags
var configConstraints = {
"database.connections.*.host": { "required": true, "type": "string" },
"database.connections.*.port": { "type": "numeric", "range": "1..65535" },
"features.*.name": { "required": true, "type": "string" },
"features.*.enabled": { "required": true, "type": "boolean" },
"logging.handlers.*.level": { "inList": "debug,info,warn,error" }
};
```
Field name shortcuts make CBValidation incredibly powerful for handling real-world data structures while keeping your constraint definitions clean and maintainable.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://coldbox-validation.ortusbooks.com/overview/valid-constraints/nested-struct-and-array-field-name-shortcuts.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.