feat(Core): Add the SubscriptionIteratorDefinition model

feat(Core): Add a new `Read` property to the `ListenerDefinition` model
feat(Builders): Add a `ISubscriptionIteratorDefinitionBuilder` and default implementation
feat(Builders): Add a new `IInputDataModelBuilder` service and default implementation
feat(Builders): Add a new `IOutputDataModelBuilder` service and default implementation
feat(Builders): Add a new `ISchemaDefinitionBuilder` service and default implementation
feat(Builders): Updated the `ITaskDefinitionBuilder` service and default implementation by adding methods to configure the task's input, output and export clauses

Signed-off-by: Charles d'Avernas <[email protected]>

Author: cdavernas

src/ServerlessWorkflow.Sdk.Builders/InputDataModelDefinitionBuilder.cs

@@ -0,0 +1,49 @@
+// Copyright © 2024-Present The Serverless Workflow Specification Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"),
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace ServerlessWorkflow.Sdk.Builders;
+
+/// <summary>
+/// Represents the default implementation of the <see cref="IInputDataModelDefinitionBuilder"/> interface
+/// </summary>
+public class InputDataModelDefinitionBuilder
+    : IInputDataModelDefinitionBuilder
+{
+
+    /// <summary>
+    /// Gets the <see cref="InputDataModelDefinition"/> to configure
+    /// </summary>
+    protected InputDataModelDefinition Input { get; } = new();
+
+    /// <inheritdoc/>
+    public virtual IInputDataModelDefinitionBuilder From(object expression)
+    {
+        ArgumentNullException.ThrowIfNull(expression);
+        this.Input.From = expression;
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual IInputDataModelDefinitionBuilder WithSchema(Action<ISchemaDefinitionBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new SchemaDefinitionBuilder();
+        setup(builder);
+        this.Input.Schema = builder.Build();
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual InputDataModelDefinition Build() => this.Input;
+
+}

src/ServerlessWorkflow.Sdk.Builders/Interfaces/IInputDataModelDefinitionBuilder.cs

@@ -0,0 +1,42 @@
+// Copyright © 2024-Present The Serverless Workflow Specification Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"),
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace ServerlessWorkflow.Sdk.Builders;
+
+/// <summary>
+/// Defines the fundamentals of a service used to build <see cref="InputDataModelDefinition"/>s
+/// </summary>
+public interface IInputDataModelDefinitionBuilder
+{
+
+    /// <summary>
+    /// Configures the input data schema
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the input data schema</param>
+    /// <returns>The configured <see cref="IInputDataModelDefinitionBuilder"/></returns>
+    IInputDataModelDefinitionBuilder WithSchema(Action<ISchemaDefinitionBuilder> setup);
+
+    /// <summary>
+    /// Configures the runtime expression used to filter the input data
+    /// </summary>
+    /// <param name="expression">The runtime expression used to filter the input data</param>
+    /// <returns>The configured <see cref="IInputDataModelDefinitionBuilder"/></returns>
+    IInputDataModelDefinitionBuilder From(object expression);
+
+    /// <summary>
+    /// Builds the configured <see cref="InputDataModelDefinition"/>
+    /// </summary>
+    /// <returns>A new <see cref="InputDataModelDefinition"/></returns>
+    InputDataModelDefinition Build();
+
+}

src/ServerlessWorkflow.Sdk.Builders/Interfaces/IListenTaskDefinitionBuilder.cs

@@ -25,6 +25,13 @@ public interface IListenTaskDefinitionBuilder
     /// </summary>
     /// <param name="setup">An <see cref="Action{T}"/> used to setup the task's listener target</param>
     /// <returns>The configured <see cref="IListenTaskDefinitionBuilder"/></returns>
-    IListenTaskDefinitionBuilder To(Action<IListenerTargetDefinitionBuilder> setup);
+    IListenTaskDefinitionBuilder To(Action<IListenerDefinitionBuilder> setup);
+
+    /// <summary>
+    /// Configures the iterator used to process each consumed event
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the <see cref="SubscriptionIteratorDefinition"/> to use</param>
+    /// <returns>The configured <see cref="IListenTaskDefinitionBuilder"/></returns>
+    IListenTaskDefinitionBuilder Foreach(Action<ISubscriptionIteratorDefinitionBuilder> setup);
 
 }

src/ServerlessWorkflow.Sdk.Builders/Interfaces/IListenerDefinitionBuilder.cs

@@ -17,19 +17,20 @@ namespace ServerlessWorkflow.Sdk.Builders;
 /// Defines the fundamentals of a service used to build <see cref="ListenerDefinition"/>s
 /// </summary>
 public interface IListenerDefinitionBuilder
+    : IListenerTargetDefinitionBuilder
 {
 
     /// <summary>
-    /// Configures the 
+    /// Configures how to read consumed events
     /// </summary>
-    /// <param name="setup"></param>
-    /// <returns></returns>
-    IListenerDefinitionBuilder To(Action<IListenerTargetDefinitionBuilder> setup);
+    /// <param name="readMode">Specifies how consumed events should be read. See <see cref="EventReadMode"/>s</param>
+    /// <returns>The configured <see cref="IListenerDefinitionBuilder"/></returns>
+    IListenerDefinitionBuilder Read(string readMode);
 
     /// <summary>
     /// Builds the configured <see cref="ListenerDefinition"/>
     /// </summary>
     /// <returns>A new <see cref="ListenerDefinition"/></returns>
-    ListenerDefinition Build();
+    new ListenerDefinition Build();
 
 }

src/ServerlessWorkflow.Sdk.Builders/Interfaces/IOutputDataModelDefinitionBuilder.cs

@@ -0,0 +1,42 @@
+// Copyright © 2024-Present The Serverless Workflow Specification Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"),
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace ServerlessWorkflow.Sdk.Builders;
+
+/// <summary>
+/// Defines the fundamentals of a service used to build <see cref="OutputDataModelDefinition"/>s
+/// </summary>
+public interface IOutputDataModelDefinitionBuilder
+{
+
+    /// <summary>
+    /// Configures the output data schema
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the output data schema</param>
+    /// <returns>The configured <see cref="IOutputDataModelDefinitionBuilder"/></returns>
+    IOutputDataModelDefinitionBuilder WithSchema(Action<ISchemaDefinitionBuilder> setup);
+
+    /// <summary>
+    /// Configures the runtime expression used to filter the data to output
+    /// </summary>
+    /// <param name="expression">The runtime expression used to filter the data to output</param>
+    /// <returns>The configured <see cref="IOutputDataModelDefinitionBuilder"/></returns>
+    IOutputDataModelDefinitionBuilder As(object expression);
+
+    /// <summary>
+    /// Builds the configured <see cref="OutputDataModelDefinition"/>
+    /// </summary>
+    /// <returns>A new <see cref="OutputDataModelDefinition"/></returns>
+    OutputDataModelDefinition Build();
+
+}

src/ServerlessWorkflow.Sdk.Builders/Interfaces/ISchemaDefinitionBuilder.cs

@@ -0,0 +1,49 @@
+// Copyright © 2024-Present The Serverless Workflow Specification Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"),
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace ServerlessWorkflow.Sdk.Builders;
+
+/// <summary>
+/// Defines the fundamentals of a service used to build <see cref="SchemaDefinition"/>s
+/// </summary>
+public interface ISchemaDefinitionBuilder
+{
+
+    /// <summary>
+    /// Sets the schema format
+    /// </summary>
+    /// <param name="format">The schema format</param>
+    /// <returns>The configured <see cref="ISchemaDefinitionBuilder"/></returns>
+    ISchemaDefinitionBuilder WithFormat(string format);
+
+    /// <summary>
+    /// Sets the schema's <see cref="ExternalResourceDefinition"/>
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the schema's <see cref="ExternalResourceDefinition"/></param>
+    /// <returns>The configured <see cref="ISchemaDefinitionBuilder"/></returns>
+    ISchemaDefinitionBuilder WithResource(Action<IExternalResourceDefinitionBuilder> setup);
+
+    /// <summary>
+    /// Sets the schema document
+    /// </summary>
+    /// <param name="document">The schema document</param>
+    /// <returns>The configured <see cref="ISchemaDefinitionBuilder"/></returns>
+    ISchemaDefinitionBuilder WithDocument(object document);
+
+    /// <summary>
+    /// Builds the configured <see cref="SchemaDefinition"/>
+    /// </summary>
+    /// <returns>A new <see cref="SchemaDefinition"/></returns>
+    SchemaDefinition Build();
+
+}

src/ServerlessWorkflow.Sdk.Builders/Interfaces/ISubscriptionIteratorDefinitionBuilder.cs

@@ -0,0 +1,63 @@
+// Copyright © 2024-Present The Serverless Workflow Specification Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"),
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace ServerlessWorkflow.Sdk.Builders;
+
+/// <summary>
+/// Defines the fundamentals of a service used to build <see cref="SubscriptionIteratorDefinition"/>s
+/// </summary>
+public interface ISubscriptionIteratorDefinitionBuilder
+{
+
+    /// <summary>
+    /// Sets the name of the variable used to store the item being enumerated
+    /// </summary>
+    /// <param name="item">The name of the variable used to store the item being enumerated</param>
+    /// <returns>The configured <see cref="ISubscriptionIteratorDefinitionBuilder"/></returns>
+    ISubscriptionIteratorDefinitionBuilder Item(string item);
+
+    /// <summary>
+    /// Sets the name of the variable used to store the index of the item being enumerated
+    /// </summary>
+    /// <param name="at">The name of the variable used to store the index of the item being enumerated</param>
+    /// <returns>The configured <see cref="ISubscriptionIteratorDefinitionBuilder"/></returns>
+    ISubscriptionIteratorDefinitionBuilder At(string at);
+
+    /// <summary>
+    /// Sets the tasks to execute for each event or message consumed
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the tasks to execute for each event or message consumed</param>
+    /// <returns>The configured <see cref="ISubscriptionIteratorDefinitionBuilder"/></returns>
+    ISubscriptionIteratorDefinitionBuilder Do(Action<ITaskDefinitionMapBuilder> setup);
+
+    /// <summary>
+    /// Configures the output data of each item
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the output data</param>
+    /// <returns>The configured <see cref="ISubscriptionIteratorDefinitionBuilder"/></returns>
+    ISubscriptionIteratorDefinitionBuilder Output(Action<IOutputDataModelDefinitionBuilder> setup);
+
+    /// <summary>
+    /// Configures the data exported by each item
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the exported data</param>
+    /// <returns>The configured <see cref="ISubscriptionIteratorDefinitionBuilder"/></returns>
+    ISubscriptionIteratorDefinitionBuilder Export(Action<IOutputDataModelDefinitionBuilder> setup);
+
+    /// <summary>
+    /// Builds the configured <see cref="SubscriptionIteratorDefinition"/>
+    /// </summary>
+    /// <returns>A new <see cref="SubscriptionIteratorDefinition"/></returns>
+    SubscriptionIteratorDefinition Build();
+
+}

src/ServerlessWorkflow.Sdk.Builders/Interfaces/ITaskDefinitionBuilder.cs

@@ -44,26 +44,47 @@ public interface ITaskDefinitionBuilder<TBuilder>
     TBuilder If(string condition);
 
     /// <summary>
-    /// Sets the workflow's timeout
+    /// Sets the task's timeout
     /// </summary>
-    /// <param name="name">The name of the workflow's timeout</param>
+    /// <param name="name">The name of the task's timeout</param>
     /// <returns>The configured <see cref="ITaskDefinitionBuilder{TBuilder}"/></returns>
     TBuilder WithTimeout(string name);
 
     /// <summary>
-    /// Sets the workflow's timeout
+    /// Sets the task's timeout
     /// </summary>
-    /// <param name="timeout">The workflow's timeout</param>
+    /// <param name="timeout">The task's timeout</param>
     /// <returns>The configured <see cref="ITaskDefinitionBuilder{TBuilder}"/></returns>
     TBuilder WithTimeout(TimeoutDefinition timeout);
 
     /// <summary>
-    /// Sets the workflow's timeout
+    /// Sets the task's timeout
     /// </summary>
-    /// <param name="setup">An <see cref="Action{T}"/> used to setup the workflow's timeout</param>
+    /// <param name="setup">An <see cref="Action{T}"/> used to setup the task's timeout</param>
     /// <returns>The configured <see cref="ITaskDefinitionBuilder{TBuilder}"/></returns>
     TBuilder WithTimeout(Action<ITimeoutDefinitionBuilder> setup);
 
+    /// <summary>
+    /// Sets the task's input data
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the task's input</param>
+    /// <returns>The configured <see cref="ITaskDefinitionBuilder{TBuilder}"/></returns>
+    TBuilder WithInput(Action<IInputDataModelDefinitionBuilder> setup);
+
+    /// <summary>
+    /// Sets the task's output data
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the task's output</param>
+    /// <returns>The configured <see cref="ITaskDefinitionBuilder{TBuilder}"/></returns>
+    TBuilder WithOutput(Action<IOutputDataModelDefinitionBuilder> setup);
+
+    /// <summary>
+    /// Sets the data exported by the task
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the data exported by the task</param>
+    /// <returns>The configured <see cref="ITaskDefinitionBuilder{TBuilder}"/></returns>
+    TBuilder WithExport(Action<IOutputDataModelDefinitionBuilder> setup);
+
     /// <summary>
     /// Configures the task to build to then execute the specified flow directive
     /// </summary>

src/ServerlessWorkflow.Sdk.Builders/Interfaces/IWorkflowDefinitionBuilder.cs

@@ -98,6 +98,20 @@ public interface IWorkflowDefinitionBuilder
     /// <returns>The configured <see cref="IWorkflowDefinitionBuilder"/></returns>
     IWorkflowDefinitionBuilder WithTimeout(Action<ITimeoutDefinitionBuilder> setup);
 
+    /// <summary>
+    /// Sets the workflow's input data
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the workflow's input</param>
+    /// <returns>The configured <see cref="IWorkflowDefinitionBuilder"/></returns>
+    IWorkflowDefinitionBuilder WithInput(Action<IInputDataModelDefinitionBuilder> setup);
+
+    /// <summary>
+    /// Sets the workflow's output data
+    /// </summary>
+    /// <param name="setup">An <see cref="Action{T}"/> used to configure the workflow's output</param>
+    /// <returns>The configured <see cref="IWorkflowDefinitionBuilder"/></returns>
+    IWorkflowDefinitionBuilder WithOutput(Action<IOutputDataModelDefinitionBuilder> setup);
+
     /// <summary>
     /// Uses the specified authentication policy
     /// </summary>

src/ServerlessWorkflow.Sdk.Builders/ListenTaskDefinitionBuilder.cs

@@ -21,31 +21,31 @@ public class ListenTaskDefinitionBuilder
 {
 
     /// <summary>
-    /// Gets/sets the task's listener configuration
+    /// Gets/sets the <see cref="ListenTaskDefinition"/> to configure
     /// </summary>
-    protected ListenerDefinition? Listener { get; set; }
+    protected ListenTaskDefinition Task { get; } = new() { Listen = null! };
 
     /// <inheritdoc/>
-    public virtual IListenTaskDefinitionBuilder To(Action<IListenerTargetDefinitionBuilder> setup)
+    public virtual IListenTaskDefinitionBuilder To(Action<IListenerDefinitionBuilder> setup)
     {
-        var builder = new ListenerTargetDefinitionBuilder();
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new ListenerDefinitionBuilder();
         setup(builder);
-        var target = builder.Build();
-        this.Listener = new()
-        {
-            To = target
-        };
+        this.Task.Listen = builder.Build();
         return this;
     }
 
     /// <inheritdoc/>
-    public override ListenTaskDefinition Build()
+    public virtual IListenTaskDefinitionBuilder Foreach(Action<ISubscriptionIteratorDefinitionBuilder> setup)
     {
-        if (this.Listener == null) throw new NullReferenceException("The listener must be set");
-        return this.Configure(new()
-        {
-            Listen = this.Listener
-        });
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new SubscriptionIteratorDefinitionBuilder();
+        setup(builder);
+        this.Task.Foreach = builder.Build();    
+        return this;
     }
 
+    /// <inheritdoc/>
+    public override ListenTaskDefinition Build() => this.Configure(this.Task);
+
 }

src/ServerlessWorkflow.Sdk.Builders/ListenerDefinitionBuilder.cs

@@ -16,33 +16,31 @@ namespace ServerlessWorkflow.Sdk.Builders;
 /// <summary>
 /// Represents the default implementation of the <see cref="IListenerDefinitionBuilder"/> interface
 /// </summary>
-/// <param name="target">The listener's target</param>
-public class ListenerDefinitionBuilder(EventConsumptionStrategyDefinition? target = null)
-    : IListenerDefinitionBuilder
+/// <param name="to">The listener's target</param>
+public class ListenerDefinitionBuilder(EventConsumptionStrategyDefinition? to = null)
+    : ListenerTargetDefinitionBuilder, IListenerDefinitionBuilder
 {
 
     /// <summary>
-    /// Gets/sets the listener's target
+    /// Gets/sets the <see cref="ListenerDefinition"/> to configure
     /// </summary>
-    protected EventConsumptionStrategyDefinition? Target { get; set; } = target;
+    protected ListenerDefinition Listener { get; } = new() { To = to! };
 
     /// <inheritdoc/>
-    public virtual IListenerDefinitionBuilder To(Action<IListenerTargetDefinitionBuilder> setup)
+    public virtual IListenerDefinitionBuilder Read(string readMode)
     {
-        var builder = new ListenerTargetDefinitionBuilder();
-        setup(builder);
-        this.Target = builder.Build();
+        ArgumentException.ThrowIfNullOrWhiteSpace(readMode);
+        this.Listener.Read = readMode;
         return this;
     }
 
     /// <inheritdoc/>
-    public virtual ListenerDefinition Build()
+    public virtual new ListenerDefinition Build()
     {
-        if (this.Target == null) throw new NullReferenceException("The listener's target must be set");
-        return new()
-        {
-            To = this.Target
-        };
+        var to = base.Build();
+        if (to == null) throw new NullReferenceException("The listener's target must be set");
+        this.Listener.To = to;
+        return this.Listener;
     }
 
 }

src/ServerlessWorkflow.Sdk.Builders/OAuth2AuthenticationClientDefinitionBuilder.cs

@@ -43,15 +43,15 @@ public class OAuth2AuthenticationClientDefinitionBuilder
     /// <inheritdoc/>
     public virtual IOAuth2AuthenticationClientDefinitionBuilder WithId(string id)
     {
-        ArgumentException.ThrowIfNullOrEmpty(id);
+        ArgumentException.ThrowIfNullOrWhiteSpace(id);
         this.Id = id;
         return this;
     }
 
     /// <inheritdoc/>
     public virtual IOAuth2AuthenticationClientDefinitionBuilder WithSecret(string secret)
     {
-        ArgumentException.ThrowIfNullOrEmpty(secret);
+        ArgumentException.ThrowIfNullOrWhiteSpace(secret);
         this.Secret = secret;
         return this;
     }

src/ServerlessWorkflow.Sdk.Builders/OutputDataModelDefinitionBuilder.cs

@@ -0,0 +1,49 @@
+// Copyright © 2024-Present The Serverless Workflow Specification Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"),
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace ServerlessWorkflow.Sdk.Builders;
+
+/// <summary>
+/// Represents the default implementation of the <see cref="IOutputDataModelDefinitionBuilder"/> interface
+/// </summary>
+public class OutputDataModelDefinitionBuilder
+    : IOutputDataModelDefinitionBuilder
+{
+
+    /// <summary>
+    /// Gets the <see cref="OutputDataModelDefinition"/> to configure
+    /// </summary>
+    protected OutputDataModelDefinition Output { get; } = new();
+
+    /// <inheritdoc/>
+    public virtual IOutputDataModelDefinitionBuilder As(object expression)
+    {
+        ArgumentNullException.ThrowIfNull(expression);
+        this.Output.As = expression;
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual IOutputDataModelDefinitionBuilder WithSchema(Action<ISchemaDefinitionBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new SchemaDefinitionBuilder();
+        setup(builder);
+        this.Output.Schema = builder.Build();
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual OutputDataModelDefinition Build() => this.Output;
+
+}

src/ServerlessWorkflow.Sdk.Builders/SchemaDefinitionBuilder.cs

@@ -0,0 +1,57 @@
+// Copyright © 2024-Present The Serverless Workflow Specification Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"),
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace ServerlessWorkflow.Sdk.Builders;
+
+/// <summary>
+/// Represents the default implementation of the <see cref="ISchemaDefinitionBuilder"/> interface
+/// </summary>
+public class SchemaDefinitionBuilder
+    : ISchemaDefinitionBuilder
+{
+
+    /// <summary>
+    /// Gets the <see cref="SchemaDefinition"/> to configure
+    /// </summary>
+    protected SchemaDefinition Schema { get; } = new();
+
+    /// <inheritdoc/>
+    public virtual ISchemaDefinitionBuilder WithFormat(string format)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(format);
+        this.Schema.Format = format;
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual ISchemaDefinitionBuilder WithResource(Action<IExternalResourceDefinitionBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new ExternalResourceDefinitionBuilder();
+        setup(builder);
+        this.Schema.Resource = builder.Build();
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual ISchemaDefinitionBuilder WithDocument(object document)
+    {
+        ArgumentNullException.ThrowIfNull(document);
+        this.Schema.Document = document;
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual SchemaDefinition Build() => this.Schema;
+
+}

src/ServerlessWorkflow.Sdk.Builders/SubscriptionIteratorDefinitionBuilder.cs

@@ -0,0 +1,77 @@
+// Copyright © 2024-Present The Serverless Workflow Specification Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"),
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace ServerlessWorkflow.Sdk.Builders;
+
+/// <summary>
+/// Represents the default implementation of the <see cref="ISubscriptionIteratorDefinitionBuilder"/> interface
+/// </summary>
+public class SubscriptionIteratorDefinitionBuilder
+    : ISubscriptionIteratorDefinitionBuilder
+{
+
+    /// <summary>
+    /// Gets the <see cref="SubscriptionIteratorDefinition"/> to configure
+    /// </summary>
+    protected SubscriptionIteratorDefinition Iterator { get; } = new();
+
+    /// <inheritdoc/>
+    public virtual ISubscriptionIteratorDefinitionBuilder Item(string item)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(item);
+        this.Iterator.Item = item;
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual ISubscriptionIteratorDefinitionBuilder At(string at)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(at);
+        this.Iterator.At = at;
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual ISubscriptionIteratorDefinitionBuilder Do(Action<ITaskDefinitionMapBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new TaskDefinitionMapBuilder();
+        setup(builder);
+        this.Iterator.Do = builder.Build();
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual ISubscriptionIteratorDefinitionBuilder Output(Action<IOutputDataModelDefinitionBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new OutputDataModelDefinitionBuilder();
+        setup(builder);
+        this.Iterator.Output = builder.Build();
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual ISubscriptionIteratorDefinitionBuilder Export(Action<IOutputDataModelDefinitionBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new OutputDataModelDefinitionBuilder();
+        setup(builder);
+        this.Iterator.Export = builder.Build();
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual SubscriptionIteratorDefinition Build() => this.Iterator;
+
+}

src/ServerlessWorkflow.Sdk.Builders/TaskDefinitionBuilder.cs

@@ -34,6 +34,21 @@ public abstract class TaskDefinitionBuilder<TBuilder, TDefinition>
     /// </summary>
     protected OneOf<TimeoutDefinition, string>? Timeout { get; set; }
 
+    /// <summary>
+    /// Gets/sets the task's input data, if any
+    /// </summary>
+    protected InputDataModelDefinition? Input { get; set; }
+
+    /// <summary>
+    /// Gets/sets the task's output data, if any
+    /// </summary>
+    protected OutputDataModelDefinition? Output { get; set; }
+
+    /// <summary>
+    /// Gets/sets the task's export data, if any
+    /// </summary>
+    protected OutputDataModelDefinition? Export { get; set; }
+
     /// <summary>
     /// Gets/sets the flow directive, if any, used to then execute
     /// </summary>
@@ -73,6 +88,36 @@ public virtual TBuilder WithTimeout(Action<ITimeoutDefinitionBuilder> setup)
         return (TBuilder)(object)this;
     }
 
+    /// <inheritdoc/>
+    public virtual TBuilder WithInput(Action<IInputDataModelDefinitionBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new InputDataModelDefinitionBuilder();
+        setup(builder);
+        this.Input = builder.Build();
+        return (TBuilder)(object)this;
+    }
+
+    /// <inheritdoc/>
+    public virtual TBuilder WithOutput(Action<IOutputDataModelDefinitionBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new OutputDataModelDefinitionBuilder();
+        setup(builder);
+        this.Output = builder.Build();
+        return (TBuilder)(object)this;
+    }
+
+    /// <inheritdoc/>
+    public virtual TBuilder WithExport(Action<IOutputDataModelDefinitionBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new OutputDataModelDefinitionBuilder();
+        setup(builder);
+        this.Export = builder.Build();
+        return (TBuilder)(object)this;
+    }
+
     /// <inheritdoc/>
     public virtual TBuilder Then(string directive)
     {
@@ -95,6 +140,9 @@ protected virtual TDefinition Configure(TDefinition definition)
             else definition.TimeoutReference = this.Timeout.T2Value;
         }
         definition.Then = this.ThenDirective;
+        definition.Input = this.Input;
+        definition.Output = this.Output;
+        definition.Export = this.Export;
         return definition;
     }
 

src/ServerlessWorkflow.Sdk.Builders/WorkflowDefinitionBuilder.cs

@@ -63,6 +63,16 @@ public class WorkflowDefinitionBuilder
     /// </summary>
     protected OneOf<TimeoutDefinition, string>? Timeout { get; set; }
 
+    /// <summary>
+    /// Gets/sets the workflow's input data, if any
+    /// </summary>
+    protected InputDataModelDefinition? Input { get; set; }
+
+    /// <summary>
+    /// Gets/sets the workflow's output data, if any
+    /// </summary>
+    protected OutputDataModelDefinition? Output { get; set; }
+
     /// <summary>
     /// Gets/sets a name/value mapping of the workflow's reusable components
     /// </summary>
@@ -166,6 +176,26 @@ public virtual IWorkflowDefinitionBuilder WithTimeout(Action<ITimeoutDefinitionB
         return this;
     }
 
+    /// <inheritdoc/>
+    public virtual IWorkflowDefinitionBuilder WithInput(Action<IInputDataModelDefinitionBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new InputDataModelDefinitionBuilder();
+        setup(builder);
+        this.Input = builder.Build();
+        return this;
+    }
+
+    /// <inheritdoc/>
+    public virtual IWorkflowDefinitionBuilder WithOutput(Action<IOutputDataModelDefinitionBuilder> setup)
+    {
+        ArgumentNullException.ThrowIfNull(setup);
+        var builder = new OutputDataModelDefinitionBuilder();
+        setup(builder);
+        this.Output = builder.Build();
+        return this;
+    }
+
     /// <inheritdoc/>
     public virtual IWorkflowDefinitionBuilder UseAuthentication(string name, AuthenticationPolicyDefinition authentication)
     {

src/ServerlessWorkflow.Sdk/EventReadMode.cs

@@ -0,0 +1,46 @@
+// Copyright © 2024-Present The Serverless Workflow Specification Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"),
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace ServerlessWorkflow.Sdk;
+
+/// <summary>
+/// Enumerates all supported event read modes
+/// </summary>
+public static class EventReadMode
+{
+
+    /// <summary>
+    /// Indicates that only the data of consumed events should be read
+    /// </summary>
+    public const string Data = "data";
+    /// <summary>
+    /// Indicates that the whole event envelope should be read, including context attributes
+    /// </summary>
+    public const string Envelope = "envelope";
+    /// <summary>
+    /// Indicates that the event's raw data should be read, without additional transformation (i.e. deserialization)
+    /// </summary>
+    public const string Raw = "raw";
+
+    /// <summary>
+    /// Gets a new <see cref="IEnumerable{T}"/> containing all supported event read modes
+    /// </summary>
+    /// <returns>A new <see cref="IEnumerable{T}"/> containing all supported event read modes</returns>
+    public static IEnumerable<string> AsEnumerable()
+    {
+        yield return Data;
+        yield return Envelope;
+        yield return Raw;
+    }
+
+}

src/ServerlessWorkflow.Sdk/Models/AsyncApiMessageDefinition.cs

@@ -32,4 +32,4 @@ public record AsyncApiMessageDefinition
     [DataMember(Name = "headers", Order = 2), JsonPropertyName("headers"), JsonPropertyOrder(2), YamlMember(Alias = "headers", Order = 2)]
     public virtual object? Headers { get; set; }
 
-}
+}

src/ServerlessWorkflow.Sdk/Models/AsyncApiSubscriptionDefinition.cs

@@ -33,4 +33,10 @@ public record AsyncApiSubscriptionDefinition
     [DataMember(Name = "consume", Order = 2), JsonPropertyName("consume"), JsonPropertyOrder(2), YamlMember(Alias = "consume", Order = 2)]
     public required virtual AsyncApiSubscriptionLifetimeDefinition Consume { get; set; }
 
+    /// <summary>
+    /// Gets/sets the configuration of the iterator, if any, used to process each consumed message
+    /// </summary>
+    [DataMember(Name = "foreach", Order = 3), JsonPropertyName("foreach"), JsonPropertyOrder(3), YamlMember(Alias = "foreach", Order = 3)]
+    public virtual SubscriptionIteratorDefinition? Foreach { get; set; }
+
 }

src/ServerlessWorkflow.Sdk/Models/ListenerDefinition.cs

@@ -27,4 +27,11 @@ public record ListenerDefinition
     [DataMember(Name = "to", Order = 1), JsonPropertyName("to"), JsonPropertyOrder(1), YamlMember(Alias = "to", Order = 1)]
     public required virtual EventConsumptionStrategyDefinition To { get; set; }
 
+    /// <summary>
+    /// Gets/sets a string that specifies how events are read during the listen operation<para></para>
+    /// See <see cref="EventReadMode"/>. Defaults to <see cref="EventReadMode.Data"/>
+    /// </summary>
+    [DataMember(Name = "read", Order = 1), JsonPropertyName("read"), JsonPropertyOrder(1), YamlMember(Alias = "read", Order = 1)]
+    public virtual string? Read { get; set; }
+
 }

src/ServerlessWorkflow.Sdk/Models/SubscriptionIteratorDefinition.cs

@@ -0,0 +1,55 @@
+// Copyright © 2024-Present The Serverless Workflow Specification Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License"),
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace ServerlessWorkflow.Sdk.Models;
+
+/// <summary>
+/// Represents the definition of a subscription iterator, used to configure the processing of each event or message consumed by a subscription
+/// </summary>
+[DataContract]
+public record SubscriptionIteratorDefinition
+{
+
+    /// <summary>
+    /// Gets/sets the name of the variable used to store the item being enumerated.<para></para>
+    /// Defaults to `item`
+    /// </summary>
+    [DataMember(Name = "item", Order = 1), JsonPropertyName("item"), JsonPropertyOrder(1), YamlMember(Alias = "item", Order = 1)]
+    public virtual string? Item { get; set; }
+
+    /// <summary>
+    /// Gets/sets the name of the variable used to store the index of the item being enumerates<para></para>
+    /// Defaults to `index`
+    /// </summary>
+    [DataMember(Name = "at", Order = 2), JsonPropertyName("at"), JsonPropertyOrder(2), YamlMember(Alias = "at", Order = 2)]
+    public virtual string? At { get; set; }
+
+    /// <summary>
+    /// Gets/sets the tasks to run for each consumed event or message
+    /// </summary>
+    [DataMember(Name = "do", Order = 3), JsonPropertyName("do"), JsonPropertyOrder(3), YamlMember(Alias = "do", Order = 3)]
+    public virtual Map<string, TaskDefinition>? Do { get; set; }
+
+    /// <summary>
+    /// Gets/sets the definition, if any, of the data to output for each iteration
+    /// </summary>
+    [DataMember(Name = "output", Order = 4), JsonPropertyName("output"), JsonPropertyOrder(4), YamlMember(Alias = "output", Order = 4)]
+    public virtual OutputDataModelDefinition? Output { get; set; }
+
+    /// <summary>
+    /// Gets/sets the definition, if any, of the data to export for each iteration
+    /// </summary>
+    [DataMember(Name = "export", Order = 5), JsonPropertyName("export"), JsonPropertyOrder(5), YamlMember(Alias = "export", Order = 5)]
+    public virtual OutputDataModelDefinition? Export { get; set; }
+
+}

src/ServerlessWorkflow.Sdk/Models/Tasks/ListenTaskDefinition.cs

@@ -32,4 +32,10 @@ public record ListenTaskDefinition
     [DataMember(Name = "listen", Order = 1), JsonPropertyName("listen"), JsonPropertyOrder(1), YamlMember(Alias = "listen", Order = 1)]
     public required virtual ListenerDefinition Listen { get; set; }
 
+    /// <summary>
+    /// Gets/sets the configuration of the iterator, if any, used to process each consumed event
+    /// </summary>
+    [DataMember(Name = "foreach", Order = 2), JsonPropertyName("foreach"), JsonPropertyOrder(2), YamlMember(Alias = "foreach", Order = 2)]
+    public virtual SubscriptionIteratorDefinition? Foreach { get; set; }
+
 }