[Repo Assist] Add PreferDateTimeOffset parameter to CsvProvider, JsonProvider, and XmlProvider (#1668)

github-actions[bot] · Copilot · dsyme · web-flow · commit 49d4888af88c · 2026-02-26T15:17:26.000Z
* Add PreferDateTimeOffset parameter to CsvProvider, JsonProvider, XmlProvider Adds a new PreferDateTimeOffset static parameter (default: false) to CsvProvider, JsonProvider, and XmlProvider. When set to true, date-time values that would normally be inferred as DateTime are instead inferred as DateTimeOffset (using the local UTC offset). Values that already parse with an explicit timezone offset are already inferred as DateTimeOffset regardless of this parameter. This addresses the long-standing request in #1100 (configure default DateTimeKind for dates without timezone) and #1072 (control over timezone in CSV date writing). Closes #1100 Closes #1072 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: trigger CI checks * Add PreferDateTimeOffset documentation to CsvProvider, JsonProvider, XmlProvider, and TypeInference docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: trigger CI checks --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Don Syme <dsyme@users.noreply.github.com> Co-authored-by: Repo Assist <repo-assist@github.com>
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -2,6 +2,7 @@
 
 ## 8.1.0-beta
 
+- Add `PreferDateTimeOffset` parameter to `CsvProvider`, `JsonProvider`, and `XmlProvider`: when true, date-time values without an explicit timezone offset are inferred as `DateTimeOffset` (using local offset) instead of `DateTime` (closes #1100, #1072)
 - Make `Http.AppendQueryToUrl` public (closes #1325)
 - Add `PreferOptionals` parameter to `JsonProvider` and `XmlProvider` (defaults to `true` to match existing behavior; set to `false` to use empty string or `NaN` for missing values, like the CsvProvider default) (closes #649)
 
diff --git a/docs/library/CsvProvider.fsx b/docs/library/CsvProvider.fsx
@@ -90,8 +90,8 @@ let msft = Stocks.Load(__SOURCE_DIRECTORY__ + "/../data/MSFT.csv").Cache()
 
 // Look at the most recent row. Note the 'Date' property
 // is of type 'DateTime' by default. Set PreferDateOnly = true
-// to use 'DateOnly' on .NET 6+
-// and 'Open' has a type 'decimal'
+// to use 'DateOnly' on .NET 6+, or PreferDateTimeOffset = true
+// to use 'DateTimeOffset'. 'Open' has a type 'decimal'.
 let firstRow = msft.Rows |> Seq.head
 let lastDate = firstRow.Date
 let lastOpen = firstRow.Open
@@ -111,6 +111,7 @@ to the columns in the CSV file.
 As you can see, the type provider also infers types of individual rows. The `Date`
 property is inferred as `DateTime` by default. When you set `PreferDateOnly = true`
 on .NET 6 and later, date-only strings (without a time component) are inferred as `DateOnly`.
+Set `PreferDateTimeOffset = true` to infer date-time values as `DateTimeOffset`.
 HLOC prices are inferred as `decimal`.
 
 ## Using units of measure
@@ -276,6 +277,10 @@ On .NET 6 and later, when you set `PreferDateOnly = true`, columns whose values
 are inferred as `DateOnly`. Time-only strings are inferred as `TimeOnly`. If a column mixes `DateOnly` and `DateTime` values, it is unified to `DateTime`.
 By default (`PreferDateOnly = false`), all date values are inferred as `DateTime` for backward compatibility.
 
+Set `PreferDateTimeOffset = true` to infer all date-time columns (that would otherwise be `DateTime`) as `DateTimeOffset` instead.
+Values that already carry an explicit timezone offset (e.g. `2023-06-15T10:30:00+05:30`) are always inferred as `DateTimeOffset` regardless of this flag.
+`PreferDateTimeOffset` and `PreferDateOnly` are independent: `DateOnly` columns stay as `DateOnly` even when `PreferDateTimeOffset=true`.
+
 If a value is missing in any row, by default the CSV type provider will infer a nullable (for `int`, `int64`, and `DateOnly`) or an optional
 (for `bool`, `DateTime`, `DateTimeOffset`, and `Guid`). When a `decimal` would be inferred but there are missing values, we will infer a
 `float` instead, and use `Double.NaN` to represent those missing values. The `string` type is already inherently nullable,
@@ -403,6 +408,13 @@ You can also explicitly request a `DateOnly` or `TimeOnly` column using schema a
 In the example above, `EventDate` is explicitly annotated as `dateonly` and `Duration` is explicitly
 annotated as `timeonly?` (a nullable `TimeOnly`).
 
+### DateTimeOffset
+
+Set `PreferDateTimeOffset = true` to infer all date-time columns (that would otherwise be `DateTime`) as
+`DateTimeOffset` instead. This is useful when you need to preserve or work with timezone-aware values.
+Values that already carry an explicit timezone offset in the sample data (e.g. `2023-06-15T10:30:00+05:30`)
+are always inferred as `DateTimeOffset` regardless of this flag.
+
 ## Transforming CSV files
 
 In addition to reading, `CsvProvider` also has support for transforming the row collection of CSV files. The operations
diff --git a/docs/library/JsonProvider.fsx b/docs/library/JsonProvider.fsx
@@ -126,6 +126,10 @@ On .NET 6 and later, when you set `PreferDateOnly = true`, strings that represen
 are inferred as `DateOnly`, and time-only strings are inferred as `TimeOnly`. By default (`PreferDateOnly = false`),
 all dates are inferred as `DateTime` for backward compatibility.
 
+Set `PreferDateTimeOffset = true` to infer all date-time values (that would otherwise be `DateTime`) as `DateTimeOffset`.
+Values that already contain an explicit timezone offset (e.g. `"2023-06-15T10:30:00+05:30"`) are always inferred as
+`DateTimeOffset` regardless of this flag.
+
 ### Inferring record types
 
 Now let's look at a sample JSON document that contains a list of records. The
diff --git a/docs/library/TypeInference.fsx b/docs/library/TypeInference.fsx
@@ -83,14 +83,21 @@ The providers recognise date and time strings in standard ISO 8601 formats:
 | Inferred Type | When Used | Example Value |
 |---|---|---|
 | `DateTime` | Date + time strings (default) | `"2023-06-15T12:00:00"` |
-| `DateTimeOffset` | Date + time + timezone offset | `"2023-06-15T12:00:00+02:00"` |
+| `DateTimeOffset` | Date + time + timezone offset (always) | `"2023-06-15T12:00:00+02:00"` |
+| `DateTimeOffset` | Any date + time string when `PreferDateTimeOffset=true` | `"2023-06-15T12:00:00"` |
 | `DateOnly` (.NET 6+) | Date-only strings when `PreferDateOnly=true` | `"2023-06-15"` |
 | `TimeOnly` (.NET 6+) | Time-only strings when `PreferDateOnly=true` | `"12:00:00"` |
 
 By default (`PreferDateOnly = false`), date-only strings such as `"2023-06-15"` are
 inferred as `DateTime` for backward compatibility. Set `PreferDateOnly = true` on
 .NET 6 and later to infer them as `DateOnly` instead.
 
+Set `PreferDateTimeOffset = true` to infer all date-time values (that would otherwise be
+`DateTime`) as `DateTimeOffset` instead. Values that already carry an explicit timezone
+offset (e.g. `"2023-06-15T12:00:00+02:00"`) are always inferred as `DateTimeOffset`
+regardless of this flag. `PreferDateTimeOffset` and `PreferDateOnly` are independent:
+`DateOnly` values stay as `DateOnly` even when `PreferDateTimeOffset=true`.
+
 If a column mixes `DateOnly` and `DateTime` values, they are unified to `DateTime`.
 
 ## Missing Values and Optionals
@@ -270,6 +277,7 @@ The following static parameters let you override the default inference behaviour
 | `InferRows` | CSV | Number of rows to use for type inference (default 1000; 0 = all rows) |
 | `SampleIsList` | JSON, XML | Treat the top-level array as a list of sample objects, not a single sample |
 | `PreferDateOnly` | CSV, JSON, XML | Infer date-only strings as `DateOnly` on .NET 6+ (default `false`) |
+| `PreferDateTimeOffset` | CSV, JSON, XML | Infer all date-time values as `DateTimeOffset` instead of `DateTime` (default `false`) |
 | `InferenceMode` | JSON, XML | Enable inline schema annotations (`ValuesAndInlineSchemasHints` or `ValuesAndInlineSchemasOverrides`) |
 | `Schema` | CSV | Override column names and/or types directly |
 
diff --git a/docs/library/XmlProvider.fsx b/docs/library/XmlProvider.fsx
@@ -330,6 +330,20 @@ attributes in our sample, so it is inferred as `string`), and then it recursivel
 the content of all `<div>` elements. If the element does not contain nested elements,
 then we print the `Value` (inner text).
 
+## Inferring date types
+
+Element and attribute values that look like dates are inferred as `DateTime` or `DateTimeOffset`.
+Values that already carry an explicit timezone offset (e.g. `"2023-06-15T12:00:00+02:00"`) are always
+inferred as `DateTimeOffset`.
+
+On .NET 6 and later, when you set `PreferDateOnly = true`, values that represent a date without a time
+component (e.g. `"2023-01-15"`) are inferred as `DateOnly`, and time-only values as `TimeOnly`.
+By default (`PreferDateOnly = false`), all date values are inferred as `DateTime` for backward compatibility.
+
+Set `PreferDateTimeOffset = true` to infer all date-time values (that would otherwise be `DateTime`) as
+`DateTimeOffset`. This is useful when you need timezone-aware values. `PreferDateTimeOffset` and
+`PreferDateOnly` are independent: `DateOnly` values stay as `DateOnly` even when `PreferDateTimeOffset=true`.
+
 ## Loading Directly from a File or URL
 
 In many cases, we might want to define schema using a local sample file, but then directly
diff --git a/src/FSharp.Data.DesignTime/Csv/CsvProvider.fs b/src/FSharp.Data.DesignTime/Csv/CsvProvider.fs
@@ -59,6 +59,7 @@ type public CsvProvider(cfg: TypeProviderConfig) as this =
         let strictBooleans = args.[17] :?> bool
         let useOriginalNames = args.[18] :?> bool
         let preferFloats = args.[19] :?> bool
+        let preferDateTimeOffset = args.[20] :?> bool
 
         // This provider already has a schema mechanism, so let's disable inline schemas.
         let inferenceMode = InferenceMode'.ValuesOnly
@@ -120,15 +121,22 @@ type public CsvProvider(cfg: TypeProviderConfig) as this =
                         strictBooleans,
                         preferFloats
                     )
+
+                let fields =
 #if NET6_0_OR_GREATER
-                if preferDateOnly && ProviderHelpers.runtimeSupportsNet6Types cfg.RuntimeAssembly then
-                    fields
-                else
-                    fields |> List.map StructuralInference.downgradeNet6PrimitiveProperty
+                    if preferDateOnly && ProviderHelpers.runtimeSupportsNet6Types cfg.RuntimeAssembly then
+                        fields
+                    else
+                        fields |> List.map StructuralInference.downgradeNet6PrimitiveProperty
 #else
-                fields
+                    fields
 #endif
 
+                if preferDateTimeOffset then
+                    fields |> List.map StructuralInference.upgradeToDateTimeOffsetPrimitiveProperty
+                else
+                    fields
+
             use _holder = IO.logTime "TypeGeneration" sample
 
             let csvType, csvErasedType, rowType, stringArrayToRow, rowToStringArray =
@@ -244,7 +252,8 @@ type public CsvProvider(cfg: TypeProviderConfig) as this =
           ProvidedStaticParameter("PreferDateOnly", typeof<bool>, parameterDefaultValue = false)
           ProvidedStaticParameter("StrictBooleans", typeof<bool>, parameterDefaultValue = false)
           ProvidedStaticParameter("UseOriginalNames", typeof<bool>, parameterDefaultValue = false)
-          ProvidedStaticParameter("PreferFloats", typeof<bool>, parameterDefaultValue = false) ]
+          ProvidedStaticParameter("PreferFloats", typeof<bool>, parameterDefaultValue = false)
+          ProvidedStaticParameter("PreferDateTimeOffset", typeof<bool>, parameterDefaultValue = false) ]
 
     let helpText =
         """<summary>Typed representation of a CSV file.</summary>
@@ -270,7 +279,8 @@ type public CsvProvider(cfg: TypeProviderConfig) as this =
               (e.g. 'MyCompany.MyAssembly, resource_name.csv'). This is useful when exposing types generated by the type provider.</param>
            <param name='PreferDateOnly'>When true on .NET 6+, date-only strings are inferred as DateOnly and time-only strings as TimeOnly. Defaults to false for backward compatibility.</param>
            <param name='StrictBooleans'>When true, only <c>true</c> and <c>false</c> (case-insensitive) are inferred as boolean. Values such as <c>0</c>, <c>1</c>, <c>yes</c>, and <c>no</c> are treated as integers or strings respectively. Defaults to false.</param>
-           <param name='UseOriginalNames'>When true, CSV column header names are used as-is for generated property names instead of being normalized (e.g. capitalizing the first letter). Defaults to false.</param>"""
+           <param name='UseOriginalNames'>When true, CSV column header names are used as-is for generated property names instead of being normalized (e.g. capitalizing the first letter). Defaults to false.</param>
+           <param name='PreferDateTimeOffset'>When true, date-time strings without an explicit timezone offset are inferred as DateTimeOffset (using the local offset) instead of DateTime. Defaults to false.</param>"""
 
     do csvProvTy.AddXmlDoc helpText
     do csvProvTy.DefineStaticParameters(parameters, buildTypes)
diff --git a/src/FSharp.Data.DesignTime/Json/JsonProvider.fs b/src/FSharp.Data.DesignTime/Json/JsonProvider.fs
@@ -61,6 +61,7 @@ type public JsonProvider(cfg: TypeProviderConfig) as this =
         let useOriginalNames = args.[12] :?> bool
         let omitNullFields = args.[13] :?> bool
         let preferOptionals = args.[14] :?> bool
+        let preferDateTimeOffset = args.[15] :?> bool
 
         let inferenceMode =
             InferenceMode'.FromPublicApi(inferenceMode, inferTypesFromValues)
@@ -109,15 +110,22 @@ type public JsonProvider(cfg: TypeProviderConfig) as this =
                                 ""
                                 sampleJson)
                         |> Array.fold (StructuralInference.subtypeInfered (not preferOptionals)) InferedType.Top
+
+                let rawInfered =
 #if NET6_0_OR_GREATER
-                if preferDateOnly && ProviderHelpers.runtimeSupportsNet6Types cfg.RuntimeAssembly then
-                    rawInfered
-                else
-                    StructuralInference.downgradeNet6Types rawInfered
+                    if preferDateOnly && ProviderHelpers.runtimeSupportsNet6Types cfg.RuntimeAssembly then
+                        rawInfered
+                    else
+                        StructuralInference.downgradeNet6Types rawInfered
 #else
-                rawInfered
+                    rawInfered
 #endif
 
+                if preferDateTimeOffset then
+                    StructuralInference.upgradeToDateTimeOffset rawInfered
+                else
+                    rawInfered
+
             use _holder = IO.logTime "TypeGeneration" (if schema <> "" then schema else sample)
 
             let ctx =
@@ -178,7 +186,8 @@ type public JsonProvider(cfg: TypeProviderConfig) as this =
           ProvidedStaticParameter("PreferDateOnly", typeof<bool>, parameterDefaultValue = false)
           ProvidedStaticParameter("UseOriginalNames", typeof<bool>, parameterDefaultValue = false)
           ProvidedStaticParameter("OmitNullFields", typeof<bool>, parameterDefaultValue = false)
-          ProvidedStaticParameter("PreferOptionals", typeof<bool>, parameterDefaultValue = true) ]
+          ProvidedStaticParameter("PreferOptionals", typeof<bool>, parameterDefaultValue = true)
+          ProvidedStaticParameter("PreferDateTimeOffset", typeof<bool>, parameterDefaultValue = false) ]
 
     let helpText =
         """<summary>Typed representation of a JSON document.</summary>
@@ -205,7 +214,8 @@ type public JsonProvider(cfg: TypeProviderConfig) as this =
            <param name='PreferDateOnly'>When true on .NET 6+, date-only strings (e.g. "2023-01-15") are inferred as DateOnly and time-only strings as TimeOnly. Defaults to false for backward compatibility.</param>
            <param name='UseOriginalNames'>When true, JSON property names are used as-is for generated property names instead of being normalized to PascalCase. Defaults to false.</param>
            <param name='OmitNullFields'>When true, optional fields with value None are omitted from the generated JSON rather than serialized as null. Defaults to false.</param>
-           <param name='PreferOptionals'>When set to true (default), inference will use the option type for missing or null values. When false, inference will prefer to use empty string or double.NaN for missing values where possible, matching the default CsvProvider behavior.</param>"""
+           <param name='PreferOptionals'>When set to true (default), inference will use the option type for missing or null values. When false, inference will prefer to use empty string or double.NaN for missing values where possible, matching the default CsvProvider behavior.</param>
+           <param name='PreferDateTimeOffset'>When true, date-time strings without an explicit timezone offset are inferred as DateTimeOffset (using the local offset) instead of DateTime. Defaults to false.</param>"""
 
     do jsonProvTy.AddXmlDoc helpText
     do jsonProvTy.DefineStaticParameters(parameters, buildTypes)
diff --git a/src/FSharp.Data.DesignTime/Xml/XmlProvider.fs b/src/FSharp.Data.DesignTime/Xml/XmlProvider.fs
@@ -54,6 +54,7 @@ type public XmlProvider(cfg: TypeProviderConfig) as this =
         let dtdProcessing = args.[11] :?> string
         let useOriginalNames = args.[12] :?> bool
         let preferOptionals = args.[13] :?> bool
+        let preferDateTimeOffset = args.[14] :?> bool
 
         let inferenceMode =
             InferenceMode'.FromPublicApi(inferenceMode, inferTypesFromValues)
@@ -80,15 +81,22 @@ type public XmlProvider(cfg: TypeProviderConfig) as this =
 
                     let t =
                         schemaSet |> XsdParsing.getElements |> List.ofSeq |> XsdInference.inferElements
+
+                    let t =
 #if NET6_0_OR_GREATER
-                    if preferDateOnly && ProviderHelpers.runtimeSupportsNet6Types cfg.RuntimeAssembly then
-                        t
-                    else
-                        StructuralInference.downgradeNet6Types t
+                        if preferDateOnly && ProviderHelpers.runtimeSupportsNet6Types cfg.RuntimeAssembly then
+                            t
+                        else
+                            StructuralInference.downgradeNet6Types t
 #else
-                    t
+                        t
 #endif
 
+                    if preferDateTimeOffset then
+                        StructuralInference.upgradeToDateTimeOffset t
+                    else
+                        t
+
                 use _holder = IO.logTime "TypeGeneration" sample
 
                 let ctx =
@@ -137,15 +145,22 @@ type public XmlProvider(cfg: TypeProviderConfig) as this =
                             (not preferOptionals)
                             globalInference
                         |> Array.fold (StructuralInference.subtypeInfered (not preferOptionals)) InferedType.Top
+
+                    let t =
 #if NET6_0_OR_GREATER
-                    if preferDateOnly && ProviderHelpers.runtimeSupportsNet6Types cfg.RuntimeAssembly then
-                        t
-                    else
-                        StructuralInference.downgradeNet6Types t
+                        if preferDateOnly && ProviderHelpers.runtimeSupportsNet6Types cfg.RuntimeAssembly then
+                            t
+                        else
+                            StructuralInference.downgradeNet6Types t
 #else
-                    t
+                        t
 #endif
 
+                    if preferDateTimeOffset then
+                        StructuralInference.upgradeToDateTimeOffset t
+                    else
+                        t
+
                 use _holder = IO.logTime "TypeGeneration" sample
 
                 let ctx =
@@ -205,7 +220,8 @@ type public XmlProvider(cfg: TypeProviderConfig) as this =
           ProvidedStaticParameter("PreferDateOnly", typeof<bool>, parameterDefaultValue = false)
           ProvidedStaticParameter("DtdProcessing", typeof<string>, parameterDefaultValue = "Ignore")
           ProvidedStaticParameter("UseOriginalNames", typeof<bool>, parameterDefaultValue = false)
-          ProvidedStaticParameter("PreferOptionals", typeof<bool>, parameterDefaultValue = true) ]
+          ProvidedStaticParameter("PreferOptionals", typeof<bool>, parameterDefaultValue = true)
+          ProvidedStaticParameter("PreferDateTimeOffset", typeof<bool>, parameterDefaultValue = false) ]
 
     let helpText =
         """<summary>Typed representation of a XML file.</summary>
@@ -232,7 +248,8 @@ type public XmlProvider(cfg: TypeProviderConfig) as this =
            <param name='PreferDateOnly'>When true on .NET 6+, date-only strings are inferred as DateOnly and time-only strings as TimeOnly. Defaults to false for backward compatibility.</param>
            <param name='DtdProcessing'>Controls how DTD declarations in the XML are handled. Accepted values: "Ignore" (default, silently skips DTD processing, safe for most cases), "Prohibit" (throws on any DTD declaration), "Parse" (enables full DTD processing including entity expansion, use with caution).</param>
            <param name='UseOriginalNames'>When true, XML element and attribute names are used as-is for generated property names instead of being normalized to PascalCase. Defaults to false.</param>
-           <param name='PreferOptionals'>When set to true (default), inference will use the option type for missing or absent values. When false, inference will prefer to use empty string or double.NaN for missing values where possible, matching the default CsvProvider behavior.</param>"""
+           <param name='PreferOptionals'>When set to true (default), inference will use the option type for missing or absent values. When false, inference will prefer to use empty string or double.NaN for missing values where possible, matching the default CsvProvider behavior.</param>
+           <param name='PreferDateTimeOffset'>When true, date-time strings without an explicit timezone offset are inferred as DateTimeOffset (using the local offset) instead of DateTime. Defaults to false.</param>"""
 
 
     do xmlProvTy.AddXmlDoc helpText
diff --git a/src/FSharp.Data.Runtime.Utilities/StructuralInference.fs b/src/FSharp.Data.Runtime.Utilities/StructuralInference.fs
diff --git a/tests/FSharp.Data.DesignTime.Tests/TypeProviderInstantiation.fs b/tests/FSharp.Data.DesignTime.Tests/TypeProviderInstantiation.fs
