Annotations and decorators

Annotations and decorators in Brossa are metadata tools used to control how datapoints behave within the system, particularly in relation to the user interface and dependency tracing. They help developers manage visibility, computation logic, and tracing behavior in a structured and readable way.

Annotations are prefixed with @ and placed before datapoint declarations. Multiple annotations can be combined on a single datapoint, and some annotations (like @hidden) automatically imply others (like @derived). This allows you to declaratively specify complex behaviours while keeping your business logic clean.

Select ↓ after a description in the table below to navigate to detailed reference information for that annotation.

Quick reference

Annotation Description

@adjustable

Allows a datapoint to be modified after a quote/endorsement is accepted. ↓

@agg(…​)

Aggregation annotation with configurable parameters. ↓

@collectable

Allows lists and sets to be directly input rather than calculated. ↓

@contract-builder

Includes this datapoint in the output record for contract builder integration. ↓

@contract-builder-record

Marks this datapoint as the output record for contract builder integration. ↓

@derived

Marks a datapoint as read-only; always uses the provided definition. ↓

@hidden

Hides a datapoint from the frontend (implies @derived). ↓

@no-auto-start

Prevents async tasks from starting automatically; requires manual trigger. ↓

@no-tracing

Excludes this datapoint from dependency tracing entirely. ↓

@overall

Marks a datapoint as policy-level rather than version-specific. ↓

@shallow

Limits the depth of dependency tracing for this datapoint. ↓

@workflow

Restricts datapoint to only use workflow state data, not policy data. ↓

Detailed reference

UI control

@derived

Marks a datapoint as read-only and calculated. The datapoint will always use its provided definition and cannot be modified by users in the UI.

premium: Number<policy.currency>;
tax_rate: Percent = 20%;

@derived
tax: Number<policy.currency> = premium * tax_rate;

Use @derived when you have calculated values that should be transparent to users but not editable.

@hidden

Hides a datapoint from the frontend user interface. Hidden datapoints are automatically treated as @derived since users cannot interact with them.

@hidden
internal_rate: Percent = 0.5%;

@derived @hidden
total: Number<policy.currency> = premium + tax;

Use @hidden for internal calculations, intermediate values, or sensitive data that shouldn’t be exposed to users.

@adjustable

Allows a datapoint to be modified after a quote or endorsement has been accepted. This is useful for values that may need adjustment during the policy lifecycle.

@adjustable
coverage_amount: Number = 100000;

@hidden @adjustable
adjusted_premium: Number = base_premium * adjustment_factor;

Use @adjustable for datapoints that business users may need to modify post-acceptance.

Tracing and performance

@shallow

Limits the depth of dependency tracing when explaining or analyzing this datapoint. Only immediate dependencies are identified, preventing deep traversal of the dependency chain.

@derived @hidden
rate_percentage: Percent = 0.5%;

internal_premium: Number = 1_000_000 * rate_percentage;

@derived @shallow
final_premium: Number = internal_premium / 1000;

Use @shallow to optimise performance for complex calculations or when you want to limit the explanation depth shown to users.

@no-tracing

Completely excludes this datapoint from dependency tracing and explanation systems.

@no-tracing
debug_value: Number = some_complex_calculation();

Use @no-tracing for debugging values, temporary calculations, or datapoints that shouldn’t appear in dependency analysis.

Data contexts and versioning

@overall

Allows a datapoint to calculate values across all policy versions instead of being restricted to a single version. This is useful for computing policy-wide totals, such as overall premiums when a policy has multiple endorsements.

@overall
total_premium: Number = calculate_across_all_versions();

@overall
policy_status: String = determine_current_status();

Use @overall to calculate values across the whole policy, such as overall premiums when a policy has endorsements.

@workflow

Marks a datapoint as operating in workflow context. Workflow context is more restricted than version or overall contexts: datapoints here have no access to normal stored policy data, and can only depend on workflow state.

@workflow
current_step: String = get_workflow_step();

@workflow
approval_required: Boolean = check_workflow_approval_status();

Use @workflow for datapoints that need to operate based purely on workflow state, without referencing policy data.

Integration and output

@contract-builder

Marks a datapoint to be included in the output record for contract builder integration.

@contract-builder
policy_number: String = generate_policy_number();

@contract-builder
premium_amount: Number = calculate_final_premium();

Use @contract-builder to specify which datapoints should be included in the contract builder output.

@contract-builder-record

Marks a datapoint as the output record for contract builder integration. The shape of the record is determined by hardcoded contract builder configuration in the backend. The configuration version is determined by the top-level annotation @contract-builder-generator(v1).

@contract-builder-record
output_record: ContractBuilderRecord = build_output_record();

Use @contract-builder-record to define the main output record structure for contract builder integration.

Data processing

@collectable

Marks a datapoint as collectable, rather than derived. By default, scalars are collectable and lists and sets are derived. Use this annotation when you need lists or sets to be directly collected rather than calculated.

@collectable
nexus_responses: List<ResponseRecord> = collect_nexus_data();

@collectable
contract_builder_requests: Set<RequestRecord> = collect_cb_requests();

Use @collectable for lists and sets that need to be directly collected, such as nexus request or response records, or contract builder request records.

@agg(…​)

Aggregation annotation that can accept parameters to control how data is aggregated or processed.

@agg(sum)
total_claims: Number = aggregate_claims_data();

Use @agg(…​) when you need to specify how collections of data should be aggregated or processed.