Fabulous.AST.Build 2.0.0-pre04

Fabulous.AST.Build

Automatically generate F# types from JSON files at build time.

Overview

Fabulous.AST.Build is an MSBuild task that:

• Watches JSON files in your project
• Automatically generates F# record types during build
• Supports incremental builds (only regenerates when JSON changes)
• Integrates seamlessly with MSBuild and .NET CLI

Use cases:

• Generate F# types from API response samples
• Keep type definitions in sync with JSON schemas
• Automate type generation in CI/CD pipelines

💡 Tip: For programmatic control over generation, use Fabulous.AST.Json directly.

Installation

dotnet add package Fabulous.AST.Build

Requirements: .NET 8.0 or later

Tutorial

Step 1: Create a JSON Schema File

Create a folder for your JSON schemas and add a sample file.

schemas/user.json:

{
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com",
    "isActive": true
}

Step 2: Configure Your Project

Add the FabulousAstJson item to your .fsproj:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Fabulous.AST.Build" Version="1.0.0" />
  </ItemGroup>

  
  <ItemGroup>
    <FabulousAstJson Include="schemas/user.json" />
  </ItemGroup>

  
  <ItemGroup>
    <Compile Include="Generated/user.Generated.fs" />
  </ItemGroup>
</Project>

Step 3: Build Your Project

dotnet build

This generates Generated/user.Generated.fs:

// Auto-generated from schemas/user.json
// Hash: abc123...
// Do not edit manually - changes will be overwritten

type User = {
    id: int
    name: string
    email: string
    isActive: bool
}

Step 4: Custom Root Type Name

By default, the root type name is derived from the filename. Override it with RootName:

<ItemGroup>
  <FabulousAstJson Include="schemas/api-response.json" RootName="ApiResponse" />
</ItemGroup>

Step 5: Add a Module

Wrap generated types in a file-level module using ModuleName:

<ItemGroup>
  <FabulousAstJson Include="schemas/user.json"
                   RootName="User"
                   ModuleName="MyApp.Models" />
</ItemGroup>

Output:

module MyApp.Models

type User = {
    id: int
    name: string
    email: string
    isActive: bool
}

Step 6: Multiple JSON Files

Process multiple schemas with different configurations:

<ItemGroup>
  <FabulousAstJson Include="schemas/user.json"
                   RootName="User"
                   ModuleName="MyApp.Models.User" />
  <FabulousAstJson Include="schemas/product.json"
                   RootName="Product"
                   ModuleName="MyApp.Models.Product" />
  <FabulousAstJson Include="schemas/order.json"
                   RootName="CustomerOrder"
                   ModuleName="MyApp.Orders" />
</ItemGroup>

<ItemGroup>
  <Compile Include="Generated/user.Generated.fs" />
  <Compile Include="Generated/product.Generated.fs" />
  <Compile Include="Generated/order.Generated.fs" />
</ItemGroup>

Note: Each file must have a unique module name since file-level modules cannot share the same fully-qualified name.

Step 7: Custom Output Directory

Change where generated files are placed:

<PropertyGroup>
  <FabulousAstJsonOutputDir>Types/</FabulousAstJsonOutputDir>
</PropertyGroup>

Step 8: Glob Patterns

Process all JSON files in a directory:

<ItemGroup>
  <FabulousAstJson Include="schemas/**/*.json" />
</ItemGroup>

Step 9: Custom Output Filename

Override the default {filename}.Generated.fs pattern:

<ItemGroup>
  <FabulousAstJson Include="schemas/user.json"
                   OutputFileName="UserTypes.fs" />
</ItemGroup>

Configuration Reference

Project Properties

Item Metadata

Type Inference

The generator infers F# types from JSON values:

Arrays Become List Types

Input (users.json):

[
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
]

Output:

type UsersItem = { id: int; name: string }
type Users = UsersItem list

Nested Objects Become Nested Types

Input (company.json):

{
    "name": "Acme Corp",
    "address": {
        "street": "123 Main St",
        "city": "London"
    }
}

Output:

type Address = { street: string; city: string }
type Company = { name: string; address: Address }

Optional Fields

Fields missing or null in some array objects become option types:

Input:

[
    { "id": 1, "name": "Alice", "nickname": "Ali" },
    { "id": 2, "name": "Bob" }
]

Output:

type RootItem = { id: int; name: string; nickname: string option }
type Root = RootItem list

Special Field Name Handling

Leading Digits

JSON fields starting with digits are prefixed with _:

{ "2faEnabled": true }

Generates:

type Root = { _2faEnabled: bool }

Reserved Keywords

F# keywords are escaped with double backticks:

{ "type": "admin", "class": "premium" }

Generates:

type Root = { ``type``: string; ``class``: string }

Incremental Builds

The task uses content hashing for smart rebuilds:

• Files are only regenerated when JSON content changes
• Configuration changes (RootName, ModuleName, etc.) trigger regeneration
• Generated files include a hash comment for verification

IDE Integration

Generated files are created during build. Your IDE may not immediately see newly generated files.

Recommended: Explicit File Listing

For the best IDE experience, explicitly list generated files:

<Compile Include="Generated/user.Generated.fs" />

The IDE knows about the file path upfront and will recognize it once generated.

Using Glob Patterns

With glob patterns like <Compile Include="Generated/*.fs" />, you may need to reload the project after the first build for the IDE to pick up new files.

Tips

• Keep generated files in source control - Avoids first-build issues
• Don't delete generated files - Incremental build only regenerates when JSON changes

Troubleshooting

IDE Not Seeing Generated Files

1. Reload/refresh the project
2. Switch from glob patterns to explicit file listing
3. Ensure the file exists in Generated/

Build Fails After Clean

Expected when using glob patterns. Run dotnet build again.

Generated File Not Updating

dotnet clean && dotnet build

Disable Generation

<EnableFabulousAstJsonGeneration>false</EnableFabulousAstJsonGeneration>

Or via command line:

dotnet build -p:EnableFabulousAstJsonGeneration=false

Related Packages

• Fabulous.AST - Core DSL for generating F# code
• Fabulous.AST.Json - Programmatic API for JSON-to-F# generation