JSON-by-example

Introduction

JSON-by-example defines Typed JSON objects.

It works by providing a sample instance of JSON that transpiles into Typed JSON classes. You can find these generated classes in the obj > x64 > Debug or obj > x64 > Release directory of the project with the filename extension json.g.cs.

JSON-by-example is useful for these reasons:

• It can double directly as JSON mockups

• It can express trees of objects and arrays

• It's easy to specify default values

Create JSON-by-example

To create a Typed JSON class, choose New item, or use Ctrl + Shift + A in Visual Studio and then select Starcounter -> Starcounter Typed JSON. The created file contains an empty JSON object which is the JSON-by-example.

One of the simplest JSON-by-example files look like this:

PersonPage.json

{
    "FirstName": "",
    "LastName": ""
}

Here, we set the value to an empty string to declare the type.

You create an instance of the generated Typed JSON with a normal constructor call: new PersonPage().

Accesing the properties of Typed JSON is the same as with any C# object:

var personPage = new PersonPage();
string name = personPage.FirstName; // Contains the value "", an empty string

Default Values

It's simple to set default values in JSON-by-example. Building on the previous code example, it might look like this:

PersonPage.json

{
    "FirstName": "Steven", 
    "LastName": "Smith"
}

By doing this, the JSON returned when creating a new PersonPage object will be {"FirstName":"Steven","LastName":"Smith"}:

Handle.GET("/GetPerson", () =>
{
    return new PersonPage(); // {"FirstName":"Steven","LastName":"Smith"}
});

Supported Datatypes

Typed JSON follows the specification of JSON, which means that objects, arrays and single values are all allowed. One difference is that when working with the C#-object and numbers we have the possibility to specify a more exact type. What in JSON is Number, splits up in Int64, Double and Decimal.

The following is a list of the tokens in JSON and the equivalence in C#:

JSON	C#
{ }	Object
[ ]	Array
"value"	String
123	Int64
true/false	Boolean
1.234 and 2E3	Decimal

To specify the type of a member in JSON-by-example, define it in the code-behind:

{
  "Value": 2E3 // will parse as decimal by default.
}

partial class Foo : Json
{
    static Foo()
    {
        // Value should be of type double, not decimal.
        DefaultTemplate.Value.InstanceType = typeof(double);
    }
}

Writable JSON Values

By default, all the values declared in JSON-by-example are read-only for the client. Any client-side change to a read-only property will result in an error.

To mark a specific value as writable by the client, add a dollar sign ($) at the end of the property name, e.g.:

{
   "FirstName$": "",
   "LastName$": ""
}

Trigger Properties

Trigger properties is a common use for writable JSON properties. They notify the code-behind that a change has happened. Here's an example of a trigger property:

{
    "FirstName": "",
    "LastName": "",
    "SaveTrigger$": 0
}

An incrementation in SaveTrigger$

The HTML Property