It appears that I have opened a can of worms so to speak 
I haven't had time to dive too deeply into the comments but here are some first reactions I have.
First, I think that date precision is one of the hanging points here. Mead alluded to this and it becomes important when implementing in Java/C# when dates are processed as DateTime or Calendar objects; it becomes impossible to determine the actual precision. HL7 handles this by representing a partial date (200909 for September 2009), however I think that this has some repercussions in terms of formatting and actually implementing (i.e. code generators will expose this as a String which isn't helpful IMO).
Also, I think Andrew touched on some business cases where some fields might be restricted to month (sorry if I misunderstood your commentary I haven't dived into deep thought about it), however I would like to stay away from restricting all dates to be precise to the month (but still allow this business case).
I see FRED as a messaging specification (+ reference implementation). I think we need to clearly define the difference between what is conveyed on the wire and what responsibility exists to store/reproduce the data. IMO consumers should merely be able to convey a precision based on their current dataset, user interface, or other factors and don't need to store the precision. For example, if an end-user program has UI with a calendar drop-down then it should convey it captured the date precise to the day, whereas another program with a year/month drop-down should convey the month precision. It doesn't matter how it is stored in their internal database. The FRED service implementers however do need to be aware of this precision and must be capable of regurgitating it.
My dream would be a common type definition that can be used for all dates/times that is consistent no matter what date data is being represented (opening date, approval date, or whatever dates we put into the messages in the future) and will allow any precision (HL7's TS is good at this however as I mentioned before there are repercussions of using that structure). What I'd like to have is some verbiage like this in the final API text (this is just a sample, I don't expect this will be the final solution we create):
---------------- FRED API.DOC ----------------
**Dates**
Dates and times are described in the FRED API using one of the following types: fac:simpleDate or fac:complexDate defined in Figure X.
Figure X - Schema for dates
<xs:simpleType name="simpleDate">
<xs:union memberTypes="xs:date xs:dateTime xs:time">
</xs:union>
</xs:simpleType>
<xs:complexType name="complexDate">
<xs:simpleContent>
<xs:extension base="simpleDate">
<xs:attribute name="offset">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="D"/>
<xs:enumeration value="M"/>
<xs:enumeration value="Y"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
End Figure X
These two types are used based on the following conditions:
fac:simpleDate (default) represents a union of xs:date, xs:dateTime and xs:time whereby the value reported in the instance represents the full precision of data:
<!-- Known to have occurred on September 1 2012 -->
<approvalDate>2012-09-01</approvalDate>
<!-- Known to have occurred at midnight on September 1, 2012 -->
<approvalDate>2012-09-01T00:00:00</approvalDate>
fac:complexDate represents an extension of simpleDate where the precision of the actual value cannot be expressed using xs:date, xs:dateTime or xs:time. This type defines a precision attribute which qualifies the value. Any date can be assigned a complexDate type by overriding its type, for example:
<!-- Known to occur in September 2012 -->
<approvalDate xsi:type="fac:complexDate" precision="M">2012-09-01</approvalDate>
Table X describes the precisions that can be conveyed using the fac:complexDate type:
---------------- END FRED API.DOC ----------------
Second, I agree that there is a difference between being optional in the schema and highly recommended in actual implementation. I think we can place this into the spec document as well as the schema as <xs:annotation> documentation using verbiage MUST/SHALL and MAY. For example:
--------- FRED API.DOC ---------
All facilities MUST carry an Active flag which MUST be set to true if an only if the facility is known to be accepting patients and is approved by the implementing jurisdiction. Additionally, facility resources MAY carry the optional Status field. When a facility resource carries a status it MUST be drawn from table X...
--------- END FRED API.DOC ---------
The text from the FRED API.DOC sections is just sample verbiage; I haven't actually started the documentation yet
Cheers
-Justin
-----Original Message-----
From: facility-registry@googlegroups.com [mailto:facility-registry@googlegroups.com] On Behalf Of Bob Jolliffe
Sent: Tuesday, October 09, 2012 6:36 PM
To: facility-registry@googlegroups.com
Subject: Re: Semantics in FRED spec
Thanks Andrew for this great feedback! I'll take some time to digest, but I think all of the points you raise are valid. I'm particularly thinking about how best to deal with "optional" elements and how they might be mandatory when dealing with different classes of conformance.
On 9 October 2012 23:16, Andrew Inglis <andrew.d.inglis@gmail.com> wrote:
Hi All,
I have been following this discussion with interest and have actually
follow up with some people involved in using Facility registries. I
have syntheses them into this response.
On the Date, having at least the Month/Year would be preferable of
just the year, The reason is when linking to existing datasets you
can confirm if the link is correct based on the only having data after
the facility was open. In number of countries (Ethiopia come to mind)
they have been opening facilities (then closing some) at a rapid rate,
thus just having the year is not enough. Therefore, I would suggest
that at least having month and year. I understand the issue that this
creates so if that means have the day/month/year that is preferable to just the year.
On the Approval Date, some facilities are not operating with approval
pending, in Kenya there some major facilities have been operating (for
years) still waiting for approval of their registration therefore i
might worth change it to operational date. Just a suggestion.
On the Status and Active, Active is a better binary field. I would
suggest that we look at adding Status into the Optional section, this
is very is a very useful field in particular when linking it to
existing data and managing the list.
Looking on the Optional sections, i understand the reason that we
don't want to be too prescriptive, however, instead referring to them
as "Optional" but as "Highly Recommended".
in managing health facilities lists have the "Agency", and an
additional field called "Type" are very useful in managing and linking
existing datasets.
On current optional area is "agency" I am assume is "owner" -
Government, Private, FBO, NGO in Kenya and Tanzania it was both very
useful in validating linking existing dataset together and in managing
the list of facilities in Kenya. The reason was that it this help
identify matches and when managing it helped Disitrict Health Offices
in Kenya in identify and ensuring that the exact number facilitie sin
the district were known and how many were government vs
non-government. Not knowing this distinction lead to confusion on the
exact number of facilities as people would include and exclude sites
based what they thought facility was, having this classification in the registry gave clarity.
Facility "Type" again is very useful when linking existing dataset and
in managing the list of facilities, it was useful in Kenya, Tanzania,
Zambia, Nigeria, Ghana and Rwanda. The reason being that when linking
existing data been able to differentiate ate by type was very useful in validating
linkages. In some cases their would two to three sites with the same name
but were different types. Also, the type was not always in the name,
secondly some sites changed type but did not change their name thus
the name lead to confusion thus in managing the list know the type
became very important.
On the Geo.xsd
I would also suggest adding two elements;
Setting the number decimal places to at least 4 decimal places. if you
have less than that then the accuracy of the location is limited and
it hard to differentiate if you have two sites next to one another or
are the same site just know by different names. This is a common
occurrence in some countries where it has name such as St Joseph
Hospital but is also know as FRED District Hospital. Thus having the
data at least to the 4 decimal point will help in managing the data
quality if the coordinates and identifying duplicates.
I would also suggest adding a field called "Accuracy" which describes
the accuracy of the coordinates either as - "GPS", "Detail Map"
"Gazetted" or "Unknown". In Rwanda it was very fortunate that the
government had geocoded a large number of the sites. in other
countries this is not the case where the geocodes come from a number
of difference sources with different level of accuracy. Therefore, i
would suggest the addition of this field if the plan is expand its
other countries. It would also help the in the management in to where cooridates to be updated.
I have included a link to a publication under the USAID|DELIVER
PROJECT that describes this in greater detail
http://www.deliver.jsi.com/dlvr_content/resources/allpubs/guidelines/G
uidLinkLogDat_GIS.pdf
I hope this is useful feedback.
Andrew Inglis
GIS Team Leader
John Snow, Inc.
USAID | DELIVER PROJECT
1616 Fort Myer Drive
11th Floor
Arlington, VA 22209
(703) 528-7474 ext. 5270
andrew_inglis@jsi.com
Learn about JSI at: www.jsi.com
On Tuesday, October 9, 2012, Bob Jolliffe wrote:
Hi Mead
Agree that times and dates are always a can of worms. With routine
reporting we have huge difficulties with weekly periods (everyone has
a different idea about the first day of the first week of the year),
financial year reporting and whether folk choose to look at the moon
(Islamic calendar) or the the sun to mark the passage of time.
This case is hopefully simpler ...
What we really need to get to, as Rowena is suggesting, is what users
will really use this <openingDate> for. If it is just for
informative display then it doesn't really matter (too much) what we put in it.
If it will be used in computations, eg. which facilities opened in
this period, then it is better to store a date in the backend
database, even if the user interface allows the entering of just
'2007'. Allowing for a union of different representations just puts
off the eventual resolution to a date till later.
But I don't have a really strong view on it. Except that I would use
the union type I referred to earlier rather than a regex. And unless
there is a compelling requirement for the extra complexity I'd favour
a simple date type for opening date.
Bob
On 5 October 2012 18:20, Mead Walker <dmead@comcast.net> wrote:
> Formats such as xs:date have always been a problem in healthcare
> (perhaps in other settings as well.
>
>
>
> The problem is that if you don't have a full date, it will default
> to something it makes up. So, January 14, turns into January 14,
> at midnight.
> October, 2011 turns into October 1 (or October 31) 2011. This
> creates a host of problems. It is also why HL7 has the date/time
> construction that it does
>
>
>
> Mead
>
>
>
> From: facility-registry@googlegroups.com
> [mailto:facility-registry@googlegroups.com] On Behalf Of Rowena Luk
> Sent: Friday, October 05, 2012 11:19 AM
>
>
> To: facility-registry@googlegroups.com
> Subject: Re: Semantics in FRED spec
>
>
>
> I'd be curious to hear more about the use case in Rwanda, and how
> strong a need/requirement that was. If it's not a hard requirement,
> I'd be in favour of sticking with the standard xs:date, for the
> sake of keeping the spec simple, clear, and consistent. Countries
> that map approval on the basis of yearly or monthly cycles could
> adopt some sort of internal convention to log those dates by the
> first or last day of those timespans.
>
> On Fri, Oct 5, 2012 at 10:34 AM, Bob Jolliffe >>> > <bobjolliffe@gmail.com> >>> > wrote:
>
> On 5 October 2012 14:42, Justin (Mohawk College) >>> > >>> > <justin.fyfe1@mohawkcollege.ca> wrote:
>> Hi Bob / Rowena,
>>
>> I think these changes to the schema are good, so long as the group
>> agrees they fulfill the use cases.
>>
>> If I understand properly, a status of "pending" would need to be
>> represented as an extension, however from a interoperability
>> standpoint it would be sufficient to know the facility is not yet
>> active:
>>
>> <active>false</active>
>> <x:status xmlns:x="urn:extension...">pending</x:status>
>
> Yes that is my understanding too ...
>
>
>>
>> Regarding date, it may be possible to fulfill the Rwanda usecase
>> for using
>> 2009 (any time during 2009), 2009-09 (any time during Sept. 2009)
>> and
>> 2009-09-09 using a restriction on xs:string which allows this, for
>> example:
>>
>> <xs:simpleType name="extDate">
>> <xs:restriction base="xs:string">
>> <xs:pattern value="^[0-9]{4}(-[0-9]{1,2})?(-[0-9]{1,2})?$"/>
>> </xs:restriction>
>> </xs:simpleType>
>>
>> And then referencing the type as <xs:element name="approvalDate"
>> type="fac:extDate"/>. This is similar to how the TS datatype is
>> specified in
>> HL7 schemas [ but don't say that too loudly 
]
>
> I love regexes but I am not sure they are the best for validating
> dates. The SDMX schemas (of which we'll also not speak too loudly)
> also address something similar by effectively allowing a union of
> standard types, something like this.
>
> <xs:simpleType name="extDate">
> <xs:union memberTypes="xs:dateTime xs:date
> xs:gYearMonth xs:gYear"/>
> </xs:simpleType>
>
> If this is indeed the semantics we want, I suggest we do it like this.
>
> Cheers
> Bob
>
>
>> Cheers
>> -Justin
>>
>>
>> On Friday, October 5, 2012 5:25:40 AM UTC-4, Bob Jolliffe wrote:
>>>
>>> Latest commit in response to Rowena's suggestion:
>>>
>>>
>>> --
--
Andrew Inglis
--
--
This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message. If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited. If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.
--