# Budget Justification Format Standards

A budget justification that is scientifically sound but structurally non-compliant is rejected at intake, before a single reviewer reads it. Federal sponsors evaluate the narrative that explains every dollar against agency-specific formatting rules — categorical ordering, character ceilings, mandatory cost-principle language — and a deviation as small as an over-length personnel block or a missing allocability statement is enough to trigger an administrative return. This page addresses that failure mode directly: it defines how to treat budget narratives as structured, validated data so that formatting deviations are caught programmatically before submission rather than discovered by a contracting officer. It is one of the compliance domains governed by the broader Core Architecture & RFP Taxonomy, which establishes the schema contracts every downstream formatter depends on.

The three primary federal funders — the National Institutes of Health (NIH), the National Science Foundation (NSF), and the Department of Defense (DoD) — each impose a distinct justification structure. Because a single institution routinely pursues all three concurrently, the practical challenge is not learning one format but encoding all three as machine-checkable rule sets that share a common intermediate representation. The sections below cover the environment you need, the mechanism that turns a narrative into validated data, the production-grade Pydantic implementation, the agency parameter differences, the edge cases that break naive parsers, how the output feeds the rest of the pipeline, and how to test it.

# Prerequisites and Environment Setup

Budget justification validation is a pure-Python workload with no native document dependencies, so the environment is lightweight. Target Python 3.10 or newer — the code below uses structural pattern matching and the modern union syntax that older interpreters reject. Create an isolated environment and install the single runtime dependency plus the test tooling:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install "pydantic>=2.6,<3" pytest

This work assumes the upstream ingestion stage has already run. Raw budget data arrives either as line items exported from an institutional financial system (PeopleSoft, Workday, or a locally maintained ledger) or as text extracted from a sponsor budget form. When the source is a PDF form rather than a structured export, the narrative and line items are first recovered by the RFP ingestion and parsing workflows — specifically the coordinate-aware PDF text extraction with pdfplumber — before any justification rule is applied. This page begins where that stage ends: with per-category amounts and their accompanying narrative text available as Python values.

Two agency-document assumptions matter. First, the character ceilings and category names shown here are illustrative anchors, not frozen constants — NIH revises the SF424 (R&R) application guide and NSF revises its Proposal & Award Policies & Procedures Guide (PAPPG) on a recurring cadence, so the rule tables must be versioned, not hard-coded inline. Second, effort is expressed and validated as a fraction of total professional effort, never as full-time equivalents, because that is the unit NIH and NSF narratives require.

# Core Mechanism: Narratives as Validated Data

The central idea is to stop treating a budget justification as free-form prose and start treating it as a typed record whose fields must satisfy agency constraints. A single line item carries a cost category, an amount, an optional effort fraction, the target agency, and the narrative string that justifies the cost. Validation is then a deterministic function of those fields: does the narrative fit the agency’s character ceiling, does the effort fall in the legal range, does the category belong to the agency’s allowed set?

This mirrors the enforcement philosophy of the compliance validation rule engines: the taxonomy decides what a rule means for a given agency, and a validation layer decides whether a given draft satisfies it. Budget justification is simply the highest-risk instance of that pattern, because financial narratives concentrate the most agency-specific formatting rules per square inch of any proposal section.

The rule surface for a justification record has four dimensions:

• Category membership — each agency defines a closed set of allowable direct-cost categories, and a line item tagged with a category outside that set is invalid regardless of its narrative.
• Narrative length — modular and detailed formats cap the justification block, and NIH, NSF, and DoD apply different ceilings.
• Effort range — any personnel line carrying an effort fraction must sit within 0.0 and 1.0; values above 1.0 almost always signal an FTE-versus-fraction unit error.
• Mandatory phrasing — DoD narratives must assert allowability, allocability, and reasonableness under the governing regulation; the absence of that language is itself a defect.

Encoding all four as declarative validators — rather than as scattered if checks in a rendering script — is what makes the format standard reusable across agencies and auditable across funding cycles.

# Rule-Aware Implementation

The production pattern models each line item as a Pydantic v2 model whose validators enforce the rule surface at construction time, so a malformed justification can never reach the assembly stage. Because the character ceilings are policy that changes, they live in a versioned rule table keyed by agency rather than as literals inside the validator. The field_validator and model_validator hooks then read that table to make their decisions.

from __future__ import annotations

import re
from enum import Enum
from typing import Final

from pydantic import BaseModel, Field, field_validator, model_validator


class Agency(str, Enum):
    NIH = "NIH"
    NSF = "NSF"
    DOD = "DoD"


# Versioned rule table. In production this is loaded from a policy store,
# not defined inline, so PAPPG / SF424 revisions ship as data, not code.
CATEGORY_LIMITS: Final[dict[Agency, int]] = {
    Agency.NIH: 250,   # per modular justification block (illustrative)
    Agency.NSF: 300,
    Agency.DOD: 400,
}

ALLOWED_CATEGORIES: Final[dict[Agency, frozenset[str]]] = {
    Agency.NIH: frozenset(
        {"Personnel", "Fringe Benefits", "Travel", "Equipment", "Supplies", "Other"}
    ),
    Agency.NSF: frozenset(
        {"Personnel", "Equipment", "Travel", "Participant Support", "Other"}
    ),
    Agency.DOD: frozenset(
        {"Personnel", "Equipment", "Travel", "Materials", "Subcontracts", "Other"}
    ),
}

# DoD narratives must assert the three cost principles.
DOD_PRINCIPLES: Final[tuple[str, ...]] = ("allowable", "allocable", "reasonable")


class BudgetLineItem(BaseModel):
    agency: Agency
    category: str
    amount: float = Field(gt=0.0)
    justification: str
    effort_pct: float | None = Field(default=None, ge=0.0, le=1.0)

    @field_validator("justification")
    @classmethod
    def collapse_whitespace(cls, value: str) -> str:
        # Normalize before any length check so PDF-recovered text does not
        # inflate character counts with stray runs of whitespace.
        return re.sub(r"\s+", " ", value.strip())

    @model_validator(mode="after")
    def enforce_agency_rules(self) -> "BudgetLineItem":
        allowed = ALLOWED_CATEGORIES[self.agency]
        if self.category not in allowed:
            raise ValueError(
                f"'{self.category}' is not an allowable {self.agency.value} "
                f"category; expected one of {sorted(allowed)}."
            )

        ceiling = CATEGORY_LIMITS[self.agency]
        length = len(self.justification)
        if length > ceiling:
            raise ValueError(
                f"{self.agency.value} justification is {length} chars, "
                f"over the {ceiling}-char limit."
            )
        if length < 10:
            raise ValueError("Justification is too short to be meaningful.")

        if self.agency is Agency.DOD:
            lowered = self.justification.lower()
            missing = [p for p in DOD_PRINCIPLES if p not in lowered]
            if missing:
                raise ValueError(
                    f"DoD justification must assert {DOD_PRINCIPLES}; "
                    f"missing: {missing}."
                )
        return self


def render_justification(items: list[BudgetLineItem]) -> str:
    """Render agency-compliant justification blocks from validated items."""
    blocks: list[str] = []
    for item in items:
        match item.agency:
            case Agency.NIH:
                block = f"**{item.category}**: {item.justification}"
                if item.effort_pct is not None:
                    block += f" (Effort: {item.effort_pct * 100:.1f}%)"
            case Agency.NSF:
                block = (
                    f"{item.category} supports project activities. "
                    f"{item.justification}"
                )
            case Agency.DOD:
                block = f"**{item.category}** (allowable/allocable): {item.justification}"
        blocks.append(block)
    return "\n\n".join(blocks)

Because every rule fires at construction time, the only way to obtain a BudgetLineItem instance is to pass the agency’s constraints — the type system itself becomes the guarantee that render_justification never emits a non-compliant block. This same typed-record discipline underpins the cross-agency normalization described in standardizing budget justification templates across agencies, which extends the model with a canonical intermediate representation and per-agency routing.

# Agency-Specific Configuration

The value of the schema-driven approach is that agency differences collapse into rows of a table rather than forks in the code. Each funder’s justification requirements derive from a different governing document, and the parser must carry every dimension below so one intermediate representation can render compliant output for any of the three. The precise page and character figures follow the agency schemas defined in the NIH FOA Schema Mapping, NSF Proposal Guide Taxonomy, and DoD BAA Requirement Extraction taxonomies.

The NIH modular format requires each categorical block — personnel, fringe benefits, travel, equipment, supplies, and other direct costs — to link explicitly to a project aim. NSF proposals instead connect every category to a specific project activity, with heightened scrutiny on graduate and postdoctoral support, participant-support costs, and cost-sharing declarations. DoD Broad Agency Announcements layer on procurement compliance: each justification must assert allowability, allocability, and reasonableness under the Federal Acquisition Regulation (FAR) and its Defense supplement (DFARS), and frequently carries mission-specific cost ceilings. Encoding these as the ALLOWED_CATEGORIES, CATEGORY_LIMITS, and DOD_PRINCIPLES tables above means a policy revision is a data edit, not a code change.

# Error Handling and Edge Cases

Naive justification formatters fail in predictable, agency-specific ways. Each of the following patterns has a concrete resolution that belongs in the validation layer rather than in post-hoc manual review:

• Whitespace-inflated length counts. Text recovered from a PDF form often carries stray newlines and double spaces that push an otherwise-compliant block over the character ceiling. Normalize whitespace before measuring length — the collapse_whitespace validator runs first for exactly this reason.
• Effort expressed as FTE instead of a fraction. A personnel line reading effort_pct=25 (meaning 25%) rather than 0.25 silently means “25× full time.” The le=1.0 bound rejects it at construction; downstream, flag any value above 1.0 for a unit-conversion review instead of truncating it.
• Category name drift. Financial exports label the same cost as “Materials & Supplies,” “Supplies,” or “M&S.” Membership checks against a closed set catch the drift; resolve it with an alias map that canonicalizes labels before the model is constructed, so the mismatch surfaces as a mapping gap rather than a rejection.
• Conditional-rule conflicts across agencies. A line valid for NSF (a participant-support cost) is invalid for NIH, which has no such standalone category. Never validate against a global rule set — always resolve the agency first, then apply that agency’s table, as enforce_agency_rules does by keying every lookup on self.agency.
• Missing cost-principle language for DoD. A technically accurate DoD narrative that never uses the words “allowable,” “allocable,” and “reasonable” is still non-compliant. Treat the phrasing requirement as a hard validator, not a style suggestion.

When a validation error fires, surface the agency, the category, and the failing dimension together — a bare “validation failed” message forces the grant administrator back into the source document to guess which of six rules tripped. The ValueError messages in the implementation above name all three deliberately.

# Integration With the Downstream Pipeline

Validated justification blocks are an intermediate artifact, not the finished proposal. Once each BudgetLineItem passes construction, the normalized records flow into the same taxonomy-resolution and rendering path used across the architecture: ingest raw line items, resolve the agency rule table, validate effort and thresholds, render the narrative blocks, then audit the assembled output against character limits and cross-reference consistency. The audited output fans back out into three agency-shaped justification documents ready for portal upload through Grants.gov, eRA Commons, or a DoD-specific submission system.

Before that assembly step, the same records are commonly handed to the compliance validation rule engines for the checks that live outside the budget narrative itself — page-limit and font enforcement on the rendered document, and automated checklist generation to confirm every required financial attachment is present. The threshold figures those engines apply are calibrated through threshold tuning for compliance, so the character ceilings in this page’s rule table stay aligned with what the enforcement layer expects.

# Testing and Verification

Because the entire format standard is expressed as validators, it is exhaustively testable without any document fixtures — every rule reduces to a construction that should either succeed or raise. The following pytest suite pins the four rule dimensions and the two most common failure modes; run it in continuous integration so a policy edit that breaks an agency’s rule table fails the build rather than a proposal.

import pytest
from pydantic import ValidationError

from budget import Agency, BudgetLineItem, render_justification


def test_valid_nih_personnel_item_constructs() -> None:
    item = BudgetLineItem(
        agency=Agency.NIH,
        category="Personnel",
        amount=85_000.0,
        justification="PI effort dedicated to Aim 1 data collection.",
        effort_pct=0.25,
    )
    assert "Effort: 25.0%" in render_justification([item])


def test_category_outside_agency_set_rejected() -> None:
    # Participant Support is NSF-only; invalid for NIH.
    with pytest.raises(ValidationError, match="not an allowable NIH"):
        BudgetLineItem(
            agency=Agency.NIH,
            category="Participant Support",
            amount=5_000.0,
            justification="Workshop stipends for external trainees.",
        )


def test_over_length_justification_rejected() -> None:
    with pytest.raises(ValidationError, match="over the 250-char limit"):
        BudgetLineItem(
            agency=Agency.NIH,
            category="Supplies",
            amount=2_000.0,
            justification="lab consumables " * 40,
        )


def test_effort_above_one_is_fte_error() -> None:
    with pytest.raises(ValidationError):
        BudgetLineItem(
            agency=Agency.NSF,
            category="Personnel",
            amount=60_000.0,
            justification="Graduate researcher supporting field activities.",
            effort_pct=25,  # FTE-vs-fraction unit error
        )


def test_dod_requires_cost_principle_language() -> None:
    with pytest.raises(ValidationError, match="must assert"):
        BudgetLineItem(
            agency=Agency.DOD,
            category="Equipment",
            amount=40_000.0,
            justification="High-speed oscilloscope for signal characterization.",
        )

For a pre-submission gate outside of CI, wrap construction in a batch validator that collects rather than raises: iterate the source records, attempt to build each BudgetLineItem, and accumulate every ValidationError into a report keyed by line number. That report is the audit trail — a grant administrator sees exactly which lines failed which rule for which agency, and the proposal is blocked from assembly until the report is empty. Coupling that gate with a schema-validated ingestion layer such as schema validation with Pydantic means non-compliant budget data is caught at both the entry and exit of the formatting stage.

# Related Pages

• Standardizing budget justification templates across agencies
• NIH FOA Schema Mapping
• NSF Proposal Guide Taxonomy
• DoD BAA Requirement Extraction
• Compliance validation rule engines

Up: Core Architecture & RFP Taxonomy