Katarzyna's Notes on Json

Notes.md

Some reflections & questions

• Why in MetadataDb there's a byte array instead od Memory / Span?

  • overhead? --> Memory is supposed to be more efficient
  • limited space on stack? --> it's Memory not Span

• What does the new API have from what Json.NET API has?

  • Json Schema Validation - it is paid in Json.NET?
  • other important features:
    • XPath for JSON
    • LINQ
    • XML
  • features comparison? --> there will be integration nuget package

  --> we simply get the JsonDocument and this is the representation of Json data we are using

  Advantages of Json.NET which System.Json.Text has: high performance, easy to use, open source, run everywhere

  (Dis)advantage Json.NET has: very popular

• How is JsonDocument related to JsonElement? --> JsonElement is just reference to parent with idx

• Why would I want to pass a specific JsonReader and how to pass it if its ref? --> special encoding?

Possible Design Solutions

• Immutable? --> still would allow to make changes, creating a new object
• Readonly? --> just a wrapper, underlying collection can change
• Option in JsonDocument? --> the same type, we don't have clearly visible that object is writable, many ifs, seems dirty
• New kind of type? WritableJsonDocument (mutable? modifiable?)? (together with JsonDocument implementing common interface IJsonDocument) --> doesn't stick with other C# coventions?

Underlying types:

JsonObject - represents Json object, root of a tree of nodes

JsonObject : JsonValue { IEnumerable<JsonNode> children; }

JsonNode - represents json syntax tree node, key-value pair

JsonNode 
{
    string key; //or JsonKey?
    JsonValue value;
}

JsonValue - represents value

TextValue : JsonValue { string value; }
NumericValue : JsonValue { int value; }
BooleanValue : JsonValue { bool value; }
NullValue : JsonValue {}
ArrayValue : JsonValue { IEnumerable<JsonValue> children; }

Modifying

Changing the tree itself by replacing values / nodes?

• Do we want to expose underlying tree or just the top-most type e.g. WritableJsonDocument and write traversing methods? --> we would want to return parts of Json - JsonElements from non-writable version; should JsonElement be also turned into interface? what exactly would it correspond to?
• Should JsonObject, JsonNode and JsonValue share a common ancestor? JsonElement?
• Do we want to keep [] syntax for accesing the elements? If we want a common interface, then it should implement this, as well as GetProperty.
• Corresponding method for modifying: SetProperty?
• Additionally: AddProperty? RemoveProperty?

Implementation

• Would it be possible to somehow use JsonReader and JsonWriter?

Useful links

1. On new API:

• video: https://channel9.msdn.com/Shows/On-NET/Try-the-new-SystemTextJson-APIs
• blogpost: https://devblogs.microsoft.com/dotnet/try-the-new-system-text-json-apis/
• on performance: https://github.com/dotnet/corefx/issues/33115
• spans: https://msdn.microsoft.com/en-us/magazine/mt814808.aspx

2. On Json.NET and its advantages:

• XPath https://goessner.net/articles/JsonPath/
• LINQ https://www.newtonsoft.com/json/help/html/LINQtoJSON.htm
• XML https://www.newtonsoft.com/json/help/html/ConvertJsonToXml.htm

3. On Json:

• grammar: https://www.json.org/