Representing Partial Dates in a JSON API

Question

I am managing a RESTful JSON data API, which is growing in scope. Currently, we are returning all dates over the wire as strings "YYYY-MM-DD", but we also need to represent the concept of partial dates.

What I mean by a partial date is a date value that has unknown components, either a Year-Month, or just a Year. In our presentation layer, this would be translated like:

2009-09-03 =>  '3rd September 2009'
2009-09    =>  'September 2009'
2009       =>  'Undated 2009'

Is there any precedent or standard for this type of data? For example, MySQL enables this by allowing 00 values in date and datetime fields - eg: '2009-00-00' will save directly to a MySQL date field, but this value does not translate consistently when parsed by most programming languages' date libraries.

What is the best way to semantically represent this concept of partial dates in the JSON feed?

Ideally, we would be able to implement a solution that was easy for our consumers to parse, but also straightforward to explain in documentation.

Answer 1

EDIT: Thinking about this again, YYYY-MM and YYYY are both valid ISO 8601, so it would probably be better to just use that.

There is no standard for JSON dates (of any kind) because JSON is a subset of JavaScript literal syntax, and JS has no date literals. See http://msdn.microsoft.com/en-us/library/bb299886.aspx#intro_to_json_sidebarb .

Answer 2

Hi,

You may find your solution @ www.datejs.com

Thanks.

Answer 3

In terms of storage, you can store the ambiguity by storing year, month, and day in separate columns, and allowing nulls. That way you can query it with string concatenation and the coalesce(day,'00') function to grab out a '00' if a column is blank.