XML file format
1. Introduction
The overall scope of BMDW development phase two is to receive more data from our listing organisations and to make these data available through our Search & Match Service. However, old format (DOT20) is not an appropriate format when you have many different fields. therefore, we had to move to another file format. The new file format is an XML (Extensible Markup Language) file which is considered an industry standard that is extendable, robust and easy to use.
Several people from the community formed a working group to create the required XSD files. These files define the elements that are allowed in the XML file, the order of the elements and the values that will be accepted. The names of the elements are based upon EMDIS specifications and aligns with the EMDIS Data Dictionary when appropriate. Several elements are basic elements that should be included in all files, but there are also elements that are specific for only donors or only cord blood units (CBUs).
We will now explain the composition of the XML file and how you should use the XSD reference files.
2. XSD schema files
We provided two XSD sxhema files that define the structure of your XML file basicTypes.xsd and Inventories.xsd.
The Inventories file describes the structure of the XML file and the order of the elements. Here you can also find if a certain field is mandatory or not (minOccurs="0"-> not mandatory). This file includes many "complexType" : an XML element that contains other elements and/or attributes. In the file you can see that the values of the elements can be defined here, like the elements GRID and ID, or that after the name of the field a "type" is defined. For example for the element with name BIRTH_DATE you see type="bareDateType". The definition of "bareDateType" is described in the basicTypes.xsd file.
We will now describe the global structure of the XML file and the elements.
2.1 General Fields (InventoryType)
Field Identifier | Required | Description | Type | Length | Comment |
|---|---|---|---|---|---|
| CREATION_TIME | Yes | Creation time stamp of the inventories (in UTC) | dateTime | minimal 20 | Without fractional seconds the length is 20, for example: 2016-08-23T13:16:48Z. Additional notes: CREATION_TIME is defined as "Creation time stamp of the <INVENTORIES>" that means the time in UTC when the complete and valid file was finally created at the registry. This can be the same as SNAPSHOT_TIME. |
| LISTING_ORGANIZATION | Yes | Organisation that lists the donor/cbu provided as ION | ionType: number between 1000 and 9999 | 4 | Issuing Organisation Number (ION) allocated by ICBBA. This can be different from the POOL when another organisation is sending the data to BMDW. |
| POOL | Yes | Physical location of the donors/CBUs of the inventory provided as ION | ionType: number between 1000 and 9999 | 4 | Physical location of the donors/CBUs of the inventory provided as ION. |
| CONTENT_TYPE | Yes | Type of the inventory items, i.e. donor ("D") or CBU ("C") | contentTypeType | 1 | The content-type is also shown in the fileName. When CONTENT_TYPE is "D", the INVENTORY must contain <DONOR>-blocks. When CONTENT_TYPE is "C", the INVENTORY must contain <CBU>-blocks. |
| UPDATE_MODE | Yes | Update mode of the inventory, i.e. FULL or DIFF | updateModeType | 4 | Only UPDATE_MODE "FULL" is currently supported. Always the complete inventory should be send. |
| SNAPSHOT_TIME | No | Timestamp of the 'data snapshot' (in UTC) | dateTime | minimal 20 | Without fractional seconds the length is 20, for example: 2016-08-23T13:16:48Z Additional notes: SNAPSHOT_TIME in the element <INVENTORY> is defined as "timestamp of the data snapshot in UTC" that means the timestamp of the creation of this part of the complete file. This can be the timestamp of the XML export and I guess that in most of the cases it will be identical to the CREATION_TIME. |
| SCHEMA_VERSION | Yes | Version of the applied XML Schema Definition (XSD) | schemaVersionType | The schema version is very important as this determines the validation rules that should be applied during the processing of your file. |
2.2 ItemBaseType fields (for Donors and CBUs)
Field Identifier | Required | Description | Type | Length | Comment |
|---|---|---|---|---|---|
| ID | Yes | Unique identifier of the donor/CBU | String | 17 | Unique identifier of the donor/CBU: The value comprises the EMDIS hub code + donor identification allocated by the associated donor registry, where the sending organisation is an EMDIS member, otherwise the two digit ISO country code of the associated donor registry + donor identification allocated by the associated donor registry. For example: AU600196166, DEGOE-35487, US087013165, SB45 |
| GRID | No | Global registration identifier of the donor/CBU | String | 19 | |
| ATTR | No | Describing attribute of the donor/CBU according to house rules of the sending organization. | String | 3 | |
| BIRTH_DATE | Yes | Date of birth of the donor/CBU | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
| SEX | No | Biological gender of the donor/CBU | sexType | 1 | sexType: "F","M" NOTE: Mandatory for donors, optional for CBUs |
| ABO | No | Blood group (ABO) of the donor/CBU | aboType | 2 | aboType: "A","B","O","AB" |
| RHESUS | No | Rhesus (Rh) factor of the donor/CBU | rhesusType | 1 | rhesusType: "P","N" NOTE: "+" and "-" are not supported |
| ETHN | No | Ethnic group of the donor/CBU | ethnType | 4 | ethnType: "AFNA","AFSS", "ASSW", "ASSO", "ASCE", "ASSE", "ASNE", "ASOC", "CAEU", |
| CCR5 | No | CCR5 status of the donor/CBU | ccr5Type | 2 | ccr5Type: "DD","WW","DW" |
| HLA | Yes | HLA of the donor/cbu | hlaType | Explained separately at hlaType | |
| KIR | No | KIR genotype of the donor/CBU | kirType | Explained separately at kirType | |
| IDM | No | Infectious disease markers (IDM) and other relevant tests of the donor/CBU | idmType | Explained separately at idmType | |
| RSV_PAT | No | Unique identifier of the patient the donor/CBU is reserved for (STATUS=RS). | String | 17 | The value comprises the EMDIS patient identification, where the patient search centre is an EMDIS member, otherwise the value is empty. For example: AU9654021, DE275342, US2277450. NOTE: This field is not required for status "RS" and can be transmitted as empty if privacy concerns exist. |
| STATUS | Yes | Status of the donor/CBU | statusType | 2 | statusType: "AV","TU","RS" ("DE" is not supported yet, "RE" not valid for CBUs) |
| STAT_END_DATE | No | Date until which the current status will be applicable | bareDateType | 10 | Date without timezone information, example 1968-06-28, Date Delimiter = "-" |
XML example files
Below you can find two XML example files: one for donors and 1 for CBUs.
Both files contain only 2 records, but in those two records almost all possible elements contain a value. It can help you to check the order of the elements in your own XML file. Please be aware that values like GRID are fictive and do not follow the rules for the check character.