Ed-Fi Request for Comment 18: FINANCE API
Product: Ed-Fi Data Standard v3.1
Affects: Ed-Fi ODS / API
Obsoletes: --
Obsoleted By: --
Status: draft

Ed-Fi Alliance
[date]

Synopsis

The Finance API describes an API surface for the exchange of K–12 education organization finance data. The API exchanges charts of accounts, their mappings, and budget and actuals for those accounts.

The API is designed to support many use cases related to exchange of financial data. The API design specifically includes the data models, transactional surface, and other structures necessary to support the federally mandated Every Student Succeeds Act (ESSA) financial transparency reporting.

Contents

Overview

The Finance API specification provides a blueprint for capture, exchange and validation of financial data for K–12 education organizations. The Ed-Fi Alliance Finance domain has been expanded with this API specification to align with state and local accounting practices, and to accommodate new transparency reporting requirements from the federally mandated Every Student Succeeds Act (ESSA).

Background

The current Ed-Fi Data Standard v3.1 Finance domain model provides a link between accounts and education organizations such as State Education Agencies (SEAs), Local Education Agencies (LEAs), Charter Management Organizations (CMOs), and Schools.

The Ed-Fi Finance Work Group has compiled feedback from the Ed-Fi Community to define use cases not supported by the current finance domain model. The proposed Finance API model would allow for mapping data to report an LEA set of accounts to an SEA’s Chart of Accounts. The Finance API includes the ability to guarantee the integrity of full account codes and to tag budgeted and actual amounts to specific required reporting submissions.

Influences & Primary References

The proposed Finance API is aligned with common accounting standards and reporting standards in the K–12 education space. The primary sources include:

The U.S. DoE Institute of Education Sciences publication Financial Accounting for Local and State School Systems. Many definitions of the reporting dimensions in the model derive from the guidance in this publication.
The accounting and reporting guidance published by SEAs, including those represented at the Finance Work Group. A survey of many states was conducted. Of particular note, the WUFAR requirements published by Wisconsin helped shape the particulars of the model, and extended the dimensions as defined by U.S. DoE publications.

The sources above build upon the Generally Accepted Accounting Principles (GAAP) as established by the Governmental Accounting Standards Board (GASB).

Use Cases

The architecture covered by this model of data exchange is intended to serve the following SEA, LEA, and CMO use cases.

SEA Use Cases

The SEA use cases center on data exchange with LEAs related to state and federal finance reporting requirements. These use cases include:

SEA publishes yearly a Chart of Accounts (COA) for LEA reporting purposes and loads the COA into a datastore such as the Ed-Fi ODS / API. The COA can be read by LEA financial system vendors via the Finance API. This eliminates the need for the SEA to publish spreadsheets, and enhances reliability.
LEAs develop their local accounts for the new fiscal year and map their local accounts to the state-level COA. An LEA vendor can use the Finance API to validate new local accounts as they are created.
LEAs develop budgets for a new fiscal year and assign a budget to each local account. The Finance API ensures that invalid account dimension combinations cannot be loaded by enforcing referential integrity of the local-to-SEA COA mappings.
SEAs may update the SEA COA during a given year either via bulk update (XML) into a backing datastore or directly to the Finance API. LEA financial system vendors can read the updated COA information from the SEA via the Finance API.
LEAs may amend their budget throughout the year by updating local codes. These amendments can be posted in their entirety or by updating changed accounts into the Finance API hosted by an SEA.
SEAs may take snapshots of data for loading into a data warehouse or for other date-based LEA reporting.
LEAs may submit actual financial information to an SEA, typically at the end of a fiscal year. These are collected in an LEA financial system throughout the year with validation, reasonability checks, and audits to ensure accuracy of the data. The LEA can provide their reviewed actual information to an SEA via the Finance API.

ESSA (or other) financial reporting by a district can be generated by an SEA. The SEA maps the state-level COA to the various categories used for ESSA reporting, identifying the various dimensions and/or granular COA accounts for each ESSA category. The SEA and LEAs review the data for correctness and approve the data. The SEA publishes the ESSA reports to the public.

CMO Use Cases

The same general use cases are applicable for charter management organizations to receive financial budgets and actuals from the schools in their network.

LEA Use Cases

In regions where there is no Finance API at the state level, an LEA may find the Finance API useful for its own purposes. For example, an LEA can load the SEA-defined COA into a backing datastore, map its own local account codes, and directly generate reports for the SEA. The data exchanged via a Finance API also supports an LEA’s analytics and reporting (e.g., to link financial data with student outcomes and school operations information).

Finance Domain Data Model

The Ed-Fi Unifying Data Model (UDM) harmonizes data definitions across technology published by the Ed-Fi Alliance. This section describes the Ed-Fi UDM structure for the proposed Finance API.

Figure 1. Ed-Fi Finance domain representation

Domain Model Design Discussion

The Chart of Accounts entity forms the backbone for classifying expenditures of all types. Each Account Identifier element is comprised of a compound structure of multiple types of classifications, or dimensions, each with a hierarchical code structure. Example dimensions include:

The Fund from which monies are being expended
The Program that is spending the funds
The Function for which the funds are being spent

While different states use different sets of dimensions, many are standardized in the financial accounting standards published by the NCES. By convention, each dimension of an Account Identifier has a dimension code reflecting a hierarchical organization. For example, a dimension Code of 100 is typically a roll-up of 110, 120, 130, …, and a dimension Code of 120 is a roll-up of 121, 122, 123, …, and so forth.

In the data model, there are entities for each dimension whose values define the set of allowable numbers within the dimension. The Chart of Accounts entity holds the set of valid compound account codes, each linked to their requisite dimensions' code. While this may seem duplicative, each aspect has a specific purpose in that the dimension entities enumerated in the model reflect the national standards. The dimension entities provide a convenient mechanism for query, reporting, and roll-ups along dimensional lines.

Though not part of this specification, API platform hosts could define additional dimensions by repeating this convention.

Because all combinations of dimension code values are not valid, the Chart of Accounts entity delineates the set of valid compound account codes. The mapping (i.e., the association) of Local Accounts (including the Budget and Actual entities) to the Chart of Accounts will allow the API to ensure that only valid Chart of Account entities are referenced. This validation is typically performed by referential integrity checks in an underlying platform's datastore. This approach obviates the need for dozens of business rules to check for valid combinations had a dimension-only model has been used. The Chart of Accounts entity provides the definitive list of account codes used to derive accounting statements and to produce budget versus actual reports.

Example Usage

This section provides a few example usage patterns for the Finance API.

Building the SEA Chart of Accounts for a Fiscal Year

SEA client systems will create a chart of accounts through the /chartOfAccounts endpoint. Each POST to /chartOfAccounts is analogous to creating a row in a typical chart of accounts spreadsheet, and contains similar information: a name and code for the account, plus accounting dimension information such as the type of account (e.g., expense), the fund type (e.g., general fund, capital project fund), the object of the account (e.g., salaries, technical services, utility services), and so forth.

The example listing below illustrates the information sent for a hypothetical instructional fund expense (10 in the fundDimensionReference) related to teacher salaries (100 in the objectDimensionReference) in the regular curriculum (120000 in the functionDimensionReference):

  {
    "id": "58aa05e44e4e4d709d3d491241f30386",
    "accountIdentifier": "10-100-120000",
	"fiscalYear": 2020,
    "educationOrganizationReference": {
      "educationOrganizationId": 1
    },
    "functionDimensionReference": {
      "code": "120000",
      "fiscalYear": 2020
    },
    "fundDimensionReference": {
      "code": "10",
      "fiscalYear": 2020
    },
    "objectDimensionReference": {
      "code": "100",
      "fiscalYear": 2020
    },
    "accountName": "Salaries",
    "accountTypeDescriptor": "uri://state-agency-example.edu#Expense",
    "reportingTags": [
      { "reportingTagDescriptor": "uri://state-agency-example.edu#ESSA" },
      { "reportingTagDescriptor": "uri://state-agency-example.edu#Statewide-Report-Fall-2020" }
    ]
  }

In this example, the SEA has reflected the dimensions in the accountIdentifier (10-100-120000). But, the API doesn't require or enforce that pattern, so SEAs may use any identification scheme that works for their environment.

Mapping Local Accounts to SEA Chart of Account Entries

In most state education systems, the SEA will issue an authoritative chart of accounts. Local education agencies and charter management organizations are required to map their local accounts to the SEA chart of accounts. Local accounts are often finer-grained classifications within the SEA accounts, but may also be additive. In addition, the SEA often has accounts that are not used at the local level. The LEAs and CMOs are typically responsible for mapping local accounts to the authoritative SEA chart of accounts. In the Finance API, this is done through the /localAccounts endpoint.

Building on the example above, the following listing shows a hypothetical school district's mapping to an SEA's account for teacher salaries. In this example, the LEA is mapping its fine-grained account for Language Arts - Literature teacher salaries to the SEA's more general account for regular curriculum teacher salaries.

  {
    "id": "336108d6468f43408388221bde5c639c",
    "accountIdentifier": "LEA16-10-100-122300",
    "chartOfAccountReference": {
      "accountIdentifier": "10-100-120000",
      "educationOrganizationId": 1,
      "fiscalYear": 2020
    },
    "educationOrganizationReference": {
      "educationOrganizationId": 16
    },
    "accountName": "Regular Curriculum - Language Arts - Literature",
    "reportingTags": [
      { "reportingTagDescriptor": "uri://state-agency-example.edu#LEA-Superintendent-Report" }
    ]
  }

Items of note from this example:

Similar to the SEA example, this LEA has reflected its account dimensions in the accountIdentifier, prefixed by an identifier for the district (LEA16-10-100-122300). Same deal as the SEA: the API doesn't require or enforce any particular pattern, it's up to the SEA and its LEAs to define a convention that works best for their environment.
Platforms implementing this API (including the Ed-Fi ODS / API) will require a valid chartOfAccountReference from the LEA. This ensures every LEA account maps to exactly one SEA account.

API Resources and Interactions

The Finance API specification allows client applications to read and write finance data through a secure REST interface.

API implementers and client system developers are expected to follow all guidelines in the Ed-Fi API Design and Implementation Guidelines. These include requirements relating to errors, authentication, security, and other aspects of API usage and implementation. Any MUST requirements from that document are considered necessary to conform to this specification. If there are differences between the requirements included in this document and the Guidelines, the information provided in this document has precedence.

An OpenAPI definition of the proposed Finance API interface is provided below. Consumer implementations wishing to conform to this standard are expected to implement paths, resources, and definitions as described in that OpenAPI specification. In addition, providers must accurately follow other related semantics defined in the Ed-Fi UDM (for example, for references to entities outside this domain).

The following is a summary of paths in the Finance API and brief descriptions:

/localAccounts

The set of account codes defined by an education organization for a fiscal year. Provides a formal record of the debits and credits relating to the specific account.

/localBudgets

The set of local education agency or charter management organization budget amounts.

/localActuals

The set of local education agency or charter management organization actual financial result amounts, typically based on the accrual basis of accounting.

/chartOfAccounts

A valid combination of account dimensions under which financials are reported. This financial entity represents a funding category combined with its purpose and type of transaction. It provides a formal way to categorize the debits and credits relating to a specific account.

/fundDimensions

The NCES fund accounting dimension. A fund is defined by the NCES as "a fiscal and accounting entity with a self-balancing set of accounts recording cash and other financial resources, together with all related liabilities and residual equities or balances, and changes therein, which are segregated for the purpose of carrying on specific activities or attaining certain objectives in accordance with special regulations, restrictions, or limitations." Most SEAs use a similar definition.

/programDimensions

The NCES program accounting dimension. A program is defined by the NCES as "a plan of activities and procedures designed to accomplish a predetermined objective or set of objectives." These are often categorized into broad program areas such as regular education, special education, vocational education, other PK-12 instructional, nonpublic school, adult and continuing education, community and junior college education, community services, and co-curricular or extracurricular activities. Most SEAs use a similar definition.

/functionDimensions

The NCES function accounting dimension representing an expenditure. Per the NCES definition, the function describes the activity for which a service or material object is acquired. The functions of a school district are generally classified into five broad areas, including instruction, support services, operation of non-instructional services, facilities acquisition and construction, and debt service. Functions are typically further classified into sub-functions. Most SEAs use a similar definition.

/objectDimensions

The NCES object accounting dimension representing an expenditure. Per the NCES definition, this classification is used to describe the service or commodity obtained as the result of a specific expenditure, such as salaries, benefits, tuition reimbursement, and so forth. Most SEAs use a similar definition.

/projectDimensions

The NCES project accounting dimension. Per the NCES, the project dimension reporting code permits school districts to accumulate expenditures to meet a variety of specialized reporting requirements at the local, state, and federal levels. In the NCES reporting scheme, this is typically a three-digit code with the format 00X. The first two digits identify the particular funding source, authority, or expenditure purpose for which a special record or report is required. The third digit is available to identify particular projects and the fiscal year of the appropriation within that funding source. SEAs will typically provide guidance to LEAs on how to structure this code.

/operationalUnitDimensions

The NCES operational unit accounting dimension. Per the NCES, this dimension is used to segregate costs by school and operational unit such as physical location, department, or other method. SEAs may provide guidance to LEAS on how to structure this code, or it may be at the discretion of the local organizations.

/sourceDimensions

The NCES source dimension. Per the NCES, the source dimension is used to classify revenue, receivables, and other sources of income based on their origins such as taxes, tuition, fees, and so forth. Revenue increases both the assets and the equity of a local education agency or charter management organization as a whole. Most SEAs use a similar definition.

/balanceSheetDimensions

The NCES balance sheet accounting dimension. The NCES definition states that the balance sheet accounts and statement of net position accounts are used to track financial transactions for each fund. Such financial statements only report assets, deferred outflows of resources, liabilities, deferred inflows of resources, and equity accounts. The statements are considered "snapshots" of how these accounts stand as of a certain point in time.

Technical definitions of these paths can be found in the Finance API OpenAPI specification.

Key RFC Questions

Initial review of the Finance API specification has raised the following questions and comments.

RFC 18 Q1. Would it be useful to add a Chart of Account Document data structure? The proposed RFC 18 specification doesn't support the notion of a Chart of Accounts Document to enclose all the individual account records for a given fiscal year and education organization. This means there's not a way for the API to indicate the status of a Chart of Accounts (e.g., as obsolete or as a draft). This also means there's no metadata available about the Chart of Accounts rows for a given fiscal year (e.g., when the set was last updated). The same issues apply to Local Accounts.
RFC 18 Q2. Would it be useful to include an endpoint that more closely replicates the current Chart of Accounts publication structure? A primary use case of the RFC 18 API is to replace the current SEA process of publishing and distributing Chart of Accounts documents to LEAs and CMOs. These documents are usually in spreadsheet or tabular form, and are ordered by account code or other meaningful method. The proposed RFC 18 contains the same data as the current publication. But, there's not a defined endpoint that can provide the data in the same fashion. To present the Chart of Accounts in a user interface, a client system would, for example, need to get all records from the /chartOfAccounts endpoint for a given fiscal year, page through all the results, then sort and format on the client side.
RFC 18 Q3. Does the Finance API need to provide details about Chart of Account changes within a given year, or does its responsibility end with simply publishing an authoritative, current Chart of Accounts? An identified use case is to support SEA updates to the Chart of Accounts within a given year. The proposed RFC 18 can provide a current account, but provides no data about exactly what changed, no history of changes, no means to indicate recent additions, or similar.

The questions posed here are entirely around whether the Finance API specified in this RFC 18 has a role in supporting these processes or communicating information between different systems related to these processes. The concerns raised in this section may be entirely addressed by existing client system functionality and/or business processes. If that's the case, then no action is indicated.

Feedback

We welcome responses to issues raised in the Key Questions above, and comments on any part of the model. The primary mechanism for feedback is via the Ed-Fi Alliance general project in the Ed-Fi Tracker.

Licensees can submit RFC 18 feedback by clicking this link (login required).
Licensees and the general public can view existing feedback here: http://tracker.ed-fi.org/projects/EDFI/ (login not required). When entering a feedback ticket, please reference the RFC number, change, or specific fix on which you are commenting, if applicable.

Browser not supported