Citations

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:

Sources = {
    manual: Source = {
        artifact: artifact("00000000-0000-4000-8000-000000000000"),
        kind: pdf
    }
}

manual is the short name that each citation uses.
artifact is the ID of the stored copy of the document.
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:

FAIL rater.rsl (strict)
error: E-CITATION rater.rsl:26:21: citation 'manual:row 3': region `row 3` is a csv region, but the source kind is pdf; write `p33` or `pp20-24`.

Cite each filed number

Write the citation in brackets after the name:

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:

            protection_class: Num {precision: int}
                where self in [1, 10] [code: "PROTECTION-CLASS", message: "Protection class must be 1 to 10.", cite: manual:p4]

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:

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:

FAIL rater.rsl (strict)
error: E-PROVENANCE-COMMENT rater.rsl:26:5: comment '# source: …' records evidence that the compiler cannot check. Cite the declaration instead with [cite: source:region], or delete the comment.

Citations also stay out of the calculation. An input or table column that carries a citation fails the check.

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.

What rslc checks and guarantees shows the message for a missing citation.
Round a premium shows where the rounding citation goes.

Get started

Comparative pricing

Prepare and validate

Concepts

Rater development

Python reference

Data reference

Name the filed documents

Cite each filed number

Cite a rule

Cite each row of a table

Keep evidence in citations

Where citations go

​Name the filed documents

​Cite each filed number

​Cite a rule

​Cite each row of a table

​Keep evidence in citations

​Where citations go

​Related

Name the filed documents

Cite each filed number

Cite a rule

Cite each row of a table

Keep evidence in citations

Where citations go

Related