edjez
commented
11 years ago I suggest a sub array called properties to deal with the basic data types;
Here is a bit of narrative about how resource map does it and an example
Implications/expectations for the data managers
The expectations are :
- for any field is the implementer specifies a stable code e.g. the field Manager name gets a code such as "MGR" or Number of Beds gets NUMBEDS.
- the code is specified using basic character set and constrained to what makes good xml element and attribute names (letters,numbers,no spaces, no apostrophes & punctuation etc)
- the code is not a localization/internationalization string (i.e. it is stable across user interface languages, and you won't
- no duplicates are allowed within the same collection/dataset
- Caps of these codes are respected and saved but whether to use PascalCasing camelCasing or CRUISECONTROLFORCOOL, and whether to use spaces or_not is left up to the data manager.
- We expose a friggin big warning & confirmation if a user changes a code "you may be breaking a lot of stuff". Changes to the code are immediately applied. History for the field gets maintained; but now needs to be queried using the new code. We allow you to rename a field to an old code that is not used anymore if you choose to play a game of musical chairs with your properties. Since this is for people aiding data integration, we see more need for empowerment than for strict guardrails; and in this case specifically even more so as sometimes folks need to batch integrate data that comes from elsewhere.
- Select fields (multi or single) have options that also have a stable "code". For example "X-Ray" has an "XR" code in the example below, the same code could be used for a "radiographie X" french label down the line from a client's perspectives.
Example
Here is an example of a specific facility from Resource Map API .
{ "id": 17444, "name": "Musanze Hospital", "createdAt": "2012-03-28T07:58:01+00:00", "updatedAt": "2012-03-28T07:58:01+00:00", "lat": -1.503223, "long": 29.643731, "properties": { "Color": "3", "Services": [ "XR", "OBG", "TR" ], "NUMBEDS": "55", "MGR": "Mrs. Liz" },
In the example Services is an example of a "multi select" / tag sort of field with 3 items 'selected' in this case (e.g. X-Ray, Ob-Gyn and Trauma services are offered in this facility).
Metadata
We wanted to give liberty to data managers to choose the evolution of their data dictionary more freely by implying/exposing to clients as little data definition metadata as possible from just looking at the data (ie if you want to know more about schema and constraints, go do a separate API query to get to the data definition/data dictionary). This way a field may start out as a string, and then normed into a single-select or a hierarchy as data gets cleaned up and their own practices evolve; without breaking clients.
For us, we can punt to a different API revision how to query and ultimately modify the data dictionary. At that stage, we can choose endpoints that facilitiate different sort of clients eg including an xforms projection of the metadata if folks want to render their own UIs on it.
More commentary on data types to include
I think we should explicitly leave attachments, images, and sub-forms out of this version of the spec.
Including links to external entities and references to other facilities could also be an important beyond-1.0 thing. (e.g.where you include a data field and a related URL) Links to other facilities allows you make reporting hierarchies dhis-style (hierarchy of nodes) but have less need for the URL; but in that case it's a nice REST convention to follow.
Note the "date" data type is a proper date; not a date-range ("sometime in november"). I would consider that a different data type altogether ("imprecise date") to be spec'd out in the future.
Sometimes I see mention of a 'tag' field type. Tags would be the same as a multi-select where users just happend to be able to create new options on the fly, but that is more of a UX thing not a data structure thing.
Hierarchy-of-containers scenarios can be implemented as a single-select field (examples we have seen are services offered, a hierarchy of ownership/agency or the country/province/district hierarchy).
Define way to define: