Skip to content
Deep Thought

Message Formats

Message Formats

Why?

In order to being able to exchange information, the information needs to be encoded into something that can be sent from A to B.

We need to use message formats whenever we need to pass a barrier where A and B cannot exchange information directly on a binary level. This might be different platforms, different processes or machines that interact witch each other over network.

MessageExchange.excalidraw.svg

Why? (2)

Another big advantage of message formats is, that they allow us to easily store information by creating a file and saving the encoded information into that file.

This is mainly used to persist information, such as configuration values or data, that can be used by programs at runtime.

Message format kinds

We differentiate between two main types of message formats:

  • Text Formats
    • Using character encodings, such as UTF-8, ASCII, …
    • Text can be read and interpreted by humans
    • Information can be easily modified, using any text editor
  • Binary Formats
    • Information is encoded as a sequence of binary data
    • Not standardized. There are different ways of encoding information as binary data.
    • Not human readable
    • Software is needed in order to read, interpret and modify the message.
  • JSON
    • JavaScript Object Notation
  • XML
    • Extensible Markup Language
  • YAML
    • Yet Another Markup Language
  • Protobuf
    • Protocol Buffer

JSON

JSON was specified in the early 2000s. It is e text format that uses Unicode to encode characters. It was derived from JavaScript, but is an open standard format, that is language-independent.

JSON Format

The JSON Format is specified by the ECMA-404 standard. It’s a very simple and easy to understand format. I recommend having a look at the specification.

JSON value

A value can be one of the following:

  • object
  • array
  • number
  • string
  • true
  • false
  • null

JSON string

A string is a sequence of characters wrapped by quotation marks.

Contrary to JavaScript, single quotes ' are not valid quotation marks to identify strings.

JSON number

A number is a sequence of decimal digits. It may have a preceding minus sign. It may have a fractional part prefixed by a decimal point. It may have an exponent prefixed by e or E.

Numeric values that cannot be represented as sequences of digits (such as Infinity and NaN) are not permitted.

JSON objects

Objects are defined by using braces {}. Inbetween the braces we specify key-value pairs in the form of string : value

{
  "key": "value"
}

JSON array

An array structure is a pair of square brackets surrounding zero or more values.

[12, "banana"]

JSON in .NET

Up until recently the most commonly used package for dealing with JSON values in .NET was Newtonsoft Json.NET. This package can be included via NuGet.

Since .NET Core 3.1 System.Text.Json is included in the runtime. It focuses primarily on performance, security and standards compliance. Unless you have a niche need (e.g. dealing with malformed JSON) System.Text.Json is the recommended way.

System.Text.Json - Serialization

using System.Text.Json;


var weatherForecast = new WeatherForecast
{
  Date = DateTime.Parse("2019-08-01"),
  TemperatureCelsius = 25,
  Summary = "Hot"
};


string jsonString = JsonSerializer
  .Serialize(weatherForecast);
Console.WriteLine(jsonString);


public class WeatherForecast
{
  public DateTimeOffset Date { get; set; }
  public int TemperatureCelsius { get; set; }
  public string? Summary { get; set; }
}

System.Text.Json - Serialization Behavior

System.Text.Json - Deserialization

using System.Text.Json;


string jsonString =
@"{
  ""Date"": ""2019-08-01T00:00:00-07:00"",
  ""TemperatureCelsius"": 25,
  ""Summary"": ""Hot""
}";


WeatherForecast? weatherForecast = JsonSerializer
  .Deserialize<WeatherForecast>(jsonString);


public class WeatherForecast
{
  public DateTimeOffset Date { get; set; }
  public int TemperatureCelsius { get; set; }
  public string? Summary { get; set; }
}