Handling CAM Charge Variations in Lease Taxonomy Design

The narrow decision this page resolves: when a portfolio mixes fixed-rate, pro-rata, expense-stop, and base-year common-area-maintenance (CAM) clauses, do you store each as its own record shape, or as one polymorphic node whose calculation method is a typed field? Store them separately and every downstream reader has to know which table to join; collapse them into a flat key-value blob and you lose the cap behaviour, denominator basis, and exclusion list that actually drive the number an auditor will later try to reconstruct. The answer that survives a year-end reconciliation is a single CAM node — a discriminated structure where calculation_type selects which fields are required and which validation rules fire — so that one ingestion path, one storage shape, and one billing reader cover every variation in the portfolio.

Where this fits in the taxonomy

CAM recovery is an operating-expense pass-through, not a base-rent adjustment, so it deliberately routes through a different branch of the taxonomy than base-rent escalation. This page sits one level below the escalation formula mapping cluster inside Core Architecture & Lease Taxonomy. By the time a CAM clause reaches this node it has already been labelled by the clause classification systems upstream and cleaned to typed decimals and ISO dates by the metadata normalization standards at the ingestion boundary. The validated node produced here is what feeds the lease data models for storage; anything the validator cannot reconcile diverts to fallback routing logic for manual review rather than emitting a guessed charge.

The four CAM variations, side by side

Every commercial CAM clause reduces to one of four calculation methods. The differences are not cosmetic — each method demands a different required-field set and a different reconciliation behaviour, which is exactly why a flat schema fails and a discriminated node succeeds.

Cap behaviour is an orthogonal axis layered on top of the method. A cumulative cap tracks the running total across the term and only bites when the lifetime increase exceeds the threshold; a non_cumulative cap resets every fiscal year. Modelling the cap as its own enum rather than folding it into the method keeps the two concerns independent — a pro-rata clause can carry any cap type, and so can an expense-stop clause, without a combinatorial explosion of record shapes.

Recommended implementation: one polymorphic node

The production-grade approach is a single pydantic v2 model whose cross-field rules are consolidated in one model_validator so the required-field matrix above is enforced at construction time. Cross-field dependencies such as “base_year_amount is required when the method is expense_stop” belong in a model_validator (which runs after every field is set), not in a per-field validator that would depend on field-ordering guarantees. Monetary fields are Decimal throughout — floating-point drift compounds across a multi-tenant rent roll until the books disagree with the ledger.

from decimal import Decimal, ROUND_HALF_UP
from enum import Enum
from typing import Optional, List
from pydantic import BaseModel, Field, field_validator, model_validator

class CalculationType(str, Enum):
    FIXED = "fixed"
    PRO_RATA = "pro_rata"
    EXPENSE_STOP = "expense_stop"
    BASE_YEAR = "base_year"

class DenominatorBasis(str, Enum):
    GLA = "gla"            # gross leasable area
    NRA = "nra"            # net rentable area
    LEASED_AREA = "leased_area"

class CapType(str, Enum):
    NONE = "none"
    ABSOLUTE = "absolute"
    CUMULATIVE = "cumulative"
    NON_CUMULATIVE = "non_cumulative"

class CAMChargeTaxonomy(BaseModel):
    lease_id: str = Field(..., description="Unique lease identifier")
    calculation_type: CalculationType
    denominator_basis: DenominatorBasis
    cap_type: CapType = CapType.NONE
    cap_value: Optional[Decimal] = Field(None, ge=0)
    base_year_amount: Optional[Decimal] = Field(None, ge=0)
    exclusion_matrix: List[str] = Field(
        default_factory=list, description="Standardized expense codes to exclude"
    )
    reconciliation_frequency: str = Field(
        "annual", pattern="^(monthly|quarterly|annual)$"
    )

    @model_validator(mode="after")
    def enforce_business_rules(self) -> "CAMChargeTaxonomy":
        # A cap value is meaningless without a cap.
        if self.cap_value is not None and self.cap_type == CapType.NONE:
            raise ValueError("cap_value must be None when cap_type is 'none'")
        if self.cap_value is None and self.cap_type != CapType.NONE:
            raise ValueError(f"cap_value is required for cap_type '{self.cap_type.value}'")
        # Stop/base-year methods need a base figure to measure the excess against.
        if self.calculation_type in (CalculationType.EXPENSE_STOP, CalculationType.BASE_YEAR):
            if self.base_year_amount is None:
                raise ValueError(
                    "base_year_amount is required for expense_stop and base_year methods"
                )
        # A fixed $/SF rate only makes sense against the tenant's own leased area.
        if self.calculation_type == CalculationType.FIXED:
            if self.denominator_basis != DenominatorBasis.LEASED_AREA:
                raise ValueError("fixed rate must use leased_area as denominator_basis")
        return self

    @field_validator("exclusion_matrix")
    @classmethod
    def validate_exclusions(cls, v: List[str]) -> List[str]:
        # Exclusions must reference standardized expense codes, never free text.
        valid_prefixes = ("CAM_", "OP_", "TAX_", "UTIL_")
        for code in v:
            if not code.startswith(valid_prefixes):
                raise ValueError(f"invalid exclusion code: {code!r}; use a standardized prefix")
        return v

    def pro_rata_factor(self, tenant_sqft: Decimal, denominator_sqft: Decimal) -> Decimal:
        if self.calculation_type != CalculationType.PRO_RATA:
            raise RuntimeError("pro_rata_factor only valid for pro_rata calculation_type")
        if denominator_sqft <= 0:
            raise ValueError("denominator square footage must be greater than zero")
        return (tenant_sqft / denominator_sqft).quantize(
            Decimal("0.0001"), rounding=ROUND_HALF_UP
        )

The model is the contract between legal abstraction and financial execution: it rejects a fixed clause that claims a building-wide denominator, a stop clause missing its base figure, and a cap value attached to an uncapped clause — all before the record can reach storage. The pro_rata_factor helper keeps the share calculation side-effect-free and Decimal-quantized, so a billing engine can call it without re-reading the contract. Wrap construction in try/except ValidationError at the ingestion seam to quarantine malformed clauses rather than letting them poison the rent roll.

Edge cases specific to commercial CAM clauses

Real leases break naive taxonomies in predictable ways, and each of these belongs in the regression corpus, not in a production incident:

• Amendment riders that flip the method. A renewal rider that converts a clause from pro_rata to a negotiated fixed rate must append a new, date-bounded node version rather than mutating the original. Precedence is resolved later by effective date in the lease data models layer — never inside the validator, which would erase the audit trail.
• Overlapping or contradictory exclusions. A clause that excludes TAX_PROPERTY in the base grant but re-includes it in a rider needs de-duplication with last-writer-wins by effective date, not a silent set union that drops the override.
• Gross-up provisions. Many pro-rata clauses gross expenses up to a 95% occupancy assumption before applying the share factor. That assumption is a field on the node, not a hard-coded constant — two clauses in the same building can specify different gross-up percentages.
• Mixed denominators across a portfolio. One asset measures to BOMA net rentable area, another to gross leasable area. Storing denominator_basis explicitly and cross-referencing certified floor plans prevents a manual override from quietly mixing the two and skewing every tenant’s share.
• Non-breaking spaces and OCR drift in scanned riders. A clause lifted from a scanned amendment may carry $12 . 50 with stray spacing or a non-breaking space inside the figure; the normalization layer must canonicalize the number before the validator sees it.

When to escalate

This taxonomy node is deliberately strict, and strictness means some clauses will refuse to validate — which is the correct behaviour, not a bug. Escalate to the manual review queue through fallback routing logic whenever:

• the extracted calculation_type is ambiguous because the clause blends two methods (for example, a fixed rate “or pro-rata share, whichever is greater”) — these need a human to pick the controlling method or model both and compare;
• a cumulative cap is present but the prior-period charge history needed to evaluate it is missing, so the running total cannot be computed deterministically;
• the denominator basis cannot be reconciled against a certified floor plan, which usually means the source clause was scanned and the figure should first route back through OCR preprocessing;
• the extraction confidence for any monetary or area field falls below the review threshold, because a wrong CAM figure posts real money against a tenant.

The rule of thumb mirrors escalation mapping: a clause that fails the consistency check, or carries a cap with no history to evaluate it against, diverts regardless of confidence score. It is cheaper to queue one clause for a person than to reverse a year of mis-billed reconciliations.

Frequently asked questions

Related

• Escalation Formula Mapping — the parent cluster that turns rent-adjustment clauses into a deterministic calculation engine.
• Mapping Commercial Lease Clauses to Standardized JSON Schemas — the discriminated-union pattern this CAM node is one instance of.
• Metadata Normalization Standards — the typed-decimal and ISO-date contract this node depends on at its input boundary.
• Lease Data Models — where versioned CAM nodes are stored and amendment precedence is resolved.
• Fallback Routing Logic — where ambiguous and low-confidence CAM clauses divert for manual review.

← Back to Escalation Formula Mapping

← Back to Escalation Formula Mapping