Define a form using JSON schema in the v3 C# SDK

Article
12/13/2017

APPLIES TO: SDK v3

If you use a C# class to define the form when you create a bot with FormFlow, the form derives from the static definition of your type in C#. As an alternative, you may instead define the form by using JSON schema. A form that is defined using JSON schema is purely data-driven; you can change the form (and therefore, the behavior of the bot) simply by updating the schema.

The JSON schema describes the fields within your JObject and includes annotations that control prompts, templates, and terms. To use JSON schema with FormFlow, you must add the Microsoft.Bot.Builder.FormFlow.Json NuGet package to your project and import the Microsoft.Bot.Builder.FormFlow.Json namespace.

Standard keywords

FormFlow supports these standard JSON Schema keywords:

Keyword	Description
type	Defines the type of data that the field contains.
enum	Defines the valid values for the field.
minimum	Defines the minimum numeric value allowed for the field (as described in NumericAttribute).
maximum	Defines the maximum numeric value allowed for the field (as described in NumericAttribute).
required	Defines which fields are required.
pattern	Validates string values (as described in PatternAttribute).

Extensions to JSON Schema

FormFlow extends the standard JSON Schema to support several additional properties.

Additional properties at the root of the schema

Property	Value
OnCompletion	C# script with arguments `(IDialogContext context, JObject state)` for completing the form.
References	References to include in scripts. For example, `[assemblyReference, ...]`. Paths should be absolute or relative to the current directory. By default, the script includes `Microsoft.Bot.Builder.dll`.
Imports	Imports to include in scripts. For example, `[import, ...]`. By default, the script includes the `Microsoft.Bot.Builder`, `Microsoft.Bot.Builder.Dialogs`, `Microsoft.Bot.Builder.FormFlow`, `Microsoft.Bot.Builder.FormFlow.Advanced`, `System.Collections.Generic`, and `System.Linq` namespaces.

Additional properties at the root of the schema or as peers of the type property

Property	Value
Templates	`{ TemplateUsage: { Patterns: [string, ...], <args> }, ...}`
Prompt	`{ Patterns:[string, ...] <args>}`

To specify templates and prompts in JSON schema, use the same vocabulary as defined by TemplateAttribute and PromptAttribute. Property names and values in the schema should match the property names and values in the underlying C# enumeration. For example, this schema snippet defines a template that overrides the TemplateUsage.NotUnderstood template and specifies a TemplateBaseAttribute.ChoiceStyle:

"Templates":{ "NotUnderstood": { "Patterns": ["I don't get it"], "ChoiceStyle":"Auto"}}

Additional properties as peers of the type property

Property	Contents	Description
DateTime	bool	Indicates whether field is a `DateTime` field.
Describe	string or object	Description of a field as described in DescribeAttribute.
Terms	`[string,...]`	Regular expressions for matching a field value as described in TermsAttribute.
MaxPhrase	int	Runs your terms through `Language.GenerateTerms(string, int)` to expand them.
Values	`{ string: {Describe:string \| object, Terms:[string, ...], MaxPhrase}, ...}`
Active	script	C# script with arguments `(JObject state)->bool` to test whether the field, message, or confirmation is active.
Validate	script	C# script with arguments `(JObject state, object value)->ValidateResult` for validating a field value.
Define	script	C# script with arguments `(JObject state, Field<JObject> field)` for dynamically defining a field.
Next	script	C# script with arguments `(object value, JObject state)` for determining the next step after filling in a field.
Before	`[confirm \| message, ...]`
After	`[confirm \| message, ...]`
Dependencies	[string, ...]	Fields that this field, message, or confirmation depends on.

Use {Confirm:script|[string, ...], ...templateArgs} within the value of the Before property or the After property to define a confirmation by using either a C# script with argument (JObject state) or a set of patterns that will be randomly selected with optional template arguments.

Use {Message:script|[string, ...] ...templateArgs} within the value of the Before property or the After property to define a message by using either a C# script with argument (JObject state) or a set of patterns that will be randomly selected with optional template arguments.

Scripts

Several of the properties that are described above contain a script as the property value. A script can be any snippet of C# code that you might normally find in the body of a method. You can add references by using the References property and/or the Imports property. Special global variables include:

Variable	Description
choice	Internal dispatch for the script to execute.
state	`JObject` form state bound for all scripts.
ifield	`IField<JObject>` to allow reasoning over the current field for all scripts except Message/Confirm prompt builders.
value	Object value to be validated for Validate.
field	`Field<JObject>` to allow dynamically updating a field in Define.
context	`IDialogContext` context to allow posting results in OnCompletion.

Fields that are defined via JSON schema have the same ability to extend or override the definitions programatically as any other field. They can also be localized in the same way.

JSON schema example

The simplest way to define a form is to define everything, including any C# code, directly in the JSON schema. This example shows the JSON schema for the annotated sandwich bot that is described in Customize a form using FormBuilder.

{
  "References": [ "Microsoft.Bot.Sample.AnnotatedSandwichBot.dll" ],
  "Imports": [ "Microsoft.Bot.Sample.AnnotatedSandwichBot.Resource" ],
  "type": "object",
  "required": [
    "Sandwich",
    "Length",
    "Ingredients",
    "DeliveryAddress"
  ],
  "Templates": {
    "NotUnderstood": {
      "Patterns": [ "I do not understand \"{0}\".", "Try again, I don't get \"{0}\"." ]
    },
    "EnumSelectOne": {
      "Patterns": [ "What kind of {&} would you like on your sandwich? {||}" ],
      "ChoiceStyle": "Auto"
    }
  },
  "properties": {
    "Sandwich": {
      "Prompt": { "Patterns": [ "What kind of {&} would you like? {||}" ] },
      "Before": [ { "Message": [ "Welcome to the sandwich order bot!" ] } ],
      "Describe": { "Image": "https://placeholdit.imgix.net/~text?txtsize=16&txt=Sandwich&w=125&h=40&txttrack=0&txtclr=000&txtfont=bold" },
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "BLT",
        "BlackForestHam",
        "BuffaloChicken",
        "ChickenAndBaconRanchMelt",
        "ColdCutCombo",
        "MeatballMarinara",
        "OvenRoastedChicken",
        "RoastBeef",
        "RotisserieStyleChicken",
        "SpicyItalian",
        "SteakAndCheese",
        "SweetOnionTeriyaki",
        "Tuna",
        "TurkeyBreast",
        "Veggie"
      ],
      "Values": {
        "RotisserieStyleChicken": {
          "Terms": [ "rotis\\w* style chicken" ],
          "MaxPhrase": 3
        }
      }
    },
    "Length": {
      "Prompt": {
        "Patterns": [ "What size of sandwich do you want? {||}" ]
      },
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "SixInch",
        "FootLong"
      ]
    },
    "Ingredients": {
      "type": "object",
      "required": [ "Bread" ],
      "properties": {
        "Bread": {
          "type": [
            "string",
            "null"
          ],
          "Describe": {
            "Title": "Sandwich Bot",
            "SubTitle": "Bread Picker"
          },
          "enum": [
            "NineGrainWheat",
            "NineGrainHoneyOat",
            "Italian",
            "ItalianHerbsAndCheese",
            "Flatbread"
          ]
        },
        "Cheese": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "American",
            "MontereyCheddar",
            "Pepperjack"
          ]
        },
        "Toppings": {
          "type": "array",
          "items": {
            "type": "integer",
            "enum": [
              "Everything",
              "Avocado",
              "BananaPeppers",
              "Cucumbers",
              "GreenBellPeppers",
              "Jalapenos",
              "Lettuce",
              "Olives",
              "Pickles",
              "RedOnion",
              "Spinach",
              "Tomatoes"
            ],
            "Values": {
              "Everything": { "Terms": [ "except", "but", "not", "no", "all", "everything" ] }
            }
          },
          "Validate": "var values = ((List<object>) value).OfType<string>(); var result = new ValidateResult {IsValid = true, Value = values} ; if (values != null && values.Contains(\"Everything\")) { result.Value = (from topping in new string[] {  \"Avocado\", \"BananaPeppers\", \"Cucumbers\", \"GreenBellPeppers\", \"Jalapenos\", \"Lettuce\", \"Olives\", \"Pickles\", \"RedOnion\", \"Spinach\", \"Tomatoes\"} where !values.Contains(topping) select topping).ToList();} return result;",
          "After": [ { "Message": [ "For sandwich toppings you have selected {Ingredients.Toppings}." ] } ]
        },
        "Sauces": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string",
            "enum": [
              "ChipotleSouthwest",
              "HoneyMustard",
              "LightMayonnaise",
              "RegularMayonnaise",
              "Mustard",
              "Oil",
              "Pepper",
              "Ranch",
              "SweetOnion",
              "Vinegar"
            ]
          }
        }
      }
    },
    "Specials": {
      "Templates": {
        "NoPreference": { "Patterns": [ "None" ] }
      },
      "type": [
        "string",
        "null"
      ],
      "Active": "return (string) state[\"Length\"] == \"FootLong\";",
      "Define": "field.SetType(null).AddDescription(\"cookie\", DynamicSandwich.FreeCookie).AddTerms(\"cookie\", Language.GenerateTerms(DynamicSandwich.FreeCookie, 2)).AddDescription(\"drink\", DynamicSandwich.FreeDrink).AddTerms(\"drink\", Language.GenerateTerms(DynamicSandwich.FreeDrink, 2)); return true;",
      "After": [ { "Confirm": "var cost = 0.0; switch ((string) state[\"Length\"]) { case \"SixInch\": cost = 5.0; break; case \"FootLong\": cost=6.50; break;} return new PromptAttribute($\"Total for your sandwich is {cost:C2} is that ok?\");" } ]
    },
    "DeliveryAddress": {
      "type": [
        "string",
        "null"
      ],
      "Validate": "var result = new ValidateResult{ IsValid = true, Value = value}; var address = (value as string).Trim(); if (address.Length > 0 && (address[0] < '0' || address[0] > '9')) {result.Feedback = DynamicSandwich.BadAddress; result.IsValid = false; } return result;"
    },
    "PhoneNumber": {
      "type": [ "string", "null" ],
      "pattern": "(\\(\\d{3}\\))?\\s*\\d{3}(-|\\s*)\\d{4}"
    },
    "DeliveryTime": {
      "Templates": {
        "StatusFormat": {
          "Patterns": [ "{&}: {:t}" ],
          "FieldCase": "None"
        }
      },
      "DateTime": true,
      "type": [
        "string",
        "null"
      ],
      "After": [ { "Confirm": [ "Do you want to order your {Length} {Sandwich} on {Ingredients.Bread} {&Ingredients.Bread} with {[{Ingredients.Cheese} {Ingredients.Toppings} {Ingredients.Sauces} to be sent to {DeliveryAddress} {?at {DeliveryTime}}?" ] } ]
    },
    "Rating": {
      "Describe": "your experience today",
      "type": [
        "number",
        "null"
      ],
      "minimum": 1,
      "maximum": 5,
      "After": [ { "Message": [ "Thanks for ordering your sandwich!" ] } ]
    }
  },
  "OnCompletion": "await context.PostAsync(\"We are currently processing your sandwich. We will message you the status.\");"
}

Implement FormFlow with JSON schema

To implement FormFlow with a JSON schema, use FormBuilderJson, which supports the same fluent interface as FormBuilder. This code example shows how to implement the JSON schema for the annotated sandwich bot that is described in Customize a form using FormBuilder.

public static IForm<JObject> BuildJsonForm()
{
    using (var stream = Assembly.GetExecutingAssembly().GetManifestResourceStream("Microsoft.Bot.Sample.AnnotatedSandwichBot.AnnotatedSandwich.json"))
    {
        var schema = JObject.Parse(new StreamReader(stream).ReadToEnd());
        return new FormBuilderJson(schema)
            .AddRemainingFields()
            .Build();
    }
    ...
}

Sample code

For complete samples that show how to implement FormFlow using the Bot Framework SDK for .NET, see the Multi-Dialog Bot sample and the Contoso Flowers Bot sample in GitHub.