ItemDef

An ItemDef describes a type of item that can occur within a study. Item properties include name, datatype, range, or codelist restrictions, and several other properties.

Element Name	ItemDef
Parent Element(s)	MetaDataVersion
Element XPath(s)	/ODM/Study/MetaDataVersion/ItemDef
Element Textual Value	None
Attributes	OID, Name, DataType, Length, DisplayFormat, VariableSet, CommentOID
Child Elements	(Description?, Definition?, Question?, Prompt?, CRFCompletionInstructions?, ImplementationNotes?, CDISCNotes?, RangeCheck, CodeListRef?, ValueListRef?, Co ding, Alias*)
Usage/Business Rules	Business Rule(s): There must be an ItemDef element for each unique ItemOID attribute value in the study. Other Information: The Question element contains the text shown to a human user when prompted to provide data for this Item. The Alias element may be added to represent an alternative name for the ItemDef, for example setting with Context="SASFieldName" for SAS dataset variable names. The RangeChecks constrain the acceptable values for items of this type. The CodeListRef (if present) constrains the acceptable values for items of this type to be members of the referenced codelist. The Origin attribute in ODM v1.3 has been replaced by an Origin element attached to the ItemRef. This allows a different Origin to be specified depending on where the Item is used.

ODM-68 - Getting issue details... STATUS

Attribute	Schema Datatype or Enumeration	Usage	Definition	Business Rules
OID	oid	Required	Unique identifier for the ItemDef element.	The OID attribute value must be unique within the Study/MetaDataVersion.
Name	name	Required	Human readable name for the ItemDef.	The Name attribute must be unique within the set of ItemDef elements within a Study/MetadataVersion.
DataType	(text \| integer \| decimal \| float \| double \| date \| time \| datetime \| string \| boolean \| double \| hexBinary \| base64Binary \| hexFloat \| base64Float \| partialDate \| partialTime \| partialDatetime \| durationDatetime \| intervalDatetime \| incompleteDatetime \| incompleteDate \| incompleteTime \| URI )	Required	Specification of the allowable values and the intended use of the corresponding value elements.	A receiving system is expected to preserve the value and precision of the data.
Length	positiveInteger	Optional	Specifies the number of characters allowed for the ItemData/Value when it is represented as a text.	Systems that import ClinicalData must be able to process and store all text string with length less than or equal to N.
DisplayFormat	text	Optional	Display format supports data visualization of numeric float and date values.
VariableSet	text	Optional	ADaM variable set, e.g. Dose, Analysis Parameter, Treatment Timing.
CommentOID	oidref	Optional	Reference to a CommentDef with sponsor provided information related to this ItemDef,	Must match the OID attribute of a CommentDef element within in this Study/MetaDataVersion. The CommentOID attribute references a CommentDef element that may carry submission information as described in the SDTM (available at https://www.cdisc.org/standards/foundational/sdtm).

Note: The DataType attribute specifies the allowable values and the intended use of the corresponding value elements, but not necessarily how systems will store them. The receiver is expected to preserve the value and precision of the data and can use the ODM-specified datatype to determine the best representation of the data in their system.

Note: In ODM v1.3.2 the Length and SignificantDigits attributes were used to express the requirements for the receiving system. In ODM v2.0 the meaning of the Length attribute remains the same for the text and string datatypes, but has been changed for the numeric datatypes and is now optional for all datatypes. The SignificantDigits attribute has been removed. If DataType is text or a string and the Length attribute is provided, Length=N indicates that the receiving system be able to process and store all text string values of length less than or equal to N. All characters are allowed in text string values.

When the Length attribute is provided, Length=N means that when a value of an item is represented as a text, its length must be less or equal to N. Length is a statement about an item's data values, not the number of characters used to represent these values in value elements. For example, the character "<" might be represented as "&lt;".

There are 3 datatypes available for floating-point values: decimal, float, and double. The decimal datatype represents a subset of the real numbers, which can be represented by decimal numerals. This datatype should be used for items with floating-point values when the number of decimal places is known in advance. For the decimal datatype, Length=N means that the number of characters required to represent the full numeric value, including the decimal character, must be less than or equal to N.

In cases where the number of decimal places is not known in advance or is not important, either float or double datatypes should be used. Both of these are patterned after the IEEE floating-point types. DataType=float corresponds to 4-byte single-precision floating-point type, with the basic value space consisting of the values m x 2^e, where m is an integer whose absolute value is less than 2²⁴, and e is an integer between -149 and 104, inclusive. DataType=double corresponds to 8-byte double-precision floating-point type, with the basic value space consisting of the values m x 2^e, where m is an integer whose absolute value is less than 2⁵³, and e is an integer between -1075 and 970, inclusive.

Note: Data characters that are not included in the encoding character set for a particular ODM file must be represented using XML entities or character references. For example, Æ could be represented as "Æ".

Note: In the ODM model, all internal keys are assumed to be unchangeable. This was done to make the audit trail issues work: If the SubjectKey in the model were the actual external subject identifier (or randomization ID) of a patient, and that value is sent incorrectly in one ODM file, there would be no way to correct the mistake in a follow-up file. In doing this, we intend that the external subject keys (and other externally visible key variables) should be defined as Items in the metadata. Thus they can be modified through normal modify/audit mechanism. Although this solves the problem of supporting modification of study keys, it leaves the user without a way to identify which ItemDefs have special meaning or what the meaning is. The most obvious place where this is a problem is in matching up patients when loading data from an external source. If you cannot find the patient ID, how do you do the matching?

The answer is to create an Alias child element of ItemDef to provide an alternative name by, for example, setting with Context="SDSVarName" and Name="USUBJID". Setting Context to SDSVarName is a convention that can be used to tag the Item with a business meaning. Rather than try to enumerate all possible meanings in the ODM model, the Data Exchange Standards Team thought it best to rely on the set of variable names defined in the CDISC SDTM; this list covers the core variables used in managing clinical data. Software that is processing an ODM-compliant XML instance can therefore use specific Names when Context="SDSVarName" to identify standard, frequently used variables. The use of this Context value is restricted to variables defined in the SDTM model. In tagging a variable, you are identifying it as matching the SDTM definition for that variable. A partial list of commonly used values includes:

STUDYID (Study Identifier Unique within a Submission)
USUBJID (Study Identifier Unique within a Submission),
SUBJID (Subject Identifier Unique within a Study),
SITEID (Unique Identifier for a study Site)
SEX (Sex or Gender, coded value),
VISITNUM (Clinical encounter Number)
VISIT (Protocol-defined description of clinical encounter),
VISITDY (Planned study day of VISIT)

See the SDTM and SDTMIG for more information about SDTM variables.

Example:

ItemDef

<!-- The "Length" is the character length as how the value is stored in the database, i.e. "F" or "M" --> 
<ItemDef Name="SEX" OID="IT.SEX" DataType="text" Length="1">
  <Description>
      <TranslatedText xml:lang="en" Type="text/plain">Sex/gender of the subject</TranslatedText>
  </Description>
  <!-- The question as will be presented to the user (e.g. CRF) -->
  <Question>
      <TranslatedText xml:lang="en" Type="text/plain">Sex</TranslatedText>
      <TranslatedText xml:lang="fr" Type="text/plain">Genre</TranslatedText>
      <TranslatedText xml:lang="de" Type="text/plain">Geschlecht</TranslatedText>
      <TranslatedText xml:lang="ko" Type="text/plain">성별</TranslatedText>
  </Question>
  <CodeListRef CodeListOID="CL_SEX"/>
  <Alias Context="SDTM" Name="SEX"/>
</ItemDef>

Page tree

ItemDef