Date format for `io.cncf.oras.artifact.created`

[SteveLasker]

The artifacts-spec defines the io.cncf.oras.artifact.created annotation for date/time sorting of artifacts, based on a created date.

io.cncf.oras.artifact.created date and time on which the artifact was created (string, date-time as defined by RFC 3339)

The annotation is currently is defined with RFC 3339

This issue re-opens the discussion if there are valid reasons to switch to another format, such as:

• ISO 8601

The created date will be used by the referrers API to sort (asc or desc) references. For instance, a list of scan results could be sorted to get the first (original), or last (current).
A list of annotations may be added, where the same value is set to a new value, over time.
A user may want the original or latest value of the annotation.

• Are there specific indexing services that make one format better over another?
• Are there other scenarios where another datetime format was chosen, and we want to avoid conversion?

[michaelb990]

RFC 3339 describes the Internet Date/Time Format which conforms to ISO 8601. What is this issue proposing to change?

https://datatracker.ietf.org/doc/html/rfc3339#section-5.6

[huanwu]

The backend store for the manifest (cosmos) doesn't support datetime directly and the datetime is stored as strings. The only recommended format for DateTime strings in Azure Cosmos DB is yyyy-MM-ddTHH:mm:ss.fffffffZ which follows the ISO 8601 UTC standard. Converting the date strings to this format will allow sorting dates lexicographically.

https://docs.microsoft.com/en-us/azure/cosmos-db/sql/working-with-dates

There's no clear document if RFC 3339 is lexicographically sortable. It might work for most of the cases.

[michaelb990]

Maybe I'm missing something. Can someone explain (or point me to) what the difference is?

RFC 3339 says:

The following profile of ISO 8601 [ISO8601] dates SHOULD be used in new protocols on the Internet.

[huanwu]

I referred this doc to compare ISO8601 and RFC3339 https://ijmacd.github.io/rfc3339-iso8601/#:~:text=RFC%203339%20is%20case%2Dinsensitive,the%20standard%20allows%20arbitrary%20precision.

At least, the following two points will make the sort result a little different.

• RFC 3339 allows for other characters to replace T but only gives a space character as an example.
• RFC 3339 is case-insensitive so every T or Z could also be t or z respectively. Previous editions of ISO 8601 were also case-insensitive.

We need exactly follow yyyy-MM-ddTHH:mm:ss.fffffffZ format, which is lexicographically sortable to get the accurate sorting result.

[SteveLasker]

@huanwu, so you're mostly focused on the diff between T/t and Z/z?
What does sorting look like when T and t are interchanged? Are we expecting other characters, as opposed to numbers, fit in the middle and change the ordering?
Or, is it sorting of different times, where the T and t are jumbled?

• 2022-07-12T00:22 - 1
• 2022-07-12T01:00 - 2
• 2022-07-12T02:00 - 3
  vs.
• 2022-07-12t01:00 - 2
• 2022-07-12T00:22 - 1
• 2022-07-12T02:00 - 3

[huanwu]

Yes, the concern is T and Z. Not only T/t and Z/z, it also allow use other character to replace T.
In your sample:
2022-07-12T00:22 - 1
2022-07-12T01:00 - 2
2022-07-12T02:00 - 3

->
2022-07-12T00:22 - 2
2022-07-12A01:00 - 1
2022-07-12T02:00 - 3

That means the hour, minute, seconds, mili-seconds sequence are not honored.

[michaelb990]

Does either standard guarantee that you'll be able to sort without processing?

Looking at your comparison chart, something like 20220714T092455.405000 would also be ISO8601 compliant. I think we have to either make this a specific format compliant with one or both of these standards (e.g. yyyy-MM-ddTHH:mm:ss.fffffffZ ONLY) or rely on registries parsing it and converting it into a sortable datetime representation.

[SteveLasker]

Thinking about how registries would index the information, I think we're discussing how it's converted to what various implementations would use.
For instance, if someone wanted to use lexicographically sorting, it would need to convert the RFC 3339 format to the indexing format. That might be converting to upper case, etc.
Which I just realized @michaelb990 is saying the same thing. :)