FSharp.SystemTextJson

• #151: Add optional argument deserializeNullAsNone: bool to option .WithSkippableOptionFields(SkippableOptionFields). When true, skippable option fields can be deserialized as None not only from a missing field, but also from null.

Fix #172: NullReferenceException when serializing a null record.

• #154: Add SkippableOptionFields enum to further customize the skipping of fields of type option and voption with WithSkippableOptionFields.

  • SkippableOptionFields.FromJsonSerializerOptions is the default and equivalent to WithSkippableOptionFields(false): fields of type option and voption are skipped if used with JsonIgnoreCondition.WhenWritingNull.
  • SkippableOptionFields.Always is equivalent to WithSkippableOptionFields(true): fields of type option and voption are always skipped.
  • SkippableOptionFields.Never: fields of type option and voption are never skipped.

• #159: Throw an exception when trying to deserialize null into a record or union in any context, rather than only when they are in fields of records and unions.

• #160: Fix WithSkippableOptionFields(false) not working for voption.

• #161: Allow using single-case unions as keys in all dictionary types.
  NOTE: This requires System.Text.Json 8.0.

• #162: Add option .WithMapFormat(MapFormat) to customize the format of F# maps.

  • MapFormat.Object always serializes maps as objects. The key type must be supported as key for dictionaries.
    NOTE: This requires System.Text.Json 8.0.
  • MapFormat.ArrayOfPairs always serializes maps as JSON arrays whose items are [key,value] pairs.
  • MapFormat.ObjectOrArrayOfPairs is the default: maps whose keys are string or single-case unions wrapping string are serialized as JSON objects, and other maps are serialized as JSON arrays whose items are [key,value] pairs.

• #163: Add StructuralComparison to the type Skippable<_>.

• #164: When deserializing a record with JsonIgnoreCondition.WhenWritingNull, when a non-nullable field is missing, throw a proper JsonException rather than a NullReferenceException.

• #141: Add fluent options builder. JsonFSharpOptions has the following new methods:

  • static methods that create options with default settings: .Default(), .NewtonsoftLike(), .FSharpLuLike() and .ThothLike().
  • instance methods .WithOptionAbc(?bool) for each flag JsonUnionEncoding.Abc, that sets or unsets this option and returns a new JsonFSharpOptions.
  • instance methods .WithAbc(value) for each optional argument abc of its constructor, that sets this option and returns a new JsonFSharpOptions.
  • an instance method .ToJsonSerializerOptions() that returns a new JsonSerializerOptions with the corresponding JsonFSharpConverter configured.
  • an instance method .AddToJsonSerializerOptions(options) that takes an existing JsonSerializerOptions, configures the corresponding JsonFSharpConverter and returns unit.

  The above is now the recommended way of configuring the library, and future options may be only made available using fluent methods and not using constructor arguments.

• #146: Add option .WithSkippableOptionFields(?bool) that makes fields of type option and voption behave like Skippable: None / ValueNone is represented by a missing field instead of a null value.

  This is equivalent to the pre-1.0 default behavior, and is now recommended if this behavior is desired instead of IgnoreNullValues = true or DefaultIgnoreCondition = WhenWritingNull.

• Fix regression #137: exception on serialization and deserialization of empty anonymous records.

Fix regression #133: failure on non-public records.

• #89: Add JsonNameAttribute as a more powerful substitute for the standard JsonPropertyNameAttribute.

  • When used on a discriminated union case, JsonNameAttribute can take a value of type int or bool instead of string.
  • JsonNameAttribute can take multiple values. When deserializing, all these values are treated as equivalent. When serializing, the first one is used.
  • JsonNameAttribute has a settable property Field: string. It is used to set the JSON name of a union case field with the given name.

• #92: Serialization of record properties (in addition to fields).

  • Add option includeRecordProperties: bool to enable serializing record properties.
  • Also serialize record properties with JsonIncludeAttribute even when includeRecordProperties is false.

• Add support for the standard DefaultIgnoreCondition.WhenWritingNull as a synonym for IgnoreNullValues = true that allows None and ValueNone to be omitted instead of null.

• #123: BREAKING CHANGE: Missing fields of type option or voption now throw an error by default instead of being deserialized to None / ValueNone. To support missing fields, either enable the option IgnoreNullValues = true or DefaultIgnoreCondition = WhenWritingNull, or use the type Skippable instead of option or voption.

• #126: Add option types: JsonFSharpTypes that specifies which types the F# converter should handle. Unlisted types will be handled by the default System.Text.Json. By default, all supported types are handled.

• #111: Support JsonKnownNamingPolicy in JsonFSharpConverterAttribute.

• #112: Add Options and Overrides properties to JsonFSharpConverter.

• #263: Add a nullary constructor for JsonFSharpConverter.

• #98: Implement JsonPropertyOrderAttribute on records.

• #108: Allow serializing unnamed union fields using their type name, instead of Item1 etc, using JsonUnionEncoding.UnionFieldNamesFromTypes.

• #100: Allow unionTagName to be part of the record type definition when deserializing union of records.

• #109: Add .xml with documentation comments to nupkg. Thanks @exyi!

• #110: Allow customizing the naming policy for union fields with unionFieldNamingPolicy.
  If not provided, use JsonSerializerOptions.PropertyNamingPolicy as before.

• #87: Fix null checking on value type fields.

• #93: Allow deserializing F# unions in AdjacentTag and InternalTag modes where the tag is not the first field in the JSON object.
  This capability is enabled by new option JsonUnionEncoding.AllowUnorderedTag, which is included in JsonUnionEncoding.Default and all JsonUnionEncoding.*Like combined formats.

• #83: Fix null reference exception when deserializing a record that Skips a field with FSharp.Core 5.0.
• Remove netcoreapp3.0 specific build.

• #77: Fix compile-time error when publishing a trimmed .NET 5 application. Thanks @pchalamet!

• #71: Allow overriding specific types in JsonFSharpConverter with new argument overrides. These override even types that have JsonFSharpConverterAttribute when allowOverride = true.

• #69: Allow overriding JsonFSharpConverter options with JsonFSharpConverterAttribute by passing allowOverride = true to JsonFSharpConverter.
• Add JsonUnionEncoding.Inherit. When this flag is set on a JsonFSharpConverterAttribute that overrides a JsonFSharpConverter, this type still uses the JsonFSharpConverter's JsonUnionEncoding.

• #56: Add JsonUnionEncoding.UnwrapRecordCases, which implies JsonUnionEncoding.NamedFields and encodes union cases containing a single record field as if the record's fields were the union's fields instead. For example:

  type U =
      | U of r: {| x: int; y: bool |}
  
  U {| x = 1; y = true |}
  // Serialized as: {"Case":"U","Fields":{"x":1,"y":true}}
  // Instead of:    {"Case":"U","Fields":{"r":{"x":1,"y":true}}}
  

  This option is compatible with all union formats (AdjacentTag, ExternalTag, InternalTag and Untagged).
• #64: Fix serialization of unit as field of an F# type. Thanks @NickDarvey!

• #54: Do throw an exception when a mandatory field is missing and an optional field was omitted. Thanks @fuchen!

• #57: Do throw an exception when a parsed value is null inside an array, a set or a tuple, unless allowNullFields is true. Thanks @drhumlen!

• #47: Add Skippable<'T> to represent values that can be omitted from the serialization of a record or a union with NamedFields. This is particularly useful with Skippable<'T option> (or voption) to represent a field that can be omitted, null, or have a proper value.

  type R = { x: Skippable<int option> }
  
  { x = Skip }              // Serialized as: {}
  { x = Include None }      // Serialized as: {"x":null}
  { x = Include (Some 42) } // Serialized as: {"x":42}
  

  Also add a Skippable module with standard functions: map, filter, etc. Implementation largely based on @cmeeren's JsonSkippable which provides the same functionality for Newtonsoft.Json.
• #51: When the type K is a single-case union wrapping a string, serialize Map<K, V> into a JSON object, like Map<string, V>.
• Allow OR-ing a base JsonUnionEncoding (AdjacentTag, InternalTag, ExternalTag or Untagged) with Default to use the default extra options (UnwrapOption ||| UnwrapSingleCaseUnions).

• #43: In deserialization, allow omitting fields that are optional.
• In deserialization, when a field is missing, find which one it is and name it in the error message.

• #30: Unwrap 'T voption with JsonUnionEncoding.UnwrapOption. Thanks @johlrich!

• #32: Add JsonUnionEncoding.UnwrapSingleFieldCases, which encodes the field of single-field cases as x instead of [x]. Include it in JsonUnionEncoding.FSharpLuLike.

• #33: Fix "read too much or not enough" when parsing a list of unions with JsonUnionEncoding.UnwrapFieldlessTags.

• #36: BREAKING CHANGE: During deserialization, throw an exception when a field of a record or union has value null, unless the type of this field is option, voption, or a union with UseNullAsTrueValue. Thanks @drhumlen!

  New option allowNullFields disables this behavior.

• #38: Add more consistent names for options:

  • BareFieldlessTags becomes UnwrapFieldlessTags;
  • SuccintOption becomes UnwrapOption;
  • EraseSingleCaseUnions becomes UnwrapSingleCaseUnions.

  The previous names are marked Obsolete.

• #3: Add support for PropertyNamingPolicy on record and union fields.
• #22: Add support for DictionaryKeyPolicy for Map<string, 'T>.
• #27: Add unionTagNamingPolicy option to JsonFSharpConverter and JsonFSharpConverterAttribute to customize the naming policy for union tag names.
• #26: Add JsonUnionEncoding.EraseSingleCaseUnions, which encodes single-case single-field unions the same as the value in the field.
  BREAKING CHANGE: This is now the default option.
• #5: Add support for PropertyNameCaseInsensitive on record and union fields.
  Add unionTagCaseInsensitive option to JsonFSharpConverter and JsonFSharpConverterAttribute to customize the case sensitivity for union tag names.