serverlessworkflow · cdavernas · Jun 28, 2023 · Jun 24, 2023 · Jun 26, 2023 · Jun 27, 2023
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,101 @@
+
+[*.{cs,vb}]
+#### Naming styles ####
+
+# Naming rules
+
+dotnet_naming_rule.interface_should_be_begins_with_i.severity = suggestion
+dotnet_naming_rule.interface_should_be_begins_with_i.symbols = interface
+dotnet_naming_rule.interface_should_be_begins_with_i.style = begins_with_i
+
+dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion
+dotnet_naming_rule.types_should_be_pascal_case.symbols = types
+dotnet_naming_rule.types_should_be_pascal_case.style = pascal_case
+
+dotnet_naming_rule.non_field_members_should_be_pascal_case.severity = suggestion
+dotnet_naming_rule.non_field_members_should_be_pascal_case.symbols = non_field_members
+dotnet_naming_rule.non_field_members_should_be_pascal_case.style = pascal_case
+
+# Symbol specifications
+
+dotnet_naming_symbols.interface.applicable_kinds = interface
+dotnet_naming_symbols.interface.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
+dotnet_naming_symbols.interface.required_modifiers = 
+
+dotnet_naming_symbols.types.applicable_kinds = class, struct, interface, enum
+dotnet_naming_symbols.types.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
+dotnet_naming_symbols.types.required_modifiers = 
+
+dotnet_naming_symbols.non_field_members.applicable_kinds = property, event, method
+dotnet_naming_symbols.non_field_members.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected
+dotnet_naming_symbols.non_field_members.required_modifiers = 
+
+# Naming styles
+
+dotnet_naming_style.begins_with_i.required_prefix = I
+dotnet_naming_style.begins_with_i.required_suffix = 
+dotnet_naming_style.begins_with_i.word_separator = 
+dotnet_naming_style.begins_with_i.capitalization = pascal_case
+
+dotnet_naming_style.pascal_case.required_prefix = 
+dotnet_naming_style.pascal_case.required_suffix = 
+dotnet_naming_style.pascal_case.word_separator = 
+dotnet_naming_style.pascal_case.capitalization = pascal_case
+
+dotnet_naming_style.pascal_case.required_prefix = 
+dotnet_naming_style.pascal_case.required_suffix = 
+dotnet_naming_style.pascal_case.word_separator = 
+dotnet_naming_style.pascal_case.capitalization = pascal_case
+dotnet_style_operator_placement_when_wrapping = beginning_of_line
+tab_width = 4
+indent_size = 4
+end_of_line = crlf
+dotnet_style_coalesce_expression = true:suggestion
+dotnet_style_null_propagation = true:suggestion
+dotnet_style_prefer_is_null_check_over_reference_equality_method = true:suggestion
+dotnet_style_prefer_auto_properties = true:silent
+dotnet_style_object_initializer = true:suggestion
+dotnet_style_collection_initializer = true:suggestion
+dotnet_style_prefer_simplified_boolean_expressions = true:suggestion
+dotnet_style_prefer_conditional_expression_over_assignment = true:silent
+dotnet_style_prefer_conditional_expression_over_return = true:silent
+dotnet_style_explicit_tuple_names = true:suggestion
+dotnet_style_prefer_inferred_tuple_names = true:suggestion
+dotnet_style_prefer_inferred_anonymous_type_member_names = true:suggestion
+dotnet_style_prefer_compound_assignment = true:suggestion
+dotnet_style_prefer_simplified_interpolation = true:suggestion
+dotnet_style_namespace_match_folder = true:suggestion
+dotnet_style_readonly_field = true:suggestion
+
+[*.cs]
+csharp_indent_labels = one_less_than_current
+csharp_space_around_binary_operators = before_and_after
+csharp_using_directive_placement = outside_namespace:silent
+csharp_prefer_simple_using_statement = true:suggestion
+csharp_prefer_braces = true:silent
+csharp_style_namespace_declarations = block_scoped:silent
+csharp_style_prefer_method_group_conversion = true:silent
+csharp_style_prefer_top_level_statements = true:silent
+csharp_style_expression_bodied_methods = false:silent
+csharp_style_expression_bodied_constructors = false:silent
+csharp_style_expression_bodied_operators = false:silent
+csharp_style_expression_bodied_properties = true:silent
+csharp_style_expression_bodied_indexers = true:silent
+csharp_style_expression_bodied_accessors = true:silent
+csharp_style_expression_bodied_lambdas = true:silent
+csharp_style_expression_bodied_local_functions = false:silent
+csharp_style_throw_expression = true:suggestion
+csharp_style_prefer_null_check_over_type_check = true:suggestion
+csharp_prefer_simple_default_expression = true:suggestion
+csharp_style_prefer_local_over_anonymous_function = true:suggestion
+csharp_style_prefer_index_operator = true:suggestion
+csharp_style_prefer_range_operator = true:suggestion
+csharp_style_implicit_object_creation_when_type_is_apparent = true:suggestion
+csharp_style_prefer_tuple_swap = true:suggestion
+csharp_style_prefer_utf8_string_literals = true:suggestion
+csharp_style_inlined_variable_declaration = true:suggestion
+csharp_style_deconstructed_variable_declaration = true:suggestion
+csharp_style_unused_value_assignment_preference = discard_variable:suggestion
+csharp_style_unused_value_expression_statement_preference = discard_variable:silent
+
+file_header_template = Copyright � 2023-Present The Serverless Workflow Specification Authors\n\nLicensed under the Apache License, Version 2.0 (the "License"),\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an "AS IS" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 
 # Serverless Workflow Specification - .NET SDK
 
-Provides .NET 6.0 API/SPI and Model Validation for the [Serverless Workflow Specification](https://github.com/serverlessworkflow/specification)
+Provides .NET 7.0 API/SPI and Model Validation for the [Serverless Workflow Specification](https://github.com/serverlessworkflow/specification)
 
 With the SDK, you can:
 
@@ -15,7 +15,7 @@ With the SDK, you can:
 
 | Latest Releases | Conformance to spec version |
 | :---: | :---: |
-| [0.8.0.10](https://github.com/serverlessworkflow/sdk-net/releases/) | [v0.8](https://github.com/serverlessworkflow/specification/tree/0.8.x) |
+| [0.8.7](https://github.com/serverlessworkflow/sdk-net/releases/) | [0.8](https://github.com/serverlessworkflow/specification/tree/0.8.x) |
 
 ### Getting Started
 
@@ -27,9 +27,9 @@ dotnet nuget add package ServerlessWorkflow.Sdk
 services.AddServerlessWorkflow();
 ```
 
-### How to use
+### Usage
 
-#### Building workflows programatically
+#### Build workflows programatically
 
 ```csharp
 var workflow = WorkflowDefinition.Create("MyWorkflow", "MyWorkflow", "1.0")
@@ -60,7 +60,7 @@ var workflow = WorkflowDefinition.Create("MyWorkflow", "MyWorkflow", "1.0")
   .Build();
 ```
 
-#### Reading workflows
+#### Read workflows
 
 ```csharp
 var reader = WorkflowReader.Create();
@@ -70,7 +70,7 @@ using(Stream stream = File.OpenRead("myWorkflow.json"))
 }
 ```
 
-#### Writing workflows
+#### Write workflows
 
 ```csharp
   var writer = WorkflowWriter.Create();
@@ -88,9 +88,163 @@ using(Stream stream = File.OpenRead("myWorkflow.json"))
   }
 ```
 
-#### Validating workflows
+#### Validate workflows
 
 ```csharp
 var validator = serviceProvider.GetRequiredService<IValidator<WorkflowDefinition>>();
 var validationResult = validator.Validate(myWorkflow);
 ```
+
+#### Extend Workflows
+
+The SDK allows extending the Serverless Workflow in two ways, possibly combined: via metadata and via extensions.
+
+#### Metadata
+
+Workflow components that support metadata, such as `WorkflowDefinition` or `StateDefinition`, expose a `metadata` property, 
+which is a dynamic name/value mapping of properties used to enrich the serverless workflow model with information beyond its core definitions.
+
+It has the advantage of being an easy, cross-compatible way of declaring additional data, but lacks well-defined, well-documented schema of the data, thus loosing the ability to validate it
+without custom implementation.
+
+*Adding metadata to a workflow:*
+```csharp
+var workflow = new WorkflowBuilder()
+    ...
+    .WithMetadata(new Dictionary<string, object>() { { "metadataPropertyName", metadataPropertyValue } })
+    ...
+    .Build();
+```
+
+*Resulting workflow:*
+
+```yaml
+id: sample-workflow
+version: 1.0.0
+specVersion: 0.8
+metadata:
+  metadataPropertyName: metadataPropertyValue #added to the metadata property of supporting components
+...
+```
+
+
+#### Extension
+
+Users have the ability to define extensions, providing the ability to extend, override or replace parts of the Serverless Workflow schema.
+
+To do so, you must first create a file containing the JsonSchema of your extension, then reference it in your workflow definition.
+
+*Schema of a sample extension that adds a new `greet` `functionType`:*
+<table>
+<tr>
+    <th>JSON</th>
+    <th>YAML</th>
+</tr>
+<tr>
+<td valign="top">
+
+```json
+{
+  "$defs": {
+    "functions": {
+      "definitions": {
+        "function": {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "Defines the function type. Is either `rest`, `asyncapi, `rpc`, `graphql`, `odata`, `expression` or `greet`. Default is `rest`",
+              "enum": [
+                "rest",
+                "asyncapi",
+                "rpc",
+                "graphql",
+                "odata",
+                "expression",
+                "custom",
+                "greet"
+              ],
+              "default": "rest"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+</td>
+
+<td valign="top">
+
+```yaml
+'$defs':
+  functions:
+    definitions:
+      function:
+        type: object
+        properties:
+          type:
+            type: string
+            description: Defines the function type. Is either `rest`, `asyncapi, `rpc`,
+              `graphql`, `odata`, `expression` or `greet`. Default is `rest`
+            enum:
+            - rest
+            - asyncapi
+            - rpc
+            - graphql
+            - odata
+            - expression
+            - custom
+            - greet
+            default: rest
+```
+
+</td>
+</tr>
+</table>
+
+The above example refers to `/$defs/functions`, because upon validation the SDK bundles all the Serverless Workflow Specification's schemas into the `$defs` property of a single schema.
+
+*In this case, `functions` is the extensionless name of the schema file we want to override (https://serverlessworkflow.io/schemas/latest/functions.json).
+
+A [Json Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) is performed sequentially on the bundled schema with the defined extensions, in declaring order.
+
+*In this case, the above schema will patch the object defined at `/functions/definitions/function` in file https://serverlessworkflow.io/schemas/latest/functions.json*
+
+*Extending a workflow:*
+```csharp
+var workflow = new WorkflowBuilder()
+    .WithId("sample-extended")
+    .WithName("Sample Extended Workflow")
+    .WithVersion("1.0.0")
+    .UseSpecVersion(ServerlessWorkflowSpecVersion.V08)
+    .UseExtension("extensionId", new Uri("file://.../extensions/greet-function-type.json"))
+    .StartsWith("do-work", flow => flow.Execute("greet", action => action
+        .Invoke(function => function
+            .OfType("greet")
+            .WithName("greet")
+            .ForOperation("#"))))
+    .End()
+    .Build();
+```
+
+*Adding extension properties:*
+```csharp
+var workflow = new WorkflowBuilder()
+    ...
+    .WithExtensionProperty("extensionPropertyName", propertyValue } })
+    ...
+    .Build();
+```
+
+*Resulting workflow:*
+
+```yaml
+id: sample-workflow
+version: 1.0.0
+specVersion: 0.8
+extensionPropertyName: propertyValue #added as top level property of extended component, as opposed to metadata
+...
+```
diff --git a/ServerlessWorkflow.Sdk.sln b/ServerlessWorkflow.Sdk.sln
@@ -1,30 +1,53 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 16
-VisualStudioVersion = 16.0.31019.35
+# Visual Studio Version 17
+VisualStudioVersion = 17.4.33213.308
 MinimumVisualStudioVersion = 10.0.40219.1
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ServerlessWorkflow.Sdk", "src\ServerlessWorkflow.Sdk\ServerlessWorkflow.Sdk.csproj", "{E174F5CC-F3DC-4370-AAC1-AC1D7724C792}"
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{9016CF88-4100-425F-9E1A-B6099F55A35B}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ServerlessWorkflow.Sdk.UnitTests", "src\ServerlessWorkflow.Sdk.UnitTests\ServerlessWorkflow.Sdk.UnitTests.csproj", "{70AD35E0-0C14-4EBF-A841-B0D084392753}"
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{60FE2678-84CF-492C-950D-3485582F6712}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{0CD38EC5-C4AB-491A-B6EA-D6C608F68157}"
+	ProjectSection(SolutionItems) = preProject
+		code-of-conduct.md = code-of-conduct.md
+		CONTRIBUTING.md = CONTRIBUTING.md
+		LICENSE = LICENSE
+		MAINTAINERS.md = MAINTAINERS.md
+		maintainer_guidelines.md = maintainer_guidelines.md
+		README.md = README.md
+	EndProjectSection
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ServerlessWorkflow.Sdk", "src\ServerlessWorkflow.Sdk\ServerlessWorkflow.Sdk.csproj", "{1C104B2C-A3E8-4CB9-AE1D-28370B7A705D}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ServerlessWorkflow.Sdk.UnitTests", "tests\ServerlessWorkflow.Sdk.UnitTests\ServerlessWorkflow.Sdk.UnitTests.csproj", "{F1575E10-B57B-4012-97FF-AF942A558D7C}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "solution", "solution", "{F3B6D944-46DA-4CAF-A8BE-0C8F230869F9}"
+	ProjectSection(SolutionItems) = preProject
+		.editorconfig = .editorconfig
+	EndProjectSection
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
 		Release|Any CPU = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(ProjectConfigurationPlatforms) = postSolution
-		{E174F5CC-F3DC-4370-AAC1-AC1D7724C792}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{E174F5CC-F3DC-4370-AAC1-AC1D7724C792}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{E174F5CC-F3DC-4370-AAC1-AC1D7724C792}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{E174F5CC-F3DC-4370-AAC1-AC1D7724C792}.Release|Any CPU.Build.0 = Release|Any CPU
-		{70AD35E0-0C14-4EBF-A841-B0D084392753}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{70AD35E0-0C14-4EBF-A841-B0D084392753}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{70AD35E0-0C14-4EBF-A841-B0D084392753}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{70AD35E0-0C14-4EBF-A841-B0D084392753}.Release|Any CPU.Build.0 = Release|Any CPU
+		{1C104B2C-A3E8-4CB9-AE1D-28370B7A705D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{1C104B2C-A3E8-4CB9-AE1D-28370B7A705D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{1C104B2C-A3E8-4CB9-AE1D-28370B7A705D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{1C104B2C-A3E8-4CB9-AE1D-28370B7A705D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{F1575E10-B57B-4012-97FF-AF942A558D7C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{F1575E10-B57B-4012-97FF-AF942A558D7C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{F1575E10-B57B-4012-97FF-AF942A558D7C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{F1575E10-B57B-4012-97FF-AF942A558D7C}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
+	GlobalSection(NestedProjects) = preSolution
+		{1C104B2C-A3E8-4CB9-AE1D-28370B7A705D} = {9016CF88-4100-425F-9E1A-B6099F55A35B}
+		{F1575E10-B57B-4012-97FF-AF942A558D7C} = {60FE2678-84CF-492C-950D-3485582F6712}
+	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {1402FB0B-4169-41A6-A372-DA260E79481B}
 	EndGlobalSection