Health Data Metadata

You can configure metadata fields on a study, which will be automatically applied to all schemas. This is useful for fields that should be global to all schemas, such as start- and endTimes or taskRunGuids.

This doc covers the configuring metadata and how metadata is exported to Synapse. For more details on how to submit metadat with your uploads, see the corresponding sections in the Bundled Zip File Upload docs and the Synchronous Health Data Submission docs.

Configuring Metadata

Studies will have a new attribute called uploadMetadataFieldDefinitions, which are defined the same way as schema field definitios. This can be edited either through the REST API or through the Bridge Study Manager. (Note: All metadata field definitions are implicitly optional. The "required" field in metadata field definitions is ignored.)

IMPORTANT NOTE: Once created, metadata fields cannot be deleted or modified except by an Bridge admin.

Example:

{
  "name":"mPower",
  "identifier":"parkinson",
  ...stuff...
  "uploadMetadataFieldDefinitions":[
    {
      "name":"startDateTime",
      "type":"timestamp"
    },
    {
      "name":"endDateTime",
      "type":"timestamp"
    },
    {
      "name":"taskRunGuid",
      "type":"string",
      "maxLength":36
    }
  ]
}

Metadata in Synapse

The Bridge Exporter will automatically create new columns in health data tables in Synapse for each metadata field. The column will be named "metadata.[fieldName]". This name was chosen to (a) conform with Synapse column naming restrictions (b) to minimize potential conflicts with existing field names and (c) to be equally valid names for both the upload API and the synchronous API.

In addition, every row will have a rawMetadata field, which is a filehandle with all submitted metadata.

Our above example would be converted to the following example table fragment:

(Note: Our example serializes the timestamp as an ISO8601 string for simplicity of the example. In actuality, Bridge exports timestamps as epoch milliseconds and timezone offset string as two separate columns.)

Conflicts in Field Names

If for whatever reason, there is already a schema field named "metadata.[fieldName]", the field defined in the schema takes precedence over the metadata field. (This applies to both type and value.) A good way to remember this is "specific beats general".

Limits

Metadata fields cannot create more than 20 columns or 2500 bytes. Note that the size limit is for space allocated, not for how much data is actually submitted. This also does not count against the column or size limit for schema fields. For more information, including column size by field type, see Schema Limits