How can I force serialization of startDate for an event to include time?

[kjlibsol]

Question

If I create a new sportsevent...:

var sportsEvent = new Schema.NET.SportsEvent()
  {
    Name = "testing",
    StartDate = DateTime.Now()
  };

and I serialize it...:

string schemaLdJson = schemaOrgSportsEvent.ToHtmlEscapedString();

the startDate is serialized like this:

"startDate":"2020-05-24"

Notice the time is excluded.

According to schema.org, it is valid to include time in a startdate:

https://schema.org/startDate

How can I force Schema.NET to output the time as well?

[kjlibsol]

...I will answer it myself, because (as it often happens), while typing my problem I had an idea....

If you create a DateTimeOffset like this (if the DateTime value is already UTC)...:

var startDateTimeOffset = new DateTimeOffset(model.Event.StartTime, TimeSpan.Zero);

it serializes as expected.

or like this if you already have the correct DateTime.Kind set.:

var startDateTimeOffset = new DateTimeOffset(model.Event.StartTime);

I still think it would be nice if just adding a DateTime would include the time, but maybe there is a good reason for this I am just not seeing. :)

[Turnerj]

Hey @kjlibsol!

At the core of it, we map schema Date to C# int/DateTime and schema DateTime to C# DateTimeOffset. If you supply a C# DateTime, we write that as a schema Date. If you supply a C# DateTimeOffset, we write that as a schema DateTime.

Technically, C# DateTime is compatible with schema DateTime however some properties may imply a requirement for timezone information. For example, an arrivalDate (https://schema.org/arrivalTime) can be quite critical information to potentially get wrong if someone doesn't pass timezone information.

This is the thing though, we really treat dates as two categories:

• Those of schema Date (date precision via C# DateTime)
• Those of schema DateTime (date, time and timezone precision via C# DateTimeOffset)

However there is a third category we aren't handling directly:

• Those of both schema Date and DateTime (minimum date precision to maximum date, time and timezone precision)

In theory, we don't need to ever write the a C# DateTime field as schema Date IF we know the property also supports schema DateTime.

It should be a matter of tweaking this line to avoid our custom converter if the property is both schema Date and schema DateTime.

Schema.NET/Tools/Schema.NET.Tool/ViewModels/Property.cs

Lines 64 to 67 in 963ce4f

	else if (this.Types.Any(x => string.Equals(x.Name, "Date", StringComparison.OrdinalIgnoreCase)))
	{
	stringBuilder.AppendIndentLine(indent, "[JsonConverter(typeof(DateTimeToIso8601DateValuesJsonConverter))]");
	}

Alternatively, instead of removing the converter altogether, we could make it smarter where cases of both schema types it would only ever output C# DateTime as schema Date if the time component was zeroed out.

[RehanSaeed]

The .NET docs say that you should prefer DateTimeOffset to DateTime. I realize that in practice many are not aware of this. Given the fact that this kind of renders DateTime obsolete, in my inital design I decided to repurpose the type to represent a schema.org Date type without the time portion.

This makes me personally happy because I never use DateTime and goes along with the official guidance but I guess it's kind of an oppinionated approach that others may not approve of, which is why @Turnerj's solution seems like a good one.

[Turnerj]

Thinking about this a little more - maybe it would be appropriate to just dynamically include something extra in the IntelliSense to identify what is going on in cases where we have both Date and DateTime schema types?

eg. Imagine a line like this:

/// Use <see cref="DateTime" /> for Schema Date precision. Use <see cref="DateTimeOffset" /> for Schema DateTime precision.

Would keep the original intent for accuracy when potentially referring to schema DateTime fields while also being clearer to the end user about what to use. It would require changes to how we create the comment field though which might be complicated at present.

[RehanSaeed]

We could add this in the ///<remarks> comment section?

[Turnerj]

I'm not sure if the remarks section actually shows up in IntelliSense? If it does, that would be a good place to put it.

[Turnerj]

@iJoris - out of curiousity, why can't you use a DateTimeOffset? Internally in your application you can still use C# DateTime and only switch to DateTimeOffset when you are setting the properties on the Schema object.

new WhateverYourSchemaObjectIs
{
    WhateverTheDatePropertyIs = new DateTimeOffset(myDateTime)
}

To completely avoid any reference to DateTimeOffset, using C# DateTime for outputting a schema DateTime, you'd need to do a lot of work. At minimum would be to write your own converter and even then, I don't think it is easily possible to get a converter to work on the right property without compiling your own version of Schema.NET.

[iJoris]

@Turnerj - Sorry I've made a mistake at writing my message.

I think my IDE cached the wrong parameters for the package.
That resulted in errors that StartDate only accepted a int or DateTime

It works now with using:
StartDate = new DateTimeOffset(eventdate);

[RehanSaeed]

@kjlibsol Are you happy to use DateTimeOffset? Can we close this?

[kjlibsol]

Yeah, sure. 👍