HML document specification

This document serves as a guide for understanding the HML document structure, as an alternative to having to read through the DTD itself. For each element of the DTD, a description is given for that element, its attributes, and its child elements.


Element: hml

Description:
hml is the root element of the document. Any document-level properties may be defined with property elements.

Attributes:
Name Type Required? Description
version CDATA Yes The version of HML that this document should conform to.

Children:
property 0 or more
project 1 or more


Element: project

Description:
The project element groups data into sections with a common destination or purpose, which is denoted by the "name" attribute.

Attributes:
Name Type Required? Description
name CDATA Yes Identifier for data's intent. (ex: "STAR", "SG09")

Children: (in order)
reporting-center 1
sample 1 or more
typing-test-names 0 or more


Element: reporting-center

Description:
The reporting-center element specifies the origin of the data as a center code.

Attributes:
Name Type Required? Description
code CDATA Yes Reporting center code identifier

Children: none


Element: sample

Description:
A "sample" element encloses the typing data pertaining to a particular sample. It may contain multiple typing elements. One for each locus, for instance. Any sample-level properties may be defined with property elements.

Attributes:
Name Type Required? Description
id CDATA Yes Identifier for the sample
center-code CDATA Yes Center code of the sample's origin (donor center, transplant center, etc.

Children:
property 0 or more
typing 1 or more


Element: typing

Description:
The typing element encapsulates a typing call combined with other primary data that may have been used to determine that call (sso, ssp, and/or sbt elements).
Contains:

  1. at most one interpretation element, which must appear first if present
  2. as many sso, ssp, and/or sbt elements as needed

Attributes:
Name Type Required? Description

Children:
interpretation 0 or 1 (must appear first)
sso 0 or more
ssp 0 or more
sbt 0 or more


Element: interpretation

Description:
interpretation element specifies the typing call at allele/code level. Usually contains one or two haploid elements for a particular locus, but may contain more if multiple loci are covered (example: two DRB1 haploids + one DRB3 haploid). As an alternative, it may contain genotype list(s) to represent the type(s).

Attributes:
Name Type Required? Description
date CDATA Yes Date on which the typing was carried out, or on which the final call was determined. Format can be either ISO-8601 or "YYYYMMDD".

Children:
haploid 1 or more, or
genotype-list 1 or more


Element: haploid

Description:
A haploid element specifies one-half of a full typing at a particular locus.

Attributes:
Name Type Required? Description
locus CDATA Yes Locus (ex: "A", "DRB1")
method CDATA Yes Typing method used (ex: "DNA", "SEROLOGY")
type CDATA Yes Allele/code level type (ex: "0101", "01AB")

Children: none


Element: genotype-list

Description:
A genotype-list represents a full unambiguous list of possibilities for the typing of a sample. The values of the elements in this genotype-list (each allele element) should conform to the naming nomenclature used by the the source specified by the db attribute (if provided) or should be fully understood by the message recipient (if not provided).

Attributes:
Name Type Required? Description
db CDATA No Database or other source from which elements in this genotype-list are taken (ex: "HLADB")
version CDATA No A specific version of the aforementioned source (ex: "2.8.0")

Children:
diploid-combination 1 or more


Element: diploid-combination

Description:
A diploid-combination element is one possibility value in a genotype list. There may be either one or two locus-block child elements, depending on whether the data provided in this diploid-combination covers one or two chromosomes.

Attributes:
Name Type Required? Description

Children:
locus-block 1 or 2


Element: locus-block

Description:
A locus-block element allows allele-list elements to be grouped together to mean one allele-list is a possibility if and only if all others are. This is useful, for example, in the case when listing DRB1 alleles next to the corresponding DRB3 alleles that are relevent in only some cases:

    <locus-block>
        <allele-list>
            <allele>DRB1*030101</allele>
            <allele>DRB1*0303</allele>
        </allele-list>
        <allele-list>
            <allele>DRB3*0203</allele>
        </allele-list>
    </locus-block>

Attributes:
Name Type Required? Description

Children:
allele-list 1 or more


Element: allele-list

Description:
An allele list element is a representation of the list of allele possibilities for a type. NMDP has historically used allele codes in combination with allele families to represent this. Example: A*01BC can now be represented as:

    <allele-list>
        <allele>A*0102</allele>
        <allele>A*0103</allele>
    </allele-list>

Attributes:
Name Type Required? Description

Children:
allele 1 or more


Element: allele

Description:
An allele element specifies a single allele. It should be given in LOCUS*NAME format and names must be at allele-level resolution. The value should conform to the naming nomenclature used by the the source specified in the enclosing genotype-list element (if it was provided) or should be fully understood by the message recipient (if it was not).
Example:

    <allele>A*010101</allele>

Attributes:
Name Type Required? Description
present 'Y'|'N'|'U' No Indicates presence of absence of this allele. A value of "N" can be used to indicate that a particualar allele was tested for and found not to be a possibility. A value of "U" (untested) indicates that the given allele was not tested for. The default value is "Y"

Children: none


Element: sso

Description:
Specifies an SSO test that was done. Scores are required, along with a reference for resolving what SSO probes correspond to the list of scores. Only one of "ref-id", "probe-name", or "nmdp-refid" may be given.

Attributes:
Name Type Required? Description
ref-id IDREF No Internal XML reference to a typing-test-names element contained in this document.
nmdp-refid CDATA No ID of kit registered with NMDP. The cardinal sequence numbers of the registered probes in the kit will determine the score order.
probe-name CDATA No Fully qualified probe name. (ex: "L999.K1.V1.A9F-S11") If this attribute is used, the scores attribute must contain exactly one score.
scores CDATA Yes The results of the SSO test, specified as one string (ex: "118111100181")

Children: none


Element: ssp

Description:
Specifies an SSP test that was done. Scores are required, along with a reference for resolving what SSPs correspond to the list of scores. Only one of "ref-id", "name", or "nmdp-refid" may be given.

Attributes:
Name Type Required? Description
ref-id IDREF No Internal XML reference to a typing-test-names element contained in this document.
nmdp-refid CDATA No ID of kit registered with NMDP. The cardinal sequence numbers of the registered SSPs in the kit will determine the score order.
name CDATA No Fully qualified SSP name. (ex: "L999.K1.V1.SSP12345") If this attribute is used, the scores attribute must contain exactly one score.
scores CDATA Yes The results of the SSP test, specified as one string (ex: "118111100181")

Children: none


Element: sbt

Description:
Specifies an SBT test that was done. The result of the test (the DNA sequence) is given in the child "sequence" element.

Attributes:
Name Type Required? Description
name CDATA Yes Fully qualified name of the SBT test (ex: "L999.K1.V1.SBT54321")
score CDATA Yes Result of primer amplification used for this test. This is usually '8', but may be '1' in which case no amplification happened and no sequence is likely to have been obtained.

Children:
sequence 1


Element: sequence

Description:
The sequence element contains the DNA sequence obtained from an SBT test. Primary (A, C, G, T) and wildcard nucleotides (M, R, W, S, Y, K, V, H, D, B, X, N) may be used (ex: "<sequence>CCGGAGTATTGGGACCAGGAGACACGGAATATGAAGGCCCAC</sequence>")

Attributes:
Name Type Required? Description

Children:
PCDATA


Element: typing-test-names

Description:
The typing-test-names element specifies a list of test names internally referenced by an sso element or an ssp element. It wraps a list of "typing-test-name" elements.

Attributes:
Name Type Required? Description
ref-id ID Yes XML ID reference unique in this document.

Children:
typing-test-name 1 or more


Element: typing-test-name

Description:
A typing-test-name element specifies a test name contained in a referenced "typing-test-names" list.

Attributes:
Name Type Required? Description
name CDATA Yes Fully qualified test name (ex: "L999.K1.V1.A9F-S11", "L999.K1.V1.SSP12345")

Children: none


Element: property

Description:
A property is a generic name-value pair

Attributes:
Name Type Required? Description
name CDATA Yes Name of this property
value CDATA Yes Value of this property

Children: none