From 8c420d826434d3a18ad5edb27cb4bcc9861f95b1 Mon Sep 17 00:00:00 2001
From: Yoh Deadfall <yoh.deadfall@hotmail.com>
Date: Sun, 23 Feb 2020 15:46:22 +0300
Subject: [PATCH] Added specification for field handling

---
 .../docs/FieldHandling_spec.md                | 72 +++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 src/libraries/System.Text.Json/docs/FieldHandling_spec.md

diff --git a/src/libraries/System.Text.Json/docs/FieldHandling_spec.md b/src/libraries/System.Text.Json/docs/FieldHandling_spec.md
new file mode 100644
index 00000000000000..fe8c0eb23103af
--- /dev/null
+++ b/src/libraries/System.Text.Json/docs/FieldHandling_spec.md
@@ -0,0 +1,72 @@
+# Table of contet
+
+- [Motivation](#motivation)
+- [Proposal](#proposal)
+  - [In depth](#in-depth)
+  - [Compatibility](#compatibility)
+- [Other implementations](#other-implementations)
+    - [Jil](#jil)
+    - [Utf8Json](#utf8json)
+    - [Newtonsoft.Json](#newtonsoftjson)
+    - [System.Runtime.Serialization.Json](#system-runtime-serialization-json)
+
+# Motivation
+
+Currently, there is no way to serialize and deserialize fields while they are an essetial part of type system which can be exposed to public like properties. While public properties are no recommended, they are used in .NET itself (see value tuples) and by users.
+
+The feature stated to be requested even before .NET Core 3.0 was released, but wasn't included into it due to a lack of time.
+
+# Proposal
+
+Originally proposed by Layomi Akinrinade.
+
+```csharp
+namespace System.Text.Json
+{
+    public partial class JsonSerializerOptions
+    {
+        public bool IncludeFields { get; set; } = false;
+    }
+}
+```
+
+## In depth
+
+By default the feature is turned off to prevent a leak for users which use `System.Text.Json` to serialize types with public fields because it could break contracts.
+
+When the feature is turned on fields goes to be serialized the same way as properties without any difference and no additional attributes, keeping `System.Text.Json` clean and tiny, but powerful tool.
+
+## Compatibility
+
+The proposed implementation is incompatible with other popular JSON serializers if opt-in strategy is used. Legacy `System.Runtime.Serialization.Json` suppoorts fields oout of the box too.
+
+```csharp
+public class ObjectWithFields
+{
+    public string Value = "Some value";
+}
+```
+
+### Jil
+
+```csharp
+var json = Jil.JSON.Serialize(new ObjectWithFields { Value = "Jil" });
+// {"Value":"Jil"}
+```
+
+### Utf8Json
+
+```csharp
+var json = Utf8Json.JsonSerializer.ToJsonString(new ObjectWithFields { Value = "Utf8Json" });
+// {"Value":"Utf8Json"}
+```
+
+### Newtonsoft.Json
+
+```csharp
+using var legacyJson = new MemoryStream();
+new System.Runtime.Serialization.Json.DataContractJsonSerializer(typeof(ObjectWithFields))
+    .WriteObject(legacyJson, new ObjectWithFields { Value = "System.Runtime.Serialization.Json" });
+var json = Encoding.UTF8.GetString(legacyJson.ToArray())
+// {"Value":"System.Runtime.Serialization.Json"}
+```