You will see the error above if you try to update an instance of the BasicDemographicInformation HealthRecordItem type that is stored in the v2 type schema from an application that “speaks” the v1 type schema.

In our recent 0910 release we updated the Basic Demographic Information HealthRecordItem type to use Codable Values for State/Province and Country. This helps make the data more consistent across applications, but it means that we had to version the data type. 

Eric Gunnerson’s blog post describes how data type versioning is handled within the HealthVault platform and my blog post three months ago elaborates a bit on this topic.  But the recent revision of Basic Demographic Info gives me a chance to expand a bit more, discuss some corner cases and give some examples. 

Data Type Details

You can see the type details in our HealthRecordItem Type Schema Browser:

• bf516a61-5252-4c28-a979-27f45f62f78d is the older version of BasicDemographicInfo.
• 3b3e6b16-eb69-483c-8d7e-dfe116ae6092 is the newer version of BasicDemographicInfo. 

You can also see the type details in our MSDN Library, which always documents our most recent SDK version (as of right now, version 1.1.2193.4712).

• Microsoft.Health.ItemTypes.BasicV2 – this is the new type
• Microsoft.Health.ItemTypes.Basic – this is the old type
• For types that got revised before 0908, we moved the old schemas to the Microsoft.Health.ItemTypes.Old namespace.  But in order to ensure binary compatibilty between SDK releases moving forward, we have switched are naming approach as described above.  From now on, old versions of data types will retain their current name and namespace and the new type version will be “burdened” with the new name. 

How this impacts you

If you have a HealthVault application which is already live and you interact with Basic Demographic Information then you are almost certainly using the older version of the schema.  Per the descriptions in Eric’s and my blog posts, if you ask the HealthVault platform for Basic Demographic Information then it will return all of the instances of both v1 and v2 of the data type.  Any v2 instances will be downconverted into v1 of the schema.  These downconverted instances will be read-only to your application.  If you try to update any of these downconverted instances then you will see the error message above.

The HealthVault Shell has been updated to use the new version of Basic, 3b3e6b16-eb69-483c-8d7e-dfe116ae6092. This means that any new account will have its Basic Demographic Information stored in the new schema.  It also means that any user who updates their Basic Demographic Info in the Shell will get moved to the new schema.

You have two options in order to avoid this error, and both require a code change:

• Stay on the 1.0.2145.4504 and don’t update BasicV2 instances.  You can accomplish this by capturing this exception and letting the user know that an update of this item was not possible, but I’d rather not wait until the user tries to save changes.  Instead, look at the IsDownversioned property on each instance of basic and tell the user when an instance is read-only using your own UI cues.  You should also give the user a workaround for updating this information, such as using the HealthVault Shell.
• Move to the 1.1.2193.4712 SDK

Moving Forward

We don’t update data types all that often, and few of our data types are singletons so it is unlikely that you’ll see this issue again in the near future.  But you can “future-proof” your application by looking for the IsDownversioned flag on each HealthRecordItem instance before you allow the user to attempt an update.

We are considering some revisions to our approach to data type versioning that may simplify this process for developers.  Keep an eye on the HealthVault Developer Blog for announcements about updates to the HealthVault platform.