1 Exploring Catala

Summary: An exploration of the Catala language to explore how to encode exceptions

Per the Catala language website:

Catala is a domain-specific language designed by researchers inComputer Science and Law, for precisely deriving algorithmsproducing automated legal decisions.

1.1 Introductory Catala Code

This Catala program is copied directly from the documentation of Catala and is the “hello world” of Catala. It outputs the integer as the Answer to the Ultimate Question of Life, the Universe, and Everything:

declaration scope HelloWorld: 
  output answer_everything content integer 
 
scope HelloWorld: 
  definition answer_everything equals 42

Interestingly, this section of code comes from a tex file! Catala isbuilt around literate programming and this section is actually a validCatala file.

1.2 Article 1

The income tax for an individual is defined as a fixed percentage of the individual’s income over a year.

The content of article 1 assumes a lot of implicit context: there existsan individual with an income, as well as an income tax that theindividual has to pay each year.

declaration structure Individual: 
  data income content money 
  data number_of_children content integer

declaration scope IncomeTaxComputation: 
  input individual content Individual 
  internal tax_rate content decimal 
  output income_tax content money

1.3 Article 2

scope IncomeTaxComputation: 
  definition tax_rate equals 20% 
  definition income_tax equals tax_rate * individual.income

1.4 Test

declaration scope Test: 
  output computation content IncomeTaxComputation 
 
scope Test: 
  definition computation equals 
 
  output of IncomeTaxComputation with { 
 
    -- individual: 
 
       Individual { 
 
         -- income: $20,000 
         -- number_of_children: 0 
       } 
  }

Catala uses literate programming, that is the mixing between the computer code and its specification in a single document. Why literate programming? Because it enables a fine-grained correspondance between the specification and the code. Whenever the specification is updated, knowing where to update the code is trivial with literal programming.

Catala is a strongly-typed, statically compiled language, so all data structures and function signatures have to be explicitly declared.

The name of the structure, ”Individual”, must start with an uppercase letter: this is the CamelCase convention.

Available types include: ”integer”, ”decimal”, ”money”, ”date”, ”duration”, and any other structure or enumeration that you declare.

Usually, you get one structure per concrete object on which the law applies (like the individual).

# The name "TaxCredit" is also written in CamelCase. 
declaration enumeration TaxCredit: 
# The line below says that "TaxCredit" can be a "NoTaxCredit" situation. 
-- NoTaxCredit 
# The line below says that alternatively, "TaxCredit" can be a 
# "ChildrenTaxCredit" situation. This situation carries a content 
# of type integer corresponding to the number of children concerned 
# by the tax credit. This means that if you're in the "ChildrenTaxCredit" 
# situation, you will also have access to this number of children. 
-- ChildrenTaxCredit content integer 
# In computer science terms, such an enumeration is called a \sum type" or simply an enum. The combination of structures and enumerations allows the Catala programmer to declare all possible shapes of data, as they are equivalent to the powerful notion of algebraic data types.

Notice that these data structures that we have declared cannot always be attached naturally to a particular piece of the specification text. So, where to put these declarations in your literate programming file? Since you will be often going back to these data structure declarations during programming, we advise you to group them together in some sort of prelude in your code source file.

Catala is a functional programming language, all code exists within a function.

The scope is the basic abstraction unit in Catala programs, and scopes can be composed. Since a function can call other functions, scopes can also call other scopes. We will see later how to do this, but first let us focus on the inputs and outputs of scopes.

The declaration of the scope is akin to a function signature: it contains a list of all the arguments along with their types. But in Catala, scope variables can be input, internal or output. input means that the variable has to be provided whenever the scope is called, and cannot be defined within the scope. internal means that the variable is defined within the scope and cannot be seen from outside the scope; it’s not part of the return value of the scope. output means that a caller can retrieve the computed value of the variable. Note that a variable can also be simultaneously an input and an output of the scope, in that case it should be annotated with input output.

This is a common pattern when coding the law: the definitions for various variables are scattered in different articles.

More generally, the order of toplevel definitions and declarations in Catala source code files does not matter

How To Cite

Zelko, Jacob S. Exploring Catala. https://jacobzelko.com/notes/aaa-0287/. August 24, 2026.

Discussion: