Fact Graph Documentation

The Fact Graph is a standalone tax logic engine designed to calculate taxes based on user-provided information. It is intended to be used as a consumable library for both JVM and JavaScript-based applications, allowing developers to implement tax law changes without hard-coding logic into their specific applications.

It consists of two primary components:

1. Fact Dictionary: A set of tax facts (e.g., eligibility requirements for a credit) represented as XML documents using Fact XML (FXML).
2. The Graph: An instantiation of a specific user's tax scenario, created by applying the Fact Dictionary logic to the taxpayer's personal information.

The Fact Graph supports collections where each item shares the same possible facts. In the dictionary, collection facts are identified by a wildcard * in their path (e.g., /jobs/*/income).

During evaluation, the * is replaced with a # followed by the unique UUID of the specific item. For example, a job with UUID a3006af1-a040-4235-9d31-68c5830c55fd will have its path resolved to /jobs/#a3006af1-a040-4235-9d31-68c5830c55fd/income.

<Fact path="/jobs/*/yearToDateIncome">
  <Writable>
    <Dollar/>
  </Writable>
</Fact>

Understanding the following terminology is essential for working with the Fact Graph:

• Fact Graph (lowercase): A specific instantiation of a user's tax scenario.
• Fact Dictionary: A set of facts about tax logic (e.g., 'to be eligible for X credit you must be Y years of age').
• Fact XML (FXML): The markup language used to define Fact Dictionaries.
• TS25: Refers to Tax Season 2025.

You can include arbitrary, user-defined metadata in your Fact Dictionary using the <Meta> tag. This metadata is intended to be serialized along with the fact graph JSON.

Example XML:

<Meta>
  <name>My Facts</name>
  <version>1.3.0</version>
</Meta>

Resulting JSON structure:

{
  "facts": [],
  "meta": {
    "name": "My Facts",
    "version": "1.3.0"
  }
}

The Fact Graph is designed to exist in-memory during a session. To persist the state, use the serialization method provided by the graph instance, which returns a JSON representation. The consumer is responsible for deciding when and how to save this JSON (e.g., to a database or file).

Validation Logic: Validation is decoupled from the save() process. Because users may enter data incrementally, the graph may exist in an invalid state during the process. The library is moving toward exposing validation through its own dedicated interface so that users can check for errors without being forced to trigger a save operation.

A Fact Dictionary is defined using an XML structure. The root container is a <FactDictionaryModule>, which must contain a single <Facts> element. The <Facts> element acts as a container for multiple <Fact> definitions.

To define a fact, use the <Fact> element with a path attribute. Every <Fact> must have exactly one of either <Writable> or <Derived> as a child to determine how its value is obtained.

<FactDictionaryModule>
  <Facts>
    <Fact path="/totalTax">
      <Derived>
        <Add>
          <Dependency path="/tentativeTaxNetNonRefundableCredits"/>
          <Dependency path="/totalOtherTaxes"/>
        </Add>
      </Derived>
    </Fact>
  </Facts>
</FactDictionaryModule>

To avoid using only basic primitives, you can define custom types within a <Types> module in your FactDictionary. This allows you to create domain-specific types (like IpPin or Address) based on the core Fact Graph primitives.

Supported Primitives:

• Boolean
• Integer
• Double (used for precision instead of float)
• String
• Object (key-value pairs of other types)

Example Type Declaration:

<Type>
  <Name>IpPin</Name>
  <BaseType>String</BaseType>
  <Limit type="Match">
     <![CDATA[^([0-9]{6})$]]>
  </Limit>
</Type>

To comply with project requirements, all commits must use your GitHub-provided noreply email address (e.g., {ID}+{USERNAME}@users.noreply.github.com).

1. Enable private email: In GitHub email settings, enable Keep my email address private.
2. Set local git config:
   • To use this email for all projects: git config --global user.email "YOUR_NO_REPLY_EMAIL".
   • To use this email only for Fact Graph: Navigate to the project directory and run git config user.email "YOUR_NO_REPLY_EMAIL".
3. Verify: Run git config user.email to confirm.

# Set for all projects
git config --global user.email "YOUR_ID+YOUR_USERNAME@users.noreply.github.com"

# Set for this repository only
cd ./path/to/fact-graph/
git config user.email "YOUR_ID+YOUR_USERNAME@users.noreply.github.com"

# Verify
git config user.email

If you are migrating from older versions or need to understand the current architecture, consult the following documentation:

• Architectural Decisions: See the Fact Graph 3.1 ADR for details on the graph structure and changes implemented since early 2025.
• Migration Guide: See from-3.0-to-3.1.md for a summary of changes between older versions and the current v3.1 release.