Validations

With custom type validations, you can set specific rules to ensure your data’s value falls within an acceptable range.

BAML provides two types of validations:

• @assert for strict validations. If a type fails an @assert validation, it will not be returned in the response. If the failing assertion was part of the top-level type, it will raise an exception. If it’s part of a container, it will be removed from the container.
• @check for non-exception-raising validations. Whether a @check passes or fails, the data will be returned. You can access the results of invidividual checks in the response data.

Assertions

Assertions are used to guarantee properties about a type or its components in a response. They can be written directly as inline attributes next to the field definition or on the line following the field definition, or on a top-level type used in a function declaration.

Using @assert

BAML will raise an exception if a function returns a Foo where Foo.bar is not between 0 and 10.

If the function NextInt8 returns 128, BAML will raise an exception.

1
class Foo {
2
  bar int @assert(between_0_and_10, {{ this > 0 and this < 10 }}) //this = Foo.bar value
3
}
4
5
function NextInt8(a: int) -> int @assert(ok_int8, {{ this >= -128 and this < 127 }}) {
6
  client GPT4
7
  prompt #"Return the number after {{ a }}"#
8
}

Asserts may be applied to a whole class via @@assert.

1
class Bar {
2
  baz int
3
  quux string
4
  @@assert(length_limit, {{ this.quux|length < this.baz }})
5
}

Using @assert with Union Types

Note that when using Unions, it is crucial to specify where the @assert attribute is applied within the union type, as it is not known until runtime which type the value will be.

1
class Foo {
2
  bar (int @assert(positive, {{ this > 0 }}) | bool @assert(is_true, {{ this }}))
3
}

In the above example, the @assert attribute is applied specifically to the int and string instances of the Union, rather than to the Foo.bar field as a whole.

Likewise, the keyword this refers to the value of the type instance it is directly associated with (e.g., int or string).

Chaining Assertions

You can have multiple assertions on a single field by chaining multiple @assert attributes.

In this example, the asserts on bar and baz are equivalent.

1
class Foo {
2
  bar int @assert(between_0_and_10, {{ this > 0 and this < 10 }})
3
  baz int @assert(positive, {{ this > 0 }}) @assert(less_than_10, {{ this < 10 }})
4
}

Chained asserts are evaluated in order from left to right. If the first assert fails, the second assert will not be evaluated.

Writing Assertions

Assertions are represented as Jinja expressions and can be used to validate various types of data. Possible constraints include checking the length of a string, comparing two values, or verifying the presence of a substring with regular expressions.

In the future, we plan to support shorthand syntax for common assertions to make writing them easier.

For now, see our Jinja cookbook / guide or the Minijinja filters docs for more information on writing expressions.

Expression keywords

• this refers to the value of the current field being validated.

this.field is used to refer to a specific field within the context of this. Access nested fields of a data type by chaining the field names together with a . as shown below.

1
class Resume {
2
  name string
3
  experience string[]
4
5
}
6
7
class Person {
8
  resume Resume @assert({{ this.experience|length > 0 }}, "Nonzero experience")
9
  person_name name
10
}

Assertion Errors

When validations fail, your BAML function will raise a BamlValidationError exception, same as when parsing fails. You can catch this exception and handle it as you see fit.

You can define custom names for each assertion, which will be included in the exception for that failure case. If you don’t define a custom name, BAML will display the body of the assert expression.

In this example, if the quote field is empty, BAML raises a BamlValidationError with the message “exact_citation_not_found”. If the website_link field does not contain “https://”, it raises a BamlValidationError with the message invalid_link.

1
class Citation {
2
  //@assert(<name>, <expr>)
3
  quote string @assert(exact_citation_found,
4
	  {{ this|length > 0 }}
5
  )
6
7
  website_link string @assert(valid_link,
8
    {{ this|regex_match("https://") }}
9
  )
10
}

1
from baml_client import b
2
from baml_client.types import Citation
3
4
def main():
5
    try:
6
        citation: Citation = b.GetCitation("SpaceX, is an American spacecraft manufacturer, launch service provider...")
7
8
        # Access the value of the quote field
9
        quote = citation.quote
10
        website_link = citation.website_link
11
        print(f"Quote: {quote} from {website_link}")
12
        
13
    except BamlValidationError as e:
14
        print(f"Validation error: {str(e)}")
15
    except Exception as e:
16
        print(f"An unexpected error occurred: {e}")

Checks

@check attributes add validations without raising exceptions if they fail. Types with @check attributes allow the validations to be inspected at runtime.

1
( bar int @check(less_than_zero, {{ this < 0 }}) )[]

1
List[Checked[int, Dict[Literal["less_than_zero"]]]]

The following example uses both @check and @assert. If line_number fails its @assert, no Citation will be returned by GetCitation(). However, exact_citation_not_found can fail without interrupting the result. Because it was a @check, client code can inspect the result of the check.

1
class Citation {
2
  quote string @check(
3
      exact_citation_match,
4
	  {{ this|length > 0 }}
5
  )
6
  line_number string @assert(
7
    has_line_number
8
    {{ this|length >= 0 }}
9
  )
10
}
11
12
function GetCitation(full_text: string) -> Citation {
13
  client GPT4 
14
  prompt #"
15
    Generate a citation of the text below in MLA format:
16
    {{full_text}}
17
18
    {{ctx.output_format}}
19
  "#
20
}

1
from baml_client import b
2
from baml_client.types import Citation, get_checks
3
4
def main():
5
    citation = b.GetCitation("SpaceX, is an American spacecraft manufacturer, launch service provider...")
6
7
    # Access the value of the quote field
8
    quote = citation.quote.value 
9
    print(f"Quote: {quote}")
10
11
    # Access a particular check.
12
    quote_match_check = citation.quote.checks['exact_citation_match'].status
13
    print(f"Citation match status: {quote_match_check})")
14
15
    # Access each check and its status.
16
    for check in get_checks(citation.quote.checks):
17
        print(f"Check {check.name}: {check.status}")

You can also chain multiple @check and @assert attributes on a single field.

1
class Foo {
2
  bar string @check(bar_nonempty, {{ this|length > 0 }})
3
  @assert(bar_no_foo, {{ this|contains("foo") }})
4
  @check(bar_no_fizzle, {{ this|contains("fizzle") }})
5
  @assert(bar_no_baz, {{ this|contains("baz") }})
6
}

Advanced Example

The following example shows more complex minijinja expressions, see the Minijinja filters docs for more information on available operators to use in your assertions.

The Book and Library classes below demonstrate how to validate a book’s title, author, ISBN, publication year, genres, and a library’s name and books. The block-level assertion in the Library class ensures that all books have unique ISBNs.

1
class Book {
2
    title string @assert(this|length > 0)
3
    author string @assert(this|length > 0)
4
    isbn string @assert(
5
        {{ this|regex_match("^(97(8|9))?\d{9}(\d|X)$") }},
6
        "Invalid ISBN format"
7
    )
8
    publication_year int @assert(valid_pub_year, {{ 1000 <= this <= 2100 }})
9
    genres string[] @assert(valid_length, {{ 1 <= this|length <= 10 }})
10
}
11
12
class Library {
13
    name string
14
    books Book[] @assert(nonempty_books, {{ this|length > 0 }})
15
                 @assert(unique_isbn, {{ this|map(attribute='isbn')|unique()|length == this|length }} )
16
}

In this example, we use a block-level @@assert to check a dependency across a pair of fields.

1
class Person {
2
    name string @assert(valid_name, {{ this|length >= 2 }})
3
    age int @assert(valid_age, {{ this >= 0 }})
4
    address Address
5
6
    @@assert(not_usa_minor, {{
7
        this.age >= 18 or this.address.country != "USA",
8
    }})
9
}