How to differentiate between custom fields in documents and fields used by the CHT

Development
1

Couch stores JSON docs without any schema. The CHT allows for writing custom fields for reports/contacts via the open-ended form configuration.

At the same time, the CHT system relies on a certain amount of expected structure to exist on this docs (e.g. type, name, date_of_birth, etc.). The question that has come up (in the context of a separate discussion) is how devs (both ones working on cht-core and devs making app configurations) are supposed to know what these special fields are (without memorizing the entire docs site).

AFIK we don’t have a list of “reserved fields” documented anywhere. Even if we did, as a core developer, how could I go about adding fields to that list without worrying about collisions with existing custom fields?

In the above-linked issue thread, we have been discussing the possibility of some kind of standard prefix for fields like this. So instead of is_canonical, we would call the field something like cht_is_canonical or _is_canonical. Some kind of prefix indicator for the field names seems useful because:

  • App developers can know not to use the prefix for any custom fields when writing form configuration.
  • Core developers can know that fields with that prefix should be safe from collisions with custom fields.

Throwing this thread out here to see if anyone has more thoughts/ideas/opinions on how to handle this! Thanks!

3 Likes
2

@diana @sugat do you have any thoughts here?

3

I think adding new keys each for custom fields and for fields used by CHT would be a nice solution. Then all the fields/values would be stored within those keys eliminating the cases for overwriting. I’m not very fond of the prefix and suffix style of naming as it can get unmanageable with the increase in number of fields.

1 Like
4

I believe documenting reserved fields is necessary, and we kind of already do: Database schema conventions | Community Health Toolkit

This page might not be comprehensive, but I believe it should.

I also don’t like the burden of prefixes/suffixes, but I think we could inforce grouping, so the structure of a doc (eg contact) could be:

{
 _id: '123',
 name: 'george', 
 type: 'person',
 date_of_birth: '20-12-1982',
 schema_version: 1,
 fields: { .... }
}

I think we should definitely refrain from large migrations to edit existent data.

1 Like