--- title: "Understanding compliance rules in LUSID" slug: "understanding-compliance-rules-and-templates" updated: 2026-08-12T09:28:02Z published: 2026-08-12T09:28:02Z canonical: "support.lusid.com/understanding-compliance-rules-and-templates" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # Understanding compliance rules in LUSID When a compliance rule runs, LUSID does the following: 1. Values the portfolios the rule applies to 2. Sorts the resulting contributions into groups 3. Tests each group against a limit A **contribution** is one row from that valuation, that is, a single priced holding, or order in a pre-trade run, with reference data. A **group** is a collection of contributions. It’s important to keep the three steps above in mind to understand templates, variations, and rules: | Term | What it defines | Example | | --- | --- | --- | | **Template** | The type of compliance check, with gaps left for numbers | *Split the portfolio by an attribute, then check no single part is too large a share of the whole* | | **Variation** | A version of that compliance check (template) | *Check each portfolio separately, or add them together and check the combined total* | | **Rule** | The specifics of a compliance check | *Split by country, measure market value, limit 20%, warn at 18%, applies to European Equity funds* | The separation of template, variation, and rule allows you to run several rules with different limits from one compliance check. You choose the template and variation on the **Create compliance rule** screen, then customise your limits. Note that variations of the same template can behave very differently, so read the variation’s description before selecting it. [See below.](/v1/docs/understanding-compliance-rules-and-templates#how-does-lusid-apply-a-compliance-rule-to-multiple-portfolios) ## Compliance rule operations The sequence of steps that form a template draws from five types of operation: | Operation | What it does | Example | | --- | --- | --- | | **Group by** | Subdivides each existing group by a single field. For example, grouping by country gives one group per country. | Group by `Instrument/Finbourne-Examples/Country` | | **Filter** | Removes individual contributions, for example `cash`. Does not change the number of groups. | Filter out instruments with an `AssetClass` of `Cash` | | **Group filter** | Removes whole groups rather than contributions within them. | Filter out portfolios with a `Portfolio/Finbourne-Examples/SingleCountry` property value of `true` | | **Recombine** | Merges every group back into one. | Merge per-country groups back into one group per portfolio | | **Check** | Tests each group and sorts them into passes and failures. Always the final step. | Check if grouped and filtered contributions contribute less than 20% `Valuation/PVinReportCcy`; issue a warning if contributions are over 18% | The **group by**, **filter**, **group filter**, and **recombine** operations form and narrow groups for the final **check** step to assess as a pass or fail. For example, to create a rule that checks no portfolio has more than 20% exposure to any one country, you could split the rule into the following sequence of operations: 1. Group by portfolio 2. Filter out cash contributions 3. Group by country 4. Check whether each country group is below 20% of its portfolio’s value ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/compliancev1.png) Note the **Steps** on the left of the diagram; the template creator names each step, and those names are what you see in a compliance run result. [See how to interpret compliance run results](/v1/docs/how-do-i-perform-a-pre-trade-compliance-run-and-view-the-results#viewing-and-interpreting-compliance-run-results). ## How does LUSID apply a compliance rule to multiple portfolios? Each compliance rule applies to a LUSID [portfolio group](/v1/docs/what-is-a-portfolio-group). All compliance rules begin with a valuation; LUSID considers every contribution from every portfolio a single group at this point in the sequence. If no step in the sequence groups by portfolio, LUSID checks all the portfolios added together. For example, LUSID would measure a 20% country limit against the combined value of the whole portfolio group. Variation names tell you how the compliance rule template behaves: - **Standard** variation: Checks each portfolio separately and produces a result per portfolio - **Aggregate** variation: Adds the portfolios together and checks the combined total, producing one result for the whole group For example, using an **aggregrate** variation to create a 20% country limit rule would allow an individual fund to sit above 20%, provided the combined holding across the group stays below it. ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-Y41TRO00.png) ## What data can a compliance rule check? A compliance rule can only check data that already exists in LUSID. For example, a *country of risk* rule might require every instrument you hold to be decorated with the `countryOfRisk` property; if missing the property, LUSID may not assess the holding. The same principle applies to anything you want to measure. A compliance rule comparing market values, for example, requires a recipe capable of pricing everything in the portfolio, otherwise LUSID may not value some holdings. ## Breaches and warnings Every check at the end of a rule has two levels: - **Breach**: Hard limit; LUSID records a group beyond it as a failure and prevents orders being placed (pre-trade). - **Warning**: Soft limit within the hard limit; LUSID records groups past the warning level but within the breach level as a warning, informing you without preventing orders from being placed. > [!NOTE] > Note > > To disable warnings, set both **Breach** and **Warning** to the same value. ## Interpreting compliance run results LUSID provides the building blocks for a compliance rule; confirming that a rule correctly implements your mandate is your responsibility. You can read the lineage of a compliance result to understand the operations LUSID used to produce it. --- ### Diagnosing a result from its lineage #### One line in the lineage covers several portfolios The compliance template [uses an aggregate variation](/v1/docs/understanding-compliance-rules-and-templates#how-does-lusid-apply-a-compliance-rule-to-multiple-portfolios). Choose a standard variation instead. #### Every group at exactly 100% in the lineage The rule template is measuring a figure against itself. Update the template (or contact the creator of the template). #### Fewer holdings than expected in the lineage Check whether the holdings missing from your results are [missing the required reference data](/v1/docs/understanding-compliance-rules-and-templates#what-data-can-a-compliance-rule-check1). #### Unexpected group in the lineage Check what the rule groups by. Grouping on a property with blank values produces a group of its own. An instrument mastered in LUSID represents a financial asset you own or have exposure to. LUSID enables you to model a wide range of securities using instrument types. If suitable data fields do not exist for an entity, you can store extra information by adding any number of properties to it.