Table of Contents

Getting started

Bonsai.Sgen is a code generator tool for the Bonsai visual reactive programming language. It uses JSON Schema to specify record data types, and generates operators to create and manipulate these records. The Data definition article describes how to define record data types for use in a workflow.

Tip

Familiarity with Scripting Extensions is recommended before using this tool.

Installation

Bonsai.Sgen is installed as a local tool of the repository that holds the workflow:

dotnet new tool-manifest
dotnet tool install --local Bonsai.Sgen

Code generation

First, define the JSON Schema for the Person type:

person.json

{
  "title": "Person",
  "type": "object",
  "properties": {
    "age": { "type": "integer" },
    "firstName": { "type": "string" },
    "lastName": { "type": "string" },
    "dateOfBirth": { "type": "string", "format": "date-time" }
  }
}

Then generate the extension code with Bonsai.Sgen:

dotnet bonsai.sgen person.json -o Extensions --serializer json

The generated code follows the naming conventions of C#, so the firstName property in the schema becomes FirstName in the generated Person type. Serialized data keeps the names declared in the schema.

Use the generated operators directly in a workflow:

Person as BonsaiSgen

The generated code depends on the library of the chosen serializer, so the Extensions.csproj file needs the matching package reference:

<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

Newtonsoft.Json also has to be installed in the Bonsai environment from the package manager. The Package references section describes the requirements of the YAML serializer.

Saving and loading

The generated operators create Person objects, convert them to JSON text and back, and can be combined with file operators to save and load records:

(de)serialization

The Basic usage and Advanced usage articles cover schemas with several types, enumerations, lists, nullable and required fields, and unions.

Python models

The bonsai-sgen package provides base classes for Pydantic models that follow the conventions of Bonsai.Sgen. Models written as Python classes export their schemas, or generate the C# types directly, through the bonsai-sgen command. The Pydantic usage article describes how to define and export these models.

Edit this page