Extension Json Definitions

JSON behavior definitions and structural events

Stateflows.Extensions.Json supports declarative State Machine and Activity definitions, as well as JSON-based definitions for structural events and requests. These definitions are parsed into the ordinary Stateflows registration APIs; they do not create a separate runtime or bypass the core behavior rules.

Register definitions

Install Stateflows.Extensions.Json, then parse a JSON document and register it with the corresponding builder:

using Stateflows.Common.Json;
using Stateflows.StateMachines.Json;

var options = new JsonOptions()
    .AddType<PaymentReceived>("events.paymentReceived");

services.AddStateflows(stateflows => stateflows.AddStateMachines(machines =>
    machines.AddStateMachineJson(File.ReadAllText("order.json"), options)));

Use AddActivityJson from Stateflows.Activities.Json to register an Activity. A JsonOptions registry can provide explicit aliases for CLR types referenced by a document; definitions cannot name assemblies, load arbitrary CLR types, or introduce aliases themselves. Structural events should be registered before behaviors that refer to their event names.

The package also provides JsonEventDefinition.Parse(...).Register(...) for structural events and requests. IEventFactory.CreateFromJson decodes an incoming JSON payload against the registered structural event definition; ordinary Stateflows validation still determines whether the event is valid.

Validation and schemas

The parsers reject unknown properties, duplicate JSON properties, invalid shapes, unsupported types, and unresolved or incompatible aliases. Behavior definition binding validates referenced handlers and the expanded behavior graph before registration. JSON parser, schema, binding, data-binding, and expansion diagnostics are reported through the package's definition exception/report types; failed registration does not replace an existing valid definition.

Draft 2020-12 schemas are included in the package:

• State Machine schema
• Activity schema
• Structural event schema

The schemas help authoring tools, while parsing and registration perform authoritative validation. The package README documents definition shapes, aliases, validation options, structural event payload conversion, and diagnostics in detail.