Schema.org Release v7 (#136)

* PronounceableText support

* Schema v6 entity updates

* Update to schema.org release v7

* Added Values7 type

* Added tests for Values7

* Only support DateTimeOffset conversion if it looks like it has an offset

ISO 8601 defines the offset as numbers after a "+" as the offset or after a "Z" meaning UTC0. Without this change, the timezone offset of the current machine is used which is (in many cases) undesired.

* Adding better support for time offsets in dates

* Fixed bug in time offset handling via substrings

Author: Turnerj

Source/Schema.NET/DateTimeHelper.cs

@@ -0,0 +1,116 @@
+namespace Schema.NET
+{
+    using System;
+
+    /// <summary>
+    /// Helper for parsing strings into <see cref="DateTime"/> or <see cref="DateTimeOffset"/>
+    /// </summary>
+    internal static class DateTimeHelper
+    {
+        private const string MSDateStringStart = "/Date(";
+        private const string MSDateStringEnd = ")/";
+        private const string NegativeOffset = "-";
+        private static readonly DateTime EpochDate = new DateTime(1970, 1, 1);
+        private static readonly char[] OffsetChars = new[] { '+', '-' };
+
+        /// <summary>
+        /// Whether a given ISO 8601 date string has an offset defined (eg. "+", "-", "Z")
+        /// </summary>
+        /// <param name="input">The input string</param>
+        /// <returns>True if the input string has an offset defined</returns>
+        public static bool ContainsTimeOffset(string input)
+        {
+            if (input.IndexOf("+", StringComparison.Ordinal) != -1 || input.IndexOf("Z", StringComparison.Ordinal) != -1)
+            {
+                return true;
+            }
+
+            var timeSeparatorIndex = input.IndexOf("T", StringComparison.Ordinal);
+            if (timeSeparatorIndex != -1)
+            {
+                return input.IndexOf(NegativeOffset, timeSeparatorIndex, StringComparison.Ordinal) != -1;
+            }
+
+            return false;
+        }
+
+        /// <summary>
+        /// Parse MS DateTime as Date eg. "/Date(946730040000)/"
+        /// </summary>
+        /// <param name="input">The input string</param>
+        /// <param name="result">The result date and time</param>
+        /// <returns>True if the input string was able to be parsed into a <see cref="DateTime"/></returns>
+        public static bool TryParseMSDateTime(string input, out DateTime result)
+        {
+            if (input.StartsWith(MSDateStringStart, StringComparison.Ordinal) && input.EndsWith(MSDateStringEnd, StringComparison.Ordinal))
+            {
+                var dateTimeStartIndex = MSDateStringStart.Length;
+                var dateTimeLength = input.IndexOf(MSDateStringEnd, StringComparison.Ordinal) - dateTimeStartIndex;
+
+#if NETCOREAPP3_1
+                var timeValue = input.AsSpan().Slice(dateTimeStartIndex, dateTimeLength);
+#else
+                var timeValue = input.Substring(dateTimeStartIndex, dateTimeLength);
+#endif
+
+                if (double.TryParse(timeValue, out var milliseconds))
+                {
+                    result = EpochDate.AddMilliseconds(milliseconds);
+                    return true;
+                }
+            }
+
+            result = DateTime.MinValue;
+            return false;
+        }
+
+        /// <summary>
+        /// Parse MS DateTime as <see cref="DateTimeOffset"/> eg. "/Date(946730040000-0100)/"
+        /// </summary>
+        /// <param name="input">The input string</param>
+        /// <param name="result">The result date and time with offset</param>
+        /// <returns>True if the input string was able to be parsed into a <see cref="DateTimeOffset"/></returns>
+        public static bool TryParseMSDateTimeOffset(string input, out DateTimeOffset result)
+        {
+            if (input.StartsWith(MSDateStringStart, StringComparison.Ordinal) && input.EndsWith(MSDateStringEnd, StringComparison.Ordinal))
+            {
+                var dateTimeStartIndex = MSDateStringStart.Length;
+                var offsetIndex = input.IndexOfAny(OffsetChars);
+                var dateTimeLength = offsetIndex - dateTimeStartIndex;
+                var offsetLength = input.IndexOf(MSDateStringEnd, offsetIndex, StringComparison.Ordinal) - offsetIndex;
+
+#if NETCOREAPP3_1
+                var timeValue = input.AsSpan().Slice(dateTimeStartIndex, dateTimeLength);
+                var offsetType = input.AsSpan().Slice(offsetIndex, 1);
+                var offsetValue = input.AsSpan().Slice(offsetIndex + 1, offsetLength - 1);
+#else
+                var timeValue = input.Substring(dateTimeStartIndex, dateTimeLength);
+                var offsetType = input.Substring(offsetIndex, 1);
+                var offsetValue = input.Substring(offsetIndex + 1, offsetLength - 1);
+#endif
+
+                if (double.TryParse(timeValue, out var milliseconds))
+                {
+                    if (int.TryParse(offsetValue, out var offset))
+                    {
+                        var dateTime = EpochDate.AddMilliseconds(milliseconds);
+                        var hours = offset / 100;
+                        var minutes = offset - (hours * 100);
+                        var offsetTimeSpan = new TimeSpan(hours, minutes, 0);
+
+                        if (offsetType[0] == NegativeOffset[0])
+                        {
+                            offsetTimeSpan = -offsetTimeSpan;
+                        }
+
+                        result = new DateTimeOffset(dateTime, offsetTimeSpan);
+                        return true;
+                    }
+                }
+            }
+
+            result = DateTimeOffset.MinValue;
+            return false;
+        }
+    }
+}

Source/Schema.NET/Schema.NET.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup Label="Build">
-    <TargetFrameworks>netstandard1.1;netstandard2.0;net461;net472</TargetFrameworks>
+    <TargetFrameworks>netstandard1.1;netstandard2.0;net461;net472;netcoreapp3.1</TargetFrameworks>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <LangVersion>latest</LangVersion>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>

Source/Schema.NET/SchemaSerializer.cs

@@ -0,0 +1,99 @@
+namespace Schema.NET
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Text;
+    using Newtonsoft.Json;
+    using Newtonsoft.Json.Converters;
+
+    /// <summary>
+    /// Schema JSON Serializer
+    /// </summary>
+    public static class SchemaSerializer
+    {
+        private const string ContextPropertyJson = "\"@context\":\"https://schema.org\",";
+
+        /// <summary>
+        /// Default serializer settings used when deserializing
+        /// </summary>
+        private static readonly JsonSerializerSettings DeserializeSettings = new JsonSerializerSettings
+        {
+            DateParseHandling = DateParseHandling.None,
+        };
+
+        /// <summary>
+        /// Default serializer settings used when HTML escaping is not required.
+        /// </summary>
+        private static readonly JsonSerializerSettings DefaultSerializationSettings = new JsonSerializerSettings()
+        {
+            Converters = new List<JsonConverter>()
+            {
+                new StringEnumConverter(),
+            },
+            DefaultValueHandling = DefaultValueHandling.Ignore,
+            NullValueHandling = NullValueHandling.Ignore,
+        };
+
+        /// <summary>
+        /// Serializer settings used when trying to avoid XSS vulnerabilities where user-supplied data is used
+        /// and the output of the serialization is embedded into a web page raw.
+        /// </summary>
+        private static readonly JsonSerializerSettings HtmlEscapedSerializationSettings = new JsonSerializerSettings()
+        {
+            Converters = new List<JsonConverter>()
+            {
+                new StringEnumConverter(),
+            },
+            DefaultValueHandling = DefaultValueHandling.Ignore,
+            NullValueHandling = NullValueHandling.Ignore,
+            StringEscapeHandling = StringEscapeHandling.EscapeHtml,
+        };
+
+        /// <summary>
+        /// Deserializes the JSON to the specified type.
+        /// </summary>
+        /// <typeparam name="T">Deserialization target type</typeparam>
+        /// <param name="value">JSON to deserialize</param>
+        /// <returns>An instance of <typeparamref name="T"/> deserialized from JSON</returns>
+        public static T DeserializeObject<T>(string value)
+            => JsonConvert.DeserializeObject<T>(value, DeserializeSettings);
+
+        /// <summary>
+        /// Serializes the value to JSON with default serialization settings.
+        /// </summary>
+        /// <param name="value">Serialization target value</param>
+        /// <returns>The serialized JSON string</returns>
+        public static string SerializeObject(object value)
+            => SerializeObject(value, DefaultSerializationSettings);
+
+        /// <summary>
+        /// Serializes the value to JSON with HTML escaping serialization settings.
+        /// </summary>
+        /// <param name="value">Serialization target value</param>
+        /// <returns>The serialized JSON string</returns>
+        public static string HtmlEscapedSerializeObject(object value)
+            => SerializeObject(value, HtmlEscapedSerializationSettings);
+
+        /// <summary>
+        /// Serializes the value to JSON with custom serialization settings.
+        /// </summary>
+        /// <param name="value">Serialization target value</param>
+        /// <param name="jsonSerializerSettings">JSON serialization settings</param>
+        /// <returns>The serialized JSON string</returns>
+        public static string SerializeObject(object value, JsonSerializerSettings jsonSerializerSettings)
+            => RemoveAllButFirstContext(JsonConvert.SerializeObject(value, jsonSerializerSettings));
+
+        private static string RemoveAllButFirstContext(string json)
+        {
+            if (json.IndexOf(ContextPropertyJson, StringComparison.Ordinal) != -1)
+            {
+                var stringBuilder = new StringBuilder(json);
+                var startIndex = ContextPropertyJson.Length + 1; // We add the one to represent the opening curly brace.
+                stringBuilder.Replace(ContextPropertyJson, string.Empty, startIndex, stringBuilder.Length - startIndex);
+                return stringBuilder.ToString();
+            }
+
+            return json;
+        }
+    }
+}

Source/Schema.NET/Thing.Partial.cs

@@ -1,52 +1,19 @@
 namespace Schema.NET
 {
-    using System.Collections.Generic;
-    using System.Text;
     using Newtonsoft.Json;
-    using Newtonsoft.Json.Converters;
 
     /// <summary>
     /// The most generic type of item.
     /// </summary>
     public partial class Thing : JsonLdObject
     {
-        private const string ContextPropertyJson = "\"@context\":\"https://schema.org\",";
-
-        /// <summary>
-        /// Default serializer settings used.
-        /// </summary>
-        private static readonly JsonSerializerSettings SerializerSettings = new JsonSerializerSettings()
-        {
-            Converters = new List<JsonConverter>()
-            {
-                new StringEnumConverter(),
-            },
-            DefaultValueHandling = DefaultValueHandling.Ignore,
-            NullValueHandling = NullValueHandling.Ignore,
-        };
-
-        /// <summary>
-        /// Serializer settings used when trying to avoid XSS vulnerabilities where user-supplied data is used
-        /// and the output of the serialization is embedded into a web page raw.
-        /// </summary>
-        private static readonly JsonSerializerSettings HtmlEscapedSerializerSettings = new JsonSerializerSettings()
-        {
-            Converters = new List<JsonConverter>()
-            {
-                new StringEnumConverter(),
-            },
-            DefaultValueHandling = DefaultValueHandling.Ignore,
-            NullValueHandling = NullValueHandling.Ignore,
-            StringEscapeHandling = StringEscapeHandling.EscapeHtml,
-        };
-
         /// <summary>
         /// Returns the JSON-LD representation of this instance.
         /// </summary>
         /// <returns>
         /// A <see cref="string" /> that represents the JSON-LD representation of this instance.
         /// </returns>
-        public override string ToString() => this.ToString(SerializerSettings);
+        public override string ToString() => SchemaSerializer.SerializeObject(this);
 
         /// <summary>
         /// Returns the JSON-LD representation of this instance.
@@ -58,7 +25,7 @@ public partial class Thing : JsonLdObject
         /// <returns>
         /// A <see cref="string" /> that represents the JSON-LD representation of this instance.
         /// </returns>
-        public string ToHtmlEscapedString() => this.ToString(HtmlEscapedSerializerSettings);
+        public string ToHtmlEscapedString() => SchemaSerializer.HtmlEscapedSerializeObject(this);
 
         /// <summary>
         /// Returns the JSON-LD representation of this instance using the <see cref="JsonSerializerSettings"/> provided.
@@ -73,14 +40,6 @@ public partial class Thing : JsonLdObject
         /// A <see cref="string" /> that represents the JSON-LD representation of this instance.
         /// </returns>
         public string ToString(JsonSerializerSettings serializerSettings) =>
-            RemoveAllButFirstContext(JsonConvert.SerializeObject(this, serializerSettings));
-
-        private static string RemoveAllButFirstContext(string json)
-        {
-            var stringBuilder = new StringBuilder(json);
-            var startIndex = ContextPropertyJson.Length + 1; // We add the one to represent the opening curly brace.
-            stringBuilder.Replace(ContextPropertyJson, string.Empty, startIndex, stringBuilder.Length - startIndex);
-            return stringBuilder.ToString();
-        }
+            SchemaSerializer.SerializeObject(this, serializerSettings);
     }
 }

Source/Schema.NET/ValuesJsonConverter.cs

@@ -318,13 +318,29 @@ private static bool TryProcessTokenAsType(JsonReader reader, Type targetType, ou
                 }
                 else if (targetType == typeof(DateTime))
                 {
-                    success = DateTime.TryParse(valueString, CultureInfo.InvariantCulture, DateTimeStyles.None, out var localResult);
-                    result = localResult;
+                    if (DateTimeHelper.TryParseMSDateTime(valueString, out var localResult))
+                    {
+                        success = true;
+                        result = localResult;
+                    }
+                    else
+                    {
+                        success = DateTime.TryParse(valueString, CultureInfo.InvariantCulture, DateTimeStyles.None, out localResult);
+                        result = localResult;
+                    }
                 }
                 else if (targetType == typeof(DateTimeOffset))
                 {
-                    success = DateTimeOffset.TryParse(valueString, CultureInfo.InvariantCulture, DateTimeStyles.None, out var localResult);
-                    result = localResult;
+                    if (DateTimeHelper.TryParseMSDateTimeOffset(valueString, out var localResult))
+                    {
+                        success = true;
+                        result = localResult;
+                    }
+                    else if (DateTimeHelper.ContainsTimeOffset(valueString))
+                    {
+                        success = DateTimeOffset.TryParse(valueString, CultureInfo.InvariantCulture, DateTimeStyles.None, out localResult);
+                        result = localResult;
+                    }
                 }
                 else if (targetType == typeof(TimeSpan))
                 {
@@ -367,19 +383,6 @@ private static bool TryProcessTokenAsType(JsonReader reader, Type targetType, ou
                     success = true;
                 }
             }
-            else if (tokenType == JsonToken.Date)
-            {
-                if (targetType == typeof(DateTime) && reader.Value is DateTimeOffset dateTimeOffset)
-                {
-                    result = dateTimeOffset.UtcDateTime;
-                    success = true;
-                }
-                else if (targetType == typeof(DateTimeOffset) && reader.Value is DateTime dateTime)
-                {
-                    result = new DateTimeOffset(dateTime);
-                    success = true;
-                }
-            }
 
             value = result;
             return success;