fn::validate

The fn::validate built-in function validates a value against a JSON Schema. If the value does not conform to the schema, a validation error is raised and the environment cannot be saved until the issues are resolved.

Declaration

fn::validate:
  schema: json-schema
  value: value-to-validate

Parameters

Returns

If validation passes, the original value is returned. If validation fails, an error is raised and the environment cannot be saved.

Example

Basic type validation

Definition

values:
  valid-string:
    fn::validate:
      schema: { type: string }
      value: "hello"

Evaluated result

{
  "valid-string": "hello"
}

Number constraints

Definition

values:
  validated-number:
    fn::validate:
      schema: { type: number, minimum: 0 }
      value: 42

Evaluated result

{
  "validated-number": 42
}

Object with required fields

Definition

values:
  user:
    fn::validate:
      schema:
        type: object
        properties:
          name: { type: string }
          email: { type: string }
        required: [name, email]
      value:
        name: "Alice"
        email: "alice@example.com"

Evaluated result

{
  "user": {
    "name": "Alice",
    "email": "alice@example.com"
  }
}

Dynamic schema from reference

You can define schemas as values and reference them dynamically:

Definition

values:
  my-schema:
    type: string
    minLength: 1
  validated:
    fn::validate:
      schema: ${my-schema}
      value: "hello"

Evaluated result

{
  "my-schema": {
    "type": "string",
    "minLength": 1
  },
  "validated": "hello"
}

Array validation

Definition

values:
  tags:
    fn::validate:
      schema:
        type: array
        items: { type: string }
      value: ["production", "us-east-1"]

Evaluated result

{
  "tags": ["production", "us-east-1"]
}

Reusing schemas from other environments

You can define schemas in a separate environment and reference them for reuse across multiple environments. This allows you to centralize schema definitions and ensure consistent validation.

Using the environments built-in property to reference the schema is the recommended approach because it doesn’t merge the schema into your environment’s output.

Schema environment (myproj/schemas)

values:
  user-schema:
    type: object
    properties:
      name: { type: string }
      email: { type: string }
    required: [name, email]

Environment using the schema reference

values:
  user:
    fn::validate:
      schema: ${environments.myproj.schemas.user-schema}
      value:
        name: "Alice"
        email: "alice@example.com"

Evaluated result

{
  "user": {
    "name": "Alice",
    "email": "alice@example.com"
  }
}

This pattern is useful for enforcing consistent validation rules across teams and projects.

Validation errors

When a value does not conform to its schema, fn::validate raises an error that prevents the environment from being saved. This ensures configuration issues are caught before the environment is used.

Example: type mismatch

values:
  type-error:
    fn::validate:
      schema: { type: string }
      value: 42

This raises an error: expected string, got number. The environment cannot be saved until the value conforms to the schema.

Example: missing required field

values:
  missing-required:
    fn::validate:
      schema:
        type: object
        properties:
          name: { type: string }
        required: [name]
      value:
        other: "value"

This raises an error indicating that the required field name is missing. The environment cannot be saved until the required field is provided.