Datatype versioning

Mar 3, 2011 at 6:48 PM

Let's say we have two versions of a specific datatype 1 and 2.

If an application  A upload data using thing type version 1 to healthvault and this data has been modified by the user in healthvaut then next time when the application A try to update this same record, the platform throw an error.

the reason is that the platform will automatically convert the data from version 1 to version2.

Recently, Microsoft did some changes in .NET to better support the datatype versioning and we need to know if any similar work has been done for JAVA SDK?

Please see for reference:

- The 1009 Release Notes- section “Better Support for Versioned Types:

Thank you.

Mar 3, 2011 at 11:20 PM
Edited Mar 3, 2011 at 11:21 PM



HealthVault converts data type versions during GetThings.  By default, HealthVault returns the version of a datatype depending on the version specified in the application's auth rules.  That behavior may be overridden in the ThingFormatSpec section of GetThings. 

From the schema documentation for /group/format/type-version-format

When a type gets versioned, HealthVault will retrieve instances of multiple versions even when only one type is specified in the request filter.  By default HealthVault will map the XML of the instance to the version supported by the application based on the base authorization XML specified in the configuration of the application in HealthVault. However, if multiple versions are supported by the application, it can use this parameter to state the version format to use when writing out the instance XML.

For example, when querying for medications, HealthVault will retrieve medications of both version one and two schemas. If an application only supports version one of the medication schema, then HealthVault will automatically map version two instances down to the version one schema. However, if the application supports both version one and two by declaring both type IDs in the applications configuration, then version one instances will be returned using the version one schema, and version two instances will be returned using the version two schema. If this application wants to retrieve all instances using a common schema (say version two), then is would specify the version two type ID in this parameter and all instances will be mapped to version two of the medication schema before being returned.

You can inspect the response to GetThings to determine if the thing has been down or upconverted for your request.  Inspect /thing/flags:

0x2 (Downversioned) - the thing instance was converted from a newer format to an older format while being written in the response.  Applications should not attempt to update an instance that has been down-versioned.

0x4 (Upversioned) - the thing instance was converted from an older format to a newer format while being written in the response.  Applications should only attempt to update the instance if given explicit approval by the user as this will change the stored instance from the older format to the new format. In some cases this may cause data loss.



HealthVault will not convert types between versions during PutThings.  If, during PutThings, an older version is sent as an update to an existing newer version HealthVault will return error 85: InvalidThingTypeVersion.  So if you call PutThings with a V1 data type as an update, but the current version fo the data type is V2, the update will fail.


The .NET SDK introduced some changes to automatically set the /group/format/type-version-format field depending on the type-ids requested.  This Java SDK gives you access to all the request fields in getThings and you can set it however you'd like.  HealthVault platform did not change.