6.3. 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.

Activity interleaving and parallel limits

Structural Activity nodes support "options": ["implicitJoin", "implicitFork", "interleave"]. This maps to the existing fluent builders' parameterless .Interleave() and NodeOptions.Interleave; an options array replaces defaults. Actions reject this flag, and combining it with "reentrant" is a registration error. Existing action-only reentrancy is unchanged.

Parallel nodes additionally accept "maxConcurrency": 4, matching the optional int maxConcurrency = -1 argument immediately after chunkSize in AddParallelActivity. -1 is unlimited, positive values bound active partitions per invocation, and 0 or values below -1 are invalid. Queued chunks wait asynchronously for slots. Iterative nodes remain sequential and reject this property.

Each interleaved arrival is chunked independently and supplies only its own non-selection/common input; final partial chunks are included immediately. Parallel/iterative scopes finalize when work drains, discard stranded tokens and aggregate ordinary boundary output. Arrivals after finalization begins wait for finalization and output routing, then start a fresh invocation. Structured scopes feed existing input boundaries without repeating initialization or Initial control, with ordinary event waits unchanged. Interleaving does not publish aggregate boundary output early. See the parallel, iterative and structured pages for complete lifecycle and checkpoint details.

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.