> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Citations

> How a rater ties each filed number and rule to a page of the filing, and which values need a citation.

A rater cites the filing the way an actuary's working papers do. Each table, constant and
rounding rule names the place in the filing that prints it. A reviewer can then check each
number in a premium against the filing, and `rslc check` confirms each citation is there.

The compiler checks citation presence, declared source names, and region syntax. A reviewer checks that the cited region supports the implemented value or rule.
Use real source artifact IDs for a published rater. The synthetic examples use placeholder IDs and invented manual pages.

## Name the filed documents

The `Sources` block names each filed document once:

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
Sources = {
    manual: Source = {
        artifact: artifact("00000000-0000-4000-8000-000000000000"),
        kind: pdf
    }
}
```

* `manual` is the short name that each citation uses.
* `artifact(...)` identifies the document in Effective by its artifact ID.
* `kind` is the document type. It sets how a citation points to a place inside it.

| Kind | A citation points to | Examples |
| - | - | - |
| `pdf` | a page or pages | `p33`, `pp20-24` |
| `xlsx` | a cell or a range of cells | `'Rates'!A2`, `'Rates'!A2:F40` |
| `csv` | a row or rows | `row 12`, `rows 12-20` |
| `parquet` | a row or rows | `row 12`, `rows 12-40` |
| `html` | an anchor | `anchor "base-rates"` |
| `zip` | a file inside the archive | `member "rates/manual.pdf"` |
| `png` | the whole image | `image` |

A citation in the wrong form for its document fails the check, such as `manual:row 3` for a `pdf`.
[`E-CITATION`](https://docs.canary.effectiveai.app/rsl/reference/check-messages/citations#e-citation) shows the message and the fix.

## Cite each filed number

Write the citation in brackets after the name. These excerpts quote a small rater with one cited table:

> [accordion] cited/rater.rsl
>
> ```rsl cited/rater.rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> spec {
>     rsl: "0.4.1",
>     carrier: "Example Mutual",
>     state: AZ,
>     product: "Dwelling Fire (citations)",
>     effective_date: 2026-01-01
> }
>
> Sources = {
>     manual: Source = {
>         artifact: artifact("00000000-0000-4000-8000-000000000000"),
>         kind: pdf
>     }
> }
>
> Types = {
>     ProtectionClass = IntBands(1, 4, 7, 10..),
>     Money = Num {precision: 0.01}
> }
>
> Constants = {
>     expense_fee [cite: manual:p9] = 35,
>     per_thousand [reason: "Coverage A is rated per 1,000 of coverage."] = 1000
> }
>
> Tables = {
>     BaseRate [cite: manual:p3, cite: manual:p4] :
>         table dims (protection: ProtectionClass) -> {
>             rate: Rate
>         }
> }
>
> Records = {
>     Policy = {
>         inputs {
>             coverage_a: Money where self in [50000, 2000000],
>             protection_class: Num {precision: int}
>                 where self in [1, 10] [code: "PROTECTION-CLASS", message: "Protection class must be 1 to 10.", cite: manual:p4]
>         },
>         step premium {
>             base_rate: Rate = lookup!(BaseRate, self.protection_class).rate,
>             premium: Premium [cite: manual:p9] =
>                 round(self.coverage_a / per_thousand * self.base_rate + expense_fee, 0, half_up)
>         }
>     }
> }
>
> RatingOutcomes = {
>     premium: Policy.premium
> }
> ```
>
> Its table file, `cited/tables/BaseRate.csv`, is under "Cite each row of a table" below.

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
Constants = {
    expense_fee [cite: manual:p9] = 35,
    per_thousand [reason: "Coverage A is rated per 1,000 of coverage."] = 1000
}

Tables = {
    BaseRate [cite: manual:p3, cite: manual:p4] :
        table dims (protection: ProtectionClass) -> {
            rate: Rate
        }
}
```

These values each need a citation:

* each table, and each table's `otherwise` row;
* each constant;
* each calculation that rounds, or the step that holds it;
* the calculation that rounds each premium the rater returns, on the calculation itself;
* each rule that breaks a tie when the rater picks the largest or smallest element of a list.

A number that the filing leaves out, such as a unit conversion, carries `[reason: "..."]` in
place of a citation. Keep the reason to 120 characters. A table can cite several pages, as
`BaseRate` does.

## Cite a rule

A rule from the filing cites the page that states it. The citation travels in each refusal of
that rule, so the person who sent the request sees where the rule comes from.
The check leaves a rule's citation optional, and a refusal of an uncited rule holds `"cite": null`:

```rsl theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
            protection_class: Num {precision: int}
                where self in [1, 10] [code: "PROTECTION-CLASS", message: "Protection class must be 1 to 10.", cite: manual:p4]
```

> [accordion] Row-level citations and evidence comments
>
> ## Cite each row of a table
>
> When rows of one table come from different pages, add a `cite` column to the CSV. Each cell names
> one of the table's own citations:
>
> ```csv cited/tables/BaseRate.csv theme={"languages":{"custom":["languages/rsl.tmLanguage.json"]}}
> protection,rate,cite
> 1,2.10,manual:p3
> 4,2.60,manual:p3
> 7,3.40,manual:p3
> 10,5.20,manual:p4
> ```
>
> The rater ignores the `cite` column when it rates.
>
> ## Keep evidence in citations
>
> The check reads citations, and it reads comments as plain text. So a comment that starts with
> `source:`, `sources:` or `readiness:` fails the check.
> [`E-PROVENANCE-COMMENT`](https://docs.canary.effectiveai.app/rsl/reference/check-messages/citations#e-provenance-comment) shows the message and the fix.
>
> Evidence also stays out of the rating data. A table column or an input that holds a source page
> fails the check with [`E-PROVENANCE-RUNTIME`](https://docs.canary.effectiveai.app/rsl/reference/check-messages/citations#e-provenance-runtime).

## Where citations go

* A rule's citation appears in each refusal of that rule.
* The bundle lists the sources and the citations of each table, input and calculation.
* The bundle's ID covers the citations, so a changed citation gives a new bundle ID.

## Related

* [Checks and guarantees](https://docs.canary.effectiveai.app/rsl/explanation/checks-and-guarantees.md) explains the compiler checks and their limits.
* [Round a premium](https://docs.canary.effectiveai.app/rsl/how-to/round-a-premium.md) shows where the rounding citation goes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.