Clarification on DateTime Format (1.7)

Open
#56 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
30/100
Issue type
Documentation
Clarity
Needs clarification
Activity status
Stale
Domain
documentation

Research direction

Start with Foundation-API section 1.7 and the linked BCF-XML 3.0 DateTime Format section, comparing their treatment of timezone-less values and timezone offset syntax. Done means the consistency question is resolved and section 1.7 clearly documents the agreed BCF-API behavior.

Written by the indexing model from the issue text.

Description

Here is what Foundation-API section 1.7 says:

1.7 DateTime Format

DateTime values must be rfc3339 compliant.

Examples:
2016-04-28T16:31:12Z would represent Thursday, April 28th, 2016, 16:31:12 (0ms) in UTC timezone.
2016-04-28T16:31:12.270Z would represent Thursday, April 28th, 2016, 16:31:12 (270ms) in UTC timezone.
2016-04-28T16:31:12.270+02:00 would represent Thursday, April 28th, 2016, 16:31:12 (270ms) with a time zone offset of +2 hours relative to UTC.

And this is from BCF-XML 3.0:

DateTime Format

DateTime values in this specification are always of type xs:dateTime which is an ISO 8601 compatible YYYY-MM-DDThh:mm:ss format with optional time zone indicators. This is the same format as defined in the BCF-API specification.

For example, 2016-04-28T16:31:12.270+02:00 would represent Thursday, April 28th, 2016, 16:31:12 (270ms) with a time zone offset of +2 hours relative to UTC. Please note that the colon in the timezone offset is optional, so +02:00 is equivalent to +0200.

To void ambiguity, this specification steps away from ISO 8601 on the topic of DateTime values with no timezone: The ISO 8601 says that DateTime values with no timezone designator are local times - In BCF all DateTime values with no timezone designator are assumed to be in UTC.

So what about the brilliant part where you deliberately (and needlessly) violate ISO 8601?
Would BCF-API handle that differently than BCF-XML, or do the two behave consistently and you just forgot to mention it in the Foundation-API's documentation?

Dominant language
No language data
Stars
39
Forks
9
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from buildingSMART/foundation-API

All issues in buildingSMART/foundation-API

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.