---
title: "17.4 Categories"
url: https://una-lang.org/en/learn/information-flow/categories/
release: v0.4.0
edition: "0.2"
---

# 17.4 Categories

## 17.4.1 What a category is

A level says how sensitive data is. A **category** says what kind of data it is: personal data, a location, a payment card number. Think of a colored sticker next to the "confidential" stamp: two folders can be equally sensitive and still belong in different cabinets.

You write categories in square brackets after the level: `secret[PII] Text` is secret, and it is personal data (PII stands for *personally identifiable information*). Each package declares its own categories by name.

## 17.4.2 Why a level is not enough

A courier needs a customer's phone number, so that the driver can call at the door. The analytics service records bookings, and it may receive secret data, such as the store's sales figures. Here is a route booking with a level and no category:

```una include="steps/25-no-category/src/courier.una" title="steps/25-no-category/src/courier.una" verified="check, run"
module courier

--- A stop on a delivery route. The phone number is secret, and nothing says it is personal.
kind Stop
  order: Text
  city: Text
  phone: secret Text

--- The courier's booking service. It may receive secret data.
capability Courier
  op book(order: Text, phone: Text) -> Unit
    accepts secret

--- The store's analytics service. It may receive secret data too: sales figures, for one.
capability Analytics
  op record(event: Text) -> Unit
    accepts secret

--- Books every stop of a route, and records each booking for the analysts.
book_route(stops: List[Stop]) -> Unit
  uses @courier: Courier[book]
  uses @analytics: Analytics[record]
=
  for stop in stops
    @courier.book(stop.order, phone: stop.phone)
    @analytics.record("booked {stop.order} in {stop.city} for {stop.phone}")

--- A courier that accepts every booking, for this run.
handler accepting() for Courier
  op book(order, phone) = unit

--- An analytics service that stores nothing, for this run.
handler discarding() for Analytics
  op record(event) = unit

pub main() -> Unit
  uses @console: Console[print]
=
  let route = [Stop(order: "A-1001", city: "Recife", phone: "+55 81 5550 0101"), Stop(order: "A-1002", city: "Olinda", phone: "+55 81 5550 0102")]
  book_route(route) with @courier = accepting(), @analytics = discarding()
  @console.print("route booked and recorded")
```

`una run .` prints:

```text include="steps/25-no-category/expected/output.txt"
route booked and recorded
```

It checks, and every customer's phone number now sits in the analytics records. Both services accept `secret`, and the phone is `secret`, so nothing tells them apart. A higher level for the phone would not help either: the courier must still receive it. What the program needs to say is that the courier may receive *personal* data and the analytics service may not.

## 17.4.3 How to write categories

### 17.4.3.1 Declaring them in `una.toml`

A package declares its categories in `una.toml`, under the table `[labels]`, as a list of names:

```toml include="steps/26-categories/una.toml" title="steps/26-categories/una.toml"
[package]
name = "courier"
version = "0.1.0"
edition = "0.2"

[labels]
categories = ["PII"]

[run]
entry = "courier"
grants = ["console"]
```

A category's name is written in UpperCamelCase: it starts with a capital letter, and each word in it does too, such as `PII` or `Location`. Any other name, such as `pii`, is U1005.

### 17.4.3.2 On a type

The categories go in square brackets right after the level, before the type: `secret[PII] Text`. Several categories are separated by commas: `confidential[Location, PII] Text`.

### 17.4.3.3 In an `accepts` clause

A ceiling can name categories too: `accepts secret[PII]` accepts secret data that is personal, and anything below it.

## 17.4.4 A courier that may receive a phone number

The step books a courier, whose service may receive personal data:

:::steps
```una include="steps/26-categories/src/courier.una" title="steps/26-categories/src/courier.una" verified="check, run"
module courier

--- A stop on a delivery route. The phone number is personal data.
kind Stop
  order: Text
  city: Text
  phone: secret[PII] Text

--- The courier's booking service. It may receive personal data, so that a driver can call
--- the customer at the door.
capability Courier
  op book(order: Text, phone: Text) -> Unit
    accepts secret[PII]

--- Books every stop of a route with the courier.
book_route(stops: List[Stop]) -> Unit
  uses @courier: Courier[book]
=
  for stop in stops
    @courier.book(stop.order, phone: stop.phone)

--- The cities of a route, for the dispatch board. They are public.
cities(stops: List[Stop]) -> List[Text] = stops.map(each: fn(stop) -> stop.city)

--- A courier that accepts every booking, for this run.
handler accepting() for Courier
  op book(order, phone) = unit

pub main() -> Unit
  uses @console: Console[print]
=
  let route = [Stop(order: "A-1001", city: "Recife", phone: "+55 81 5550 0101"), Stop(order: "A-1002", city: "Olinda", phone: "+55 81 5550 0102")]
  book_route(route) with @courier = accepting()
  let board = cities(route).join(separator: ", ")
  @console.print("route booked: {board}")
```

Walkthrough:

1. **`phone: secret[PII] Text`.** A phone number is personal data. The level `secret` and the category `PII` travel with it.
2. **`accepts secret[PII]`.** The courier's booking service needs the phone, so a driver can call at the door. Its ceiling names the category. An operation that `accepts secret` without `PII` would reject the phone with U4003: the category is part of the ceiling.
3. **`@courier.book(stop.order, phone: stop.phone)`.** The order id is public and the phone is `secret[PII]`. Each argument is checked against the ceiling.
4. **`cities`.** It reads only the public `city` field, so the dispatch board, printed by `main`, shows no personal data.
:::

`una run .` prints:

```text include="steps/26-categories/expected/output.txt"
route booked: Recife, Olinda
```

The analytics service of [Why a level is not enough](#why-a-level-is-not-enough), with `accepts secret`, would now refuse the phone. Personal data reaches only the places that say they may receive it.

## 17.4.5 How categories flow and combine

### 17.4.5.1 A label flows only into one with the same categories, or more

A label flows into another only if its level is at or below the other's, *and* its categories are among the other's. So `secret[PII]` flows into `secret[PII]` and `restricted[PII]`, but not into `secret`. Give the courier `accepts secret`:

```diff include="steps/26-categories..steps/27-no-category-ceiling:src/courier.una" context="1" title="src/courier.una"
--- a/src/courier.una
+++ b/src/courier.una
@@ -12,3 +12,3 @@
   op book(order: Text, phone: Text) -> Unit
-    accepts secret[PII]
+    accepts secret
 
```

```text include="steps/27-no-category-ceiling/expected/rendered.txt#L1"
[U4003] Error: `@courier.book` accepts `secret` data, and this argument is `secret[PII]`
```

The levels match, and the category does not. Personal data never loses its category by accident.

### 17.4.5.2 Combining values joins categories

When values combine, the result takes the higher level and every category of either. Declare a second category, `Location`, for the door of each stop, and send the courier the phone and the door in one text:

```diff include="steps/26-categories..steps/28-two-categories:src/courier.una" context="1" title="src/courier.una"
--- a/src/courier.una
+++ b/src/courier.una
@@ -2,3 +2,3 @@
 
---- A stop on a delivery route. The phone number is personal data.
+--- A stop on a delivery route. The phone number is personal data, and the door is a location.
 kind Stop
@@ -7,2 +7,3 @@
   phone: secret[PII] Text
+  door: confidential[Location] Text
 
@@ -19,3 +20,3 @@
   for stop in stops
-    @courier.book(stop.order, phone: stop.phone)
+    @courier.book(stop.order, phone: "{stop.phone}, {stop.door}")
 
@@ -31,3 +32,3 @@
 =
-  let route = [Stop(order: "A-1001", city: "Recife", phone: "+55 81 5550 0101"), Stop(order: "A-1002", city: "Olinda", phone: "+55 81 5550 0102")]
+  let route = [Stop(order: "A-1001", city: "Recife", phone: "+55 81 5550 0101", door: "Rua do Sol 10"), Stop(order: "A-1002", city: "Olinda", phone: "+55 81 5550 0102", door: "Rua da Aurora 5")]
   book_route(route) with @courier = accepting()
```

```text include="steps/28-two-categories/expected/rendered.txt#L1-L6"
[U4003] Error: `@courier.book` accepts `secret[PII]` data, and this argument is `secret[Location, PII]`
    ╭─[ src/courier.una:21:38 ]
    │
 21 │     @courier.book(stop.order, phone: "{stop.phone}, {stop.door}")
    │                                      ─────────────┬─────────────
    │                                                   ╰─────────────── `@courier.book` accepts `secret[PII]` data, and this argument is `secret[Location, PII]`
```

The text joins `secret[PII]` and `confidential[Location]` into `secret[Location, PII]`: the higher level, and both categories. The courier accepts personal data, not locations, so the combined text is refused. To send both, the courier's ceiling would name both: `accepts secret[Location, PII]`.

### 17.4.5.3 A category must be declared

A category that `[labels] categories` does not declare is U4007. A misspelled category cannot create a new, unchecked kind of data:

```diff include="steps/26-categories..steps/29-misspelled:src/courier.una" context="1" title="src/courier.una"
--- a/src/courier.una
+++ b/src/courier.una
@@ -6,3 +6,3 @@
   city: Text
-  phone: secret[PII] Text
+  phone: secret[PIl] Text
 
```

```text include="steps/29-misspelled/expected/rendered.txt#L1-L6"
[U4007] Error: label category `PIl` is not declared in `[labels] categories` of `una.toml`
   ╭─[ src/courier.una:7:17 ]
   │
 7 │   phone: secret[PIl] Text
   │                 ─┬─
   │                  ╰─── label category `PIl` is not declared in `[labels] categories` of `una.toml`
```

The help line offers the declared name that is closest, and `una fix .` applies it.

### 17.4.5.4 Dropping a category takes a policy

Dropping a category is a release, like lowering a level: only a policy can do it ([section 17.5](https://una-lang.org/en/learn/information-flow/releasing-data-policies-and-trusted-modules/#s17-5)), and its `to` type shows the label it gives.

## 17.4.6 Choosing categories

:::decide
**Which to use:**

| You want to… | Do this |
| --- | --- |
| Keep one kind of data, such as personal data, away from services that may receive other secrets | declare a category, such as `PII`, and put it on the data and on the ceilings that may receive it |
| Tell apart two kinds of data that some services receive separately | one category for each, such as `Location` and `PII` |
| Mark data that only differs in how sensitive it is | a level, with no new category |
:::

Declare few categories, each for a kind of data that a law, a contract or a promise to customers treats apart.

## 17.4.7 Check yourself: categories

A fraud-screening service accepts the highest level, `restricted`, and no category. Give it the courier's booking:

```diff include="steps/26-categories..steps/30-restricted:src/courier.una" context="1" title="src/courier.una"
--- a/src/courier.una
+++ b/src/courier.una
@@ -12,3 +12,3 @@
   op book(order: Text, phone: Text) -> Unit
-    accepts secret[PII]
+    accepts restricted
 
```

Does the phone, `secret[PII]`, reach it?

:::answer Show the answer
No:

```text include="steps/30-restricted/expected/rendered.txt#L1"
[U4003] Error: `@courier.book` accepts `restricted` data, and this argument is `secret[PII]`
```

`secret` is below `restricted`, so the level fits. But `PII` is not among the ceiling's categories, which are none. A label flows only when both its level and its categories fit.
:::
