Check messages: citations

Generated from the rslc compiler.

E-PROVENANCE

A filed number needs a citation. Each table, constant and rounding states a number from the filing. The check asks each one to cite the region of the source document that prints it. A citation tells a reviewer where to look. A number that the filing leaves unstated, such as a unit conversion, says why with [reason: "…"]. Example The constant rate_per_1000 carries a filed rate and lacks a citation.

Constants = {
    rate_per_1000 = 2
}

rslc check bad/rater.rsl

FAIL bad/rater.rsl (strict)
error: E-PROVENANCE bad/rater.rsl:17:5: constant `rate_per_1000` has no citation
  = because: every filed number cites the filing region that states it; a number no filing states says why in `[reason: "…"]`
  = help: cite the region that states it, `rate_per_1000 [cite: manual:p12] = …`, or say why no filing does: `rate_per_1000 [reason: "unit conversion"] = …`
  = applicability: manual
cost premium: 1 (each list of size 1: 1, 3: 1, 10: 1)

Fix Cite the page that prints the rate.

Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}

Complete files

bad/rater.rsl

spec {
    rsl: "0.4.1",
    carrier: "Example Mutual",
    state: AZ,
    product: "Staffing Liability",
    effective_date: 2026-01-01
}

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

Constants = {
    rate_per_1000 = 2
}

Records = {
    Policy = {
        inputs {
            payroll: Num {precision: int} where self in [0, 100000000]
        },
        step rating {
            premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
        }
    }
}

RatingOutcomes = {
    premium: Policy.premium
}

good/rater.rsl

spec {
    rsl: "0.4.1",
    carrier: "Example Mutual",
    state: AZ,
    product: "Staffing Liability",
    effective_date: 2026-01-01
}

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

Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}

Records = {
    Policy = {
        inputs {
            payroll: Num {precision: int} where self in [0, 100000000]
        },
        step rating {
            premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
        }
    }
}

RatingOutcomes = {
    premium: Policy.premium
}

E-SOURCE-SCHEMA

A source has an artifact and a kind. Sources declares each document a rater cites. A source has exactly two fields. artifact holds the ID of the stored document, written artifact("<uuid>") with a lowercase UUID. kind is the file type, written bare: pdf, xlsx, csv, html, zip, png or parquet. A citation such as [cite: manual:p3] names a source and a region inside it. The fixed shape lets every tool open the same stored document at the cited page. Example The source manual has a third field, title.

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

rslc check bad/rater.rsl

FAIL bad/rater.rsl (strict)
error: E-SOURCE-SCHEMA bad/rater.rsl:13:9: source 'manual' has unknown field 'title'. A Source has exactly these fields: artifact: artifact("<uuid>"), kind: pdf | xlsx | csv | html | zip | png | parquet. Delete it or move the text to a comment.

Fix Delete the extra field. Text that helps a reader, such as the document’s title, fits in a comment.

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

Other causes

A source lacks artifact or kind.
A source states one field twice.
kind is a quoted string such as "pdf", or a file type outside the list.
artifact holds something other than artifact("…"), such as a bare string or file("manual.pdf").
The ID inside artifact("…") is something other than a lowercase UUID, such as "rate-manual".

Complete files

bad/rater.rsl

spec {
    rsl: "0.4.1",
    carrier: "Example Mutual",
    state: AZ,
    product: "Staffing Liability",
    effective_date: 2026-01-01
}

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

Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}

Records = {
    Policy = {
        inputs {
            payroll: Num {precision: int} where self in [0, 100000000]
        },
        step rating {
            premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
        }
    }
}

RatingOutcomes = {
    premium: Policy.premium
}

good/rater.rsl

spec {
    rsl: "0.4.1",
    carrier: "Example Mutual",
    state: AZ,
    product: "Staffing Liability",
    effective_date: 2026-01-01
}

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

Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}

Records = {
    Policy = {
        inputs {
            payroll: Num {precision: int} where self in [0, 100000000]
        },
        step rating {
            premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
        }
    }
}

RatingOutcomes = {
    premium: Policy.premium
}

E-CITATION

A citation names a declared source and region. A citation names a source and a region inside it: [cite: manual:p3]. The check asks for a source that Sources declares and a region that fits the source’s kind:

pdf: a page p33 or a page range pp20-24
xlsx: a cell 'Sheet name'!A2 or a cell range 'Sheet name'!A2:F20
csv and parquet: row 12 or rows 12-20
html: anchor "rates"
zip: member "rates/manual.pdf"
png: image

A citation that resolves lets a reviewer open the document at the place that states the number. Example The constant cites manual:page3, and manual is a PDF, so the region reads p3.

Constants = {
    rate_per_1000 [cite: manual:page3] = 2
}

rslc check bad/rater.rsl

FAIL bad/rater.rsl (strict)
error: E-CITATION bad/rater.rsl:17:26: citation 'manual:page3': region `page3` is not a pdf region; write `p33` or `pp20-24`.

Fix Write the page as p3.

Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}

Other causes

The citation names a source that Sources lacks, such as filing:p3 beside a source named manual.
A page or row number is 0, or a range runs backwards; pages and rows start at 1.
A citation sits on a type or a source; cite the table, constant, step, calculation or input that uses the document.
A table’s otherwise row lacks a citation; write otherwise [cite: manual:p3]: { … }.
A table column maps to the CSV header cite; that header holds a citation for each row.
A cell of a table’s cite column holds a citation the table leaves undeclared, or text of another shape.
A then: tie priority of a ranking function such as argmax lacks a citation; write then [cite: manual:p3]: ….
A placeholder carries @manual:p3 after nl "…"; cite the calculation in its place.
A calculation’s body is a quoted string; write a placeholder as nl "…".

Complete files

bad/rater.rsl

spec {
    rsl: "0.4.1",
    carrier: "Example Mutual",
    state: AZ,
    product: "Staffing Liability",
    effective_date: 2026-01-01
}

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

Constants = {
    rate_per_1000 [cite: manual:page3] = 2
}

Records = {
    Policy = {
        inputs {
            payroll: Num {precision: int} where self in [0, 100000000]
        },
        step rating {
            premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
        }
    }
}

RatingOutcomes = {
    premium: Policy.premium
}

good/rater.rsl

spec {
    rsl: "0.4.1",
    carrier: "Example Mutual",
    state: AZ,
    product: "Staffing Liability",
    effective_date: 2026-01-01
}

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

Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}

Records = {
    Policy = {
        inputs {
            payroll: Num {precision: int} where self in [0, 100000000]
        },
        step rating {
            premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
        }
    }
}

RatingOutcomes = {
    premium: Policy.premium
}

E-PROVENANCE-RUNTIME

Provenance stays out of rating data. Provenance says where a number comes from. In RSL it lives in citations, such as [cite: manual:p3] on a table. The compiler checks each citation and leaves it out of the rating calculation. The check stops provenance that travels as data: a table column of source pages, an input that holds a document, or a flag that says someone verified the rates. A caller would have to supply such a value on every request, and a reviewer would find the evidence in two places. Example The table HazardRate declares a source_page column beside its rate.

    HazardRate [cite: manual:p3] :
        table dims (hazard: Hazard) -> {
            rate: Rate,
            source_page: Num {precision: int}
        }
}

hazard,rate,source_page
low,2,3
high,3.5,3

rslc check bad/rater.rsl

FAIL bad/rater.rsl (strict)
error: E-PROVENANCE-RUNTIME bad/rater.rsl:27:13: table 'HazardRate' column 'source_page' carries provenance at runtime. Delete the column and its CSV data, and cite the table: HazardRate [cite: source:region] : (…). For rows from another region, declare that citation on the table too and name it in the optional 'cite' column.

Fix Delete the column from the table and from its CSV file. The table’s citation already records the page. When rows come from different pages, declare each citation on the table and name each row’s citation in a CSV column headed cite.

    HazardRate [cite: manual:p3] :
        table dims (hazard: Hazard) -> {
            rate: Rate
        }
}

hazard,rate
low,2
high,3.5

Other causes

A table’s CSV file has a column headed source_page, source_part, __cite or a name that starts with _source.
An input has the type Source.
An enum lists artifact IDs as members; declare each document in Sources.
A Bool input whose name ends in _verified, _supplied or _confirmed stays unread by every calculation and rule.

Complete files

bad/rater.rsl

spec {
    rsl: "0.4.1",
    carrier: "Example Mutual",
    state: AZ,
    product: "Staffing Liability",
    effective_date: 2026-01-01
}

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

Types = {
    Hazard = {
        low,
        high
    }
}

Tables = {
    HazardRate [cite: manual:p3] :
        table dims (hazard: Hazard) -> {
            rate: Rate,
            source_page: Num {precision: int}
        }
}

Records = {
    Policy = {
        inputs {
            payroll: Num {precision: int} where self in [0, 100000000],
            hazard: Hazard
        },
        step rating {
            rate: Rate = lookup!(HazardRate, self.hazard).rate,
            premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * self.rate, 2, half_up)
        }
    }
}

RatingOutcomes = {
    premium: Policy.premium
}

bad/tables/HazardRate.csv

hazard,rate,source_page
low,2,3
high,3.5,3

good/rater.rsl

spec {
    rsl: "0.4.1",
    carrier: "Example Mutual",
    state: AZ,
    product: "Staffing Liability",
    effective_date: 2026-01-01
}

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

Types = {
    Hazard = {
        low,
        high
    }
}

Tables = {
    HazardRate [cite: manual:p3] :
        table dims (hazard: Hazard) -> {
            rate: Rate
        }
}

Records = {
    Policy = {
        inputs {
            payroll: Num {precision: int} where self in [0, 100000000],
            hazard: Hazard
        },
        step rating {
            rate: Rate = lookup!(HazardRate, self.hazard).rate,
            premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * self.rate, 2, half_up)
        }
    }
}

RatingOutcomes = {
    premium: Policy.premium
}

good/tables/HazardRate.csv

hazard,rate
low,2
high,3.5

E-PROVENANCE-COMMENT

Evidence belongs in a citation. A comment that starts with source:, sources: or readiness: records evidence in a place the compiler leaves unread. The check asks for that evidence as a citation on the declaration the comment describes: [cite: manual:p3]. The compiler checks a citation against Sources, and tools open the document at the cited page. A comment drifts as the rater changes around it. Comments that explain a calculation in other words pass the check. Example A comment above the constant repeats where the rate comes from.

Constants = {
    # source: rate manual, page 3
    rate_per_1000 [cite: manual:p3] = 2
}

rslc check bad/rater.rsl

FAIL bad/rater.rsl (strict)
error: E-PROVENANCE-COMMENT bad/rater.rsl:17:5: comment '# source: …' records evidence that the compiler cannot check. Cite the declaration instead with [cite: source:region], or delete the comment.
  = because: evidence lives only in `[cite: source:region]`, which the compiler checks; a comment is a second, unchecked spelling of it
  = help: put the region in a citation on the declaration the comment describes, `name: T [cite: <source>:<region>] = …`, then delete the comment
  = applicability: placeholders

Fix Delete the comment; the constant’s citation already names the page. Where the declaration lacks a citation, move the page from the comment into [cite: …] first.

Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}

Complete files

bad/rater.rsl

spec {
    rsl: "0.4.1",
    carrier: "Example Mutual",
    state: AZ,
    product: "Staffing Liability",
    effective_date: 2026-01-01
}

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

Constants = {
    # source: rate manual, page 3
    rate_per_1000 [cite: manual:p3] = 2
}

Records = {
    Policy = {
        inputs {
            payroll: Num {precision: int} where self in [0, 100000000]
        },
        step rating {
            premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
        }
    }
}

RatingOutcomes = {
    premium: Policy.premium
}

good/rater.rsl

spec {
    rsl: "0.4.1",
    carrier: "Example Mutual",
    state: AZ,
    product: "Staffing Liability",
    effective_date: 2026-01-01
}

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

Constants = {
    rate_per_1000 [cite: manual:p3] = 2
}

Records = {
    Policy = {
        inputs {
            payroll: Num {precision: int} where self in [0, 100000000]
        },
        step rating {
            premium: Premium [cite: manual:p3] = round(self.payroll / 1000 * rate_per_1000, 2, half_up)
        }
    }
}

RatingOutcomes = {
    premium: Policy.premium
}

Get started

Tutorials

Implement a filing

Test a rater

Quote and underwrite

Concepts

Reference

Check messages: citations

E-PROVENANCE

E-SOURCE-SCHEMA

E-CITATION

E-PROVENANCE-RUNTIME

E-PROVENANCE-COMMENT

​E-PROVENANCE

​E-SOURCE-SCHEMA

​E-CITATION

​E-PROVENANCE-RUNTIME

​E-PROVENANCE-COMMENT

E-PROVENANCE

E-SOURCE-SCHEMA

E-CITATION

E-PROVENANCE-RUNTIME

E-PROVENANCE-COMMENT