> For the complete documentation index, see [llms.txt](https://coldbox-validation.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coldbox-validation.ortusbooks.com/overview/validating-constraints/using-default-values.md).

# Using Default Values

Using default values in constraints

The `defaultValue` constraint (introduced in 4.5.0) allows you to automatically apply default values to fields before validation rules are checked. This is useful for initializing optional fields with sensible defaults.

## Overview

When a field has a `defaultValue` defined and the field's current value is null or empty, the default value will be assigned to the field before any other constraints are evaluated.

## Basic Usage

{% tabs %}
{% tab title="BoxLang" %}

```javascript
class {
    this.constraints = {
        status: {
            defaultValue: "active",
            required: true,
            inList: "active,inactive,pending"
        },
        createdDate: {
            defaultValue: now(),
            required: true,
            type: "date"
        },
        priority: {
            defaultValue: 5,
            min: 1,
            max: 10
        }
    };
}
```

{% endtab %}

{% tab title="CFML" %}

```javascript
component {
    this.constraints = {
        status: {
            defaultValue = "active",
            required = true,
            inList = "active,inactive,pending"
        },
        createdDate = {
            defaultValue = now(),
            required = true,
            type = "date"
        },
        priority = {
            defaultValue = 5,
            min = 1,
            max = 10
        }
    };
}
```

{% endtab %}
{% endtabs %}

## When Defaults Are Applied

The `defaultValue` is applied when:

* The field value is **null**
* The field value is an **empty string** (for simple values)
* The field value has **no value** (hasValue() check fails)

The default is **NOT** applied when:

* The field already has a non-empty value
* The field is explicitly set to a falsy value like `false` or `0`

## Practical Examples

### Form with Default Status

{% tabs %}
{% tab title="BoxLang" %}
{% code title="User.bx" overflow="wrap" lineNumbers="true" %}

```javascript
class {
    property name="name" type="string";
    property name="email" type="string";
    property name="status" type="string";
    property name="roleId" type="numeric";

    this.constraints = {
        name: { required: true, size: "2..100" },
        email: { required: true, type: "email" },
        status: {
            defaultValue: "pending",
            required: true,
            inList: "pending,active,inactive"
        },
        roleId: {
            defaultValue: 3,  // Default user role
            required: true,
            type: "numeric"
        }
    };
}
```

{% endcode %}
{% endtab %}

{% tab title="CFML" %}
{% code title="User.cfc" overflow="wrap" lineNumbers="true" %}

```javascript
component {
    property name="name" type="string";
    property name="email" type="string";
    property name="status" type="string";
    property name="roleId" type="numeric";

    this.constraints = {
        name = { required = true, size = "2..100" },
        email = { required = true, type = "email" },
        status = {
            defaultValue = "pending",
            required = true,
            inList = "pending,active,inactive"
        },
        roleId = {
            defaultValue = 3,  // Default user role
            required = true,
            type = "numeric"
        }
    };
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

In your handler:

```javascript
function create(event, rc, prc) {
    var user = new User();
    populateModel(user);

    var results = validate(target=user);

    if (!results.hasErrors()) {
        // user.status will be "pending" if not provided
        // user.roleId will be 3 if not provided
        userService.create(user);
    }
}
```

### Dynamic Default with Functions

You can use closures to compute dynamic defaults:

{% tabs %}
{% tab title="BoxLang" %}
{% code title="Order.bx" overflow="wrap" lineNumbers="true" %}

```javascript
class {
    property name="orderNumber" type="string";
    property name="createdDate" type="date";
    property name="expiryDate" type="date";

    this.constraints = {
        orderNumber: {
            defaultValue: () => createUUID(),
            required: true,
            type: "string"
        },
        createdDate: {
            defaultValue: () => now(),
            required: true,
            type: "date"
        },
        expiryDate: {
            defaultValue: () => dateAdd('d', 30, now()),
            required: true,
            type: "date"
        }
    };
}
```

{% endcode %}
{% endtab %}

{% tab title="CFML" %}
{% code title="Order.cfc" overflow="wrap" lineNumbers="true" %}

```javascript
component {
    property name="orderNumber" type="string";
    property name="createdDate" type="date";
    property name="expiryDate" type="date";

    this.constraints = {
        orderNumber = {
            defaultValue = function() { return createUUID(); },
            required = true,
            type = "string"
        },
        createdDate = {
            defaultValue = function() { return now(); },
            required = true,
            type = "date"
        },
        expiryDate = {
            defaultValue = function() { return dateAdd('d', 30, now()); },
            required = true,
            type = "date"
        }
    };
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## API Validation with Defaults

{% tabs %}
{% tab title="BoxLang" %}
{% code title="ProductHandler.bx" overflow="wrap" lineNumbers="true" %}

```javascript
function apiCreateProduct(event, rc, prc) {
    var productConstraints = {
        name: { required: true, size: "1..255" },
        description: { size: "0..1000" },
        active: {
            defaultValue: true,
            type: "boolean"
        },
        publishedDate: {
            defaultValue: () => now(),
            required: false
        }
    };

    try {
        // Apply defaults and validate
        var validProduct = validateOrFail(
            target: rc,
            constraints: productConstraints
        );

        var product = productService.create(validProduct);
        return event.renderData(data=product);
    } catch(ValidationException e) {
        return event.renderData(
            statusCode: 422,
            data: { errors: deserializeJSON(e.extendedInfo) }
        );
    }
}
```

{% endcode %}
{% endtab %}

{% tab title="CFML" %}
{% code title="ProductHandler.cfc" overflow="wrap" lineNumbers="true" %}

```javascript
function apiCreateProduct(event, rc, prc) {
    var productConstraints = {
        name = { required = true, size = "1..255" },
        description = { size = "0..1000" },
        active = {
            defaultValue = true,
            type = "boolean"
        },
        publishedDate = {
            defaultValue = function() { return now(); },
            required = false
        }
    };

    try {
        // Apply defaults and validate
        var validProduct = validateOrFail(
            target=rc,
            constraints=productConstraints
        );

        var product = productService.create(validProduct);
        return event.renderData(data=product);
    } catch(ValidationException e) {
        return event.renderData(
            statusCode=422,
            data={ errors: deserializeJSON(e.extendedInfo) }
        );
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Best Practices

### 1. Use for Optional Fields Only

Default values work best for truly optional fields:

```javascript
// Good - truly optional
optionalNotes: { defaultValue: "", size: "0..500" }

// Less ideal - required field should not have a default that bypasses validation
email: { defaultValue: "noemail@example.com", required: true, type: "email" }
```

### 2. Defaults Should Match Constraint Rules

Always ensure your default value complies with other constraints:

{% tabs %}
{% tab title="BoxLang" %}

```javascript
// ✅ Good - default matches type and range constraints
priority: {
    defaultValue: 5,
    type: "numeric",
    min: 1,
    max: 10
}

// ❌ Bad - default violates inList constraint
status: {
    defaultValue: "unknown",
    inList: "active,inactive,pending"
}
```

{% endtab %}

{% tab title="CFML" %}

```javascript
// ✅ Good - default matches type and range constraints
priority = {
    defaultValue = 5,
    type = "numeric",
    min = 1,
    max = 10
}

// ❌ Bad - default violates inList constraint
status = {
    defaultValue = "unknown",
    inList = "active,inactive,pending"
}
```

{% endtab %}
{% endtabs %}

### 3. Use Functions for Dynamic Defaults

For timestamp or unique identifier defaults, use functions:

```javascript
createdAt: {
    defaultValue: () => now(),
    required: true
}

uuid: {
    defaultValue: () => createUUID(),
    required: true
}
```

### 4. Document Default Behavior

Always document which fields have defaults:

```javascript
/**
 * User entity constraints
 *
 * Fields with defaults:
 * - status: defaults to "pending"
 * - roleId: defaults to 3 (user role)
 * - createdDate: defaults to now()
 */
```

## See Also

* [Constraint Profiles](/overview/validating-constraints/validating-with-profiles.md) - Validate different field sets for different scenarios
* [Custom Constraints](https://github.com/ortus-docs/cbvalidation-docs/blob/v4.x/advanced/constraint-custom-messages.md) - Customize validation messages
* [Validating Constraints](/overview/validating-constraints.md) - Main validation documentation


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://coldbox-validation.ortusbooks.com/overview/validating-constraints/using-default-values.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.