Clinical Data Interchange Standards Consortium

Specification for the Operational Data Model (ODM)

Version 1.2
Source File: ODM-1.2.5.adtd
Last Update: 19 Dec 2003 10:10 AM

Copyright © CDISC 2003 This document is the property of CDISC Inc. This document can be freely used and reproduced without limitation as long as (1) it is not modified, and (2) the entire copyright statement is included in the copy. Modifications to this document can only be made with written consent of CDISC Inc.

An official copy of this document is available at http://www.cdisc.org/models/odm/v1.2/ODM1-2-0.html.

Table of Contents

1   Introduction (non-normative)
2   General Issues
2.1   Content of the Standard
2.2   File Conformity
2.3   System Conformity
2.4   Vendor Extensions
2.5   Changes from Previous Versions (non-normative)
2.6   Entities and Elements
2.7   Clinical Data Keys
2.8   Single Files and Collections
2.9   Transactions
2.10   Element Ordering
2.11   Element Identifiers and References
2.12   Syntax Notation
2.13   Data Formats
3   General Elements
3.1   ODM
3.2   Study
3.3   GlobalVariables
3.4   StudyName
3.5   StudyDescription
3.6   ProtocolName
3.7   BasicDefinitions
3.8   MeasurementUnit
3.9   Symbol
3.10   TranslatedText
4   Metadata Elements
4.1   MetaDataVersion
4.2   Include
4.3   Protocol
4.4   StudyEventRef
4.5   StudyEventDef
4.6   FormRef
4.7   FormDef
4.8   ItemGroupRef
4.9   ItemGroupDef
4.10   ItemRef
4.11   ItemDef
4.12   Question
4.13   ExternalQuestion
4.14   MeasurementUnitRef
4.15   RangeCheck
4.16   CheckValue
4.17   ErrorMessage
4.18   CodeListRef
4.19   Role
4.20   Alias
4.21   CodeList
4.22   CodeListItem
4.23   Decode
4.24   ExternalCodeList
4.25   ArchiveLayout
4.26   ImputationMethod
4.27   Presentation
5   Administrative Elements
5.1   AdminData
5.2   User
5.3   LoginName
5.4   DisplayName
5.5   FullName
5.6   FirstName
5.7   LastName
5.8   Organization
5.9   Address
5.10   StreetName
5.11   City
5.12   StateProv
5.13   Country
5.14   PostalCode
5.15   OtherText
5.16   Email
5.17   Picture
5.18   Pager
5.19   Fax
5.20   Phone
5.21   LocationRef
5.22   Certificate
5.23   Location
5.24   MetaDataVersionRef
5.25   SignatureDef
5.26   Meaning
5.27   LegalReason
6   Reference Data Elements
6.1   ReferenceData
7   Clinical Data Elements
7.1   ClinicalData
7.2   SubjectData
7.3   StudyEventData
7.4   FormData
7.5   ArchiveLayoutRef
7.6   ItemGroupData
7.7   ItemData
7.8   Annotation
7.9   Comment
7.10   Flag
7.11   FlagValue
7.12   FlagType
7.13   Signature
7.14   UserRef
7.15   SignatureRef
7.16   DateTimeStamp
7.17   CryptoBindingManifest
7.18   AuditRecord
7.19   ReasonForChange
7.20   SourceID
7.21   InvestigatorRef
7.22   SiteRef
7.23   Association
7.24   KeySet
8   Digital Signatures
8.1   ds:Signature
9   Element Index (non-normative)
10   Attribute Index (non-normative)

1   Introduction (non-normative)

The Operational Data Model (ODM) is a vendor neutral, platform independent format for interchange and archive of data collected in clinical trials. The model represents study metadata, data and administrative data associated with a clinical trial. Only the information that needs to be shared among different software systems during a trial, or archived after a trial is included in the model.

This is version 1.2 of the ODM. Version 1.2 contains a number of new features that improve the functionality, security and convenience of the model. Descriptions of the new features have been incorporated into the text of this document. A separate document Version 1.2 New Features provides a summary of the new features for users of earlier versions of the model.

Beginning with version 1.2, both an XML Schema and a DTD are provided with the ODM model. The XML schema should be considered definitive. The DTD is informational and is provided for backward compatibility.

Clinical data management systems vary significantly in the information they store and the rules they enforce. The ODM model has been designed to represent a wide range of study information so as to be compatible with most existing clinical data management systems. Systems that do not have all of the features represented by the ODM model may still be ODM compatible as long as they comply with the conformity rules provided in the section on System Conformity.

The ODM has been designed to be compliant with guidance and regulations published by the FDA for computer systems used in clinical trials. This document is intended to be both the formal specification of the ODM and a user guide for those involved in transferring or archiving of clinical data using the model.

2   General Issues

2.1   Content of the Standard

This document contains the entire CDISC ODM standard. Most of the text in this standard expresses requirements on systems that read or write ODM files. However some of the text is commentary or examples. All such "unofficial" text is segregated into paragraphs or sections prominently marked as non-normative, a note, or an example.

2.2   File Conformity

An XML file conforms to this standard only if it satisfies all the criteria detailed in this standard. These criteria include both syntactic constraints and semantic ones.

The syntactic constraints are

1. The ODM file must be a well-formed XML file. See the XML standard for details.
2. The ODM file must conform to the XML Namespace standard. See the XML Namespace standard for details.
3. The ODM file must contain only elements and attributes defined in this standard, and satisfy the rules about element nesting and the formats of attribute values and element bodies.
4. The ODM file must contain a prolog and a single (top-level) ODM element.
5. The XML system identifier for the version 1.2 ODM file format is "http://www.cdisc.org/dtd/ODM-1.2.dtd".

Example:

<?xml version="1.0" encoding="ISO-8859-1"?>
<ODM ...>
...
</ODM>

The semantic constraints are expressed throughout the rest of this document.

Accompanying this standard is an automatically generated XML Schema file and an automatically generated DTD file, both of which express certain of the syntactic constraints. These files can be used (along with a validating XML parser) to test that an ODM file is syntactically valid. However, syntactic validity is only part of total correctness.

The XML Schema should be considered definitive, and the DTD informational. This is because the Schema captures more of the syntactic constraints, and because it is compatible with XML namespaces.

2.3   System Conformity

A computing system that processes information in ODM format can claim conformance to this standard only if it obeys the following rules.

1. Generated ODM files must satisfy all the correctness rules in this standard, both syntactic and semantic.
2. A receiving system must be able to read any ODM file that satisfies all the correctness rules in this standard, both syntactic and semantic.
3. Information included in generated ODM files must be accurate according to the rules of this standard.
4. A receiving system must interpret information read from an ODM file accurately according to the rules of this standard.
5. Generated ODM files need not include information that is not normally handled or stored by the generating system.
6. A receiving system may selectively ignore information read from an ODM file if that information is not normally handled or stored by the receiving system.
7. A receiving system may constrain the range of data values, keys, names, and so on, that it is capable of handling or storing.
8. All system limitations (rules 5 thru 7) must be documented.
9. If conformity is dependent on certain modes or settings, this must also be documented.

2.4   Vendor Extensions

Clinical data systems frequently store more information than can be expressed in the ODM model. The exact nature of such additional information will vary from system to system. Thus, there will be pressure for proprietary extensions to the model.

Vendor extensions to the ODM model are acceptable as long as

1. The vendor supplies a XML Schema or DTD specification fully describing their extended ODM format.
2. Extended ODM files reference the proper extension Schema or DTD.
3. The extension adds new XML elements and attributes, but does not render any standard ODM file obsolete. That is, all ODM files that are correct under this standard are acceptable as extended ODM files.
4. All new element and attribute names use distinct XML namespaces to insure that there are no naming conflicts with other vendor extensions.
5. The file obtained (from an extended ODM file) by removing all vendor extensions must be a meaningful and accurate standard ODM file.
6. ODM files free of any vendor extensions can be generated upon request.

Vendor extensions should never be used for information that can be expressed using other ODM elements.

Note: Vendor extensions that carry generally useful information should be brought to CDISC's attention for possible future standardization.

Note: It is easy to write a filter that removes all non-standard attributes and elements from an extended XML file, either as a stand-alone program or as part of normal input processing. Receiving systems are encouraged to be forgiving when encountering extended ODM files.

2.5   Changes from Previous Versions (non-normative)

ODM 1.2 is a pure extension of ODM 1.1. Elements and attributes have been added, but none have been removed. Elements and attributes that are present in both versions have the same interpretations. However, there are two ways in which an ODM 1.1 file will fail to be a perfect ODM 1.2 file:

1. An ODM 1.1 file will reference the ODM 1.1 DTD, while an ODM 1.2 file will reference the ODM 1.2 Schema (or DTD).
2. ODM 1.1 files can contain date/time values that violate the ISO 8601 and XML Schema standards. Date/time values in ODM 1.2 files must conform to these standards. (Applications that read ODM files are urged to be forgiving on this point.)

Note: An XSL preprocessor can be used to fix any non-standard dates that might occur in an ODM 1.1 file, producing a fully correct ODM 1.2 file.

The elements that have been added to ODM 1.2 are

• Alias
• Association
• ImputationMethod
• KeySet
• ds:Signature

The attributes that have been added to ODM 1.2 are

• ODMVersion, Originator, SourceSystem, SourceSystemVersion (in ODM)
• Description (in MetaDataVersion)
• Purpose (in ItemGroupDef)
• KeySequence, ImputationMethodOID, Role, RoleCodeListOID (in ItemRef)
• EditPoint, UsedImputationMethod (in AuditRecord)

The BasicDefinitions element in Study is now optional. The values of the sasName format have been expanded and augmented with a sasFormatName format.

In ODM 1.2, a small number of elements and attributes are labeled as deprecated. This means that that element or attribute is still legal, but that its use is discouraged. Deprecated features may be removed in some future version of this standard.

The deprecated elements and attributes are the Role element, the CryptoBindingManifest element, and the Role attribute (in ItemGroupDef).

2.6   Entities and Elements

The ODM model assumes that a study's clinical data will consist of several kinds of entities. These include subjects, study events, forms, item groups, items, and annotations.

An item is an individual clinical data item, such as a single systolic blood pressure reading. Items are collected together into item groups.

An item group is a closely related set of items that are generally analyzed together. (Item groups are sometimes referred to as "records" and are associated with "panels" or "tables".) Item groups are aggregated into forms.

A form is analogous to a page in a paper CRF book or electronic CRF screen. A form generally collects a set of logically and temporally related information. A series of forms is collected as part of a study event.

A study event is a patient visit or some other data-collection event. Each study event belongs to some patient in the study.

A subject is a patient participating in the study.

An annotation is a comment applied to a subject, study event, form, item group, or item. Annotations can also be applied to pairs of entities.

The metadata of a study describes the types of study events, forms, item groups, and items that are allowed in the study. The metadata entities include StudyEventDefs, FormDefs, ItemGroupDefs, and ItemDefs.

A StudyEventDef describes a particular type of study event (mostly by listing the types of forms it can contain).

A FormDef describes a particular type of form.

An ItemGroupDef describes a particular type of item group.

An ItemDef describes a particular type of item.

The clinical data of a study will typically have many actual study events corresponding to each StudyEventDef, many actual forms corresponding to each FormDef, and so on.

An ODM file (like any XML file) consists of a tree of elements. The clinical data elements in an ODM file represent either the state of a clinical entity or a change to the state of that entity. These elements include the SubjectData, StudyEventData, FormData, ItemGroupData, ItemData, and Annotation elements.

Each such element contains key attributes that identify the data entity that it provides information for. Frequently, many data elements will correspond to a single data entity. This can occur when a series of updates are being applied to a single entity, or when an audit trail is being represented.

Similarly, there are XML elements corresponding to metadata entities.

Note: Not all clinical studies organize their data into visits or forms. For such a study, it is appropriate to have a single common study event per subject, and/or a single common form per study event.

2.7   Clinical Data Keys

There are two kinds of keys in the ODM model: internal and external. Internal keys are used to designate entities within the model, and to allow cross-references between entities within (and between) ODM files. Internal keys are not for human use, and are assumed to be unchanging. Internal keys include subject keys, element OIDs, and repeat keys.

To fully identify a clinical data entity, the following internal keys are needed:

Kind of Entity	Identifying Keys
study	StudyOID
subject	above plus SubjectKey
study event	above plus StudyEventOID and StudyEventRepeatKey
form	above plus FormOID and FormRepeatKey
item group	above plus ItemGroupOID and ItemGroupRepeatKey
item	above plus ItemOID
annotation	keys for the annotated entity plus SeqNum

A StudyOID uniquely identifies a study. A SubjectKey uniquely identifies a subject within a study. SubjectKeys cannot be used to identify a subject across studies.

A StudyEventOID uniquely identifies a StudyEventDef within a study. However there may be several study events of a particular type for a given subject. Thus, to fully identify a particular study event, we need the StudyOID, the SubjectKey, the StudyEventOID, and a StudyEventRepeatKey.

Each form belongs to a study event, and can be identified (within that study event) by a FormOID (which gives its type) and a FormRepeatKey.

Each item group in clinical data belongs to a form, and can be identified (within that form) by an ItemGroupOID (which gives its type) and an ItemGroupRepeatKey.

Other items groups are reference data, and can be identified solely by an ItemGroupOID and an ItemGroupRepeatKey.

Each item belongs to an item group. However items of a given type are not allowed to repeat within the item group. Thus, only the ItemOID is needed to uniquely identify an item within its item group.

External keys are any keys used by clinical personnel. These include subject randomization codes, site codes, and so on. In the ODM model, external keys are represented as if they were clinical data. Thus external keys can be changed as needed, and are subject to normal auditing processes.

2.8   Single Files and Collections

An ODM document (file) can be viewed as a set of instructions telling how to modify a target database so that it can be brought into alignment with a source database. A single ODM document could contain all the information about the source database -- all the subjects, all the metadata, all the clinical data, and all the changes to each item of clinical data. However, it's not always convenient to create such a large document. So we allow a series of ODM files to incrementally provide this information.

Each ODM document has a FileOID attribute (see the ODM element). The FileOID should uniquely identify the document.

An ODM document can also have a PriorFileOID attribute. This attribute gives the FileOID of the immediately preceding file in a series. Thus, a collection of files linked by PriorFileOID can be used to incrementally describe a source database. (Of course, the first document in the series has no PriorFileOID attribute.)

Data in one file of a series is allowed to depend on definitions contained in an earlier file in the series. If a file contains either ReferenceData or ClinicalData then that file must either contain the necessary metadata definitions to interpret that data directly, or there must be a previous file in the series that contains these definitions. Similarly, if a file contains ClinicalData, the file must either contain the administrative data referenced in the audit and signature records, or there must be a previous file in the series that contain that data.

A tree-structured collection of ODM files (where more than one file references the same prior file) is also allowed.

An ODM document (or collection) can contain information on more than one study. To simplify the discussion, we will occasionally write as if only one study was present. If a file (or collection of files) contains multiple studies, the rules described below should be applied to each of the studies independently.

Note: The FileOID identifies the document content. It does not change just because the document is copied.

Note: FileOIDs should be universally unique if at all possible. One way to ensure this is to prefix every FileOID with an Internet domain name owned by the creator of the ODM file or database (followed by a /). For example, FileOID="BestPharmaceuticals.com/Study5894/1" might be a good way to denote the first file in a series for study 5894 from Best Pharmaceuticals.

Note: Similarly, StudyOIDs should be universally unique if at all possible. For example, StudyOID="BestPharmaceuticals.com/Study5894".

Note: Applications may need to store ODM documents that they receive and later retrieve them based on their FileOID. In particular, interpreting a new file in a series will require locating the prior file by its FileOID. One easy way to do this is to use the (possibly transformed) FileOID as part of the file name itself. For example, the ODM document mentioned above could be stored in ...\BestPharmaceuticals.com\Study5894\1.xml.

Other File Attributes

As implied above, most ODM documents will contain only part of the total information (current and historical) held in the source database.

The information that is sent in a given document can vary along several dimensions. Some examples of the contents of a document are:

• just metadata,
• just clinical data,
• a series of updates of a single value for a single subject,
• the current state of the entire study,
• the current state of a subset of a study (particular subjects, particular forms, etc),
• the changes to the study since the last communication, or
• a full history of all changes ever made to the study.

Because of this variability, it is also important that each document describe itself, so that the consumer of the document knows what to expect of it. To address these needs, the ODM element has several attributes for describing the current document.

The CreationDateTime attribute tells when the ODM document was created. In contrast, the AsOfDateTime attribute tells when the document content was accurate. This is of particular importance when a series of files is used to give an evolving view of a changing database.

The FileType and Granularity attributes allow the document sender to define the scope, across time and data, that a particular document spans. The Archive attribute allows the sender to assert that the contents of the document meet a specific set of criteria that qualifies it as an electronic record as defined in the FDA 21 CFR 11 Guidance. Finally, the Description attribute provides the sender a text string in which to give details, as elaborately as necessary, to supplement the other attributes in describing the document. This section details the values these attributes can take, and discusses the use of the values in a single document and in a series of documents.

FileType

A document's FileType must be either Snapshot or Transactional. A Snapshot document shows how to re-create the current state of the source database with respect to the included data, but does not show how it got to be in that state over time. A Transactional document shows, for each included entity, both the latest state of the source database, and (optionally) some prior states of that entity in the source database. A Snapshot document contains only Insert transactions for clinical data, and must contain exactly one Insert instruction per data point, while a Transactional document may contain more that one TransactionType instruction, of any type, per clinical data element. When you process an Transactional document, the rules for ordering a set of transactions for a single data point are those described in the section on Element Ordering.

Granularity

A document's Granularity is intended to give the sender a shorthand way to describe the breadth of the information in the document, for certain common types of documents. Here are the intended meanings of these categories:

Category	Document contains
All	Any and all types of data and metadata
Metadata	Metadata only
AdminData	Admin data only
ReferenceData	Reference data only
AllClinicalData	Clinical data only
SingleSite	Clinical data for a single site only
SingleSubject	Clinical data for a single subject only

If these shorthand categories are not sufficient, use the document's Description attribute to give details.

Archival

The Archival attribute is optional. If set, its value must be "Yes".

Archival=Yes states that this file (or collection of files) is intended to meet the requirements of an electronic record as defined in 21 CFR 11. More specifically, the file (or set of files) must clearly establish a complete and non-redundant set of insertions, updates, and deletions of data values with full auditing and signature information (if available).

Archival=Yes requires

• The current file must be Transactional.
• If the current file is one of a collection, all other files in the collection must be both Archival and Transactional.
• The set of transactions must be both complete and non-redundant within the file or collection of files. In particular each file must contain:
• no transactions that have an audit date of prior to the AsOfDateTime of its PriorFile (if any),
• all transactions up to its AsOfDateTime. (For Granularity=All, this means all transactions in the study. See Granularity for the meaning of "all" for other Granularity settings),
• all AuditRecord and Signature information available in the source database, and
• no Upsert transactions.

2.9   Transactions

Each data element has an optional TransactionType attribute. This attribute can be one of Insert, Update, Remove, or Upsert.

A TransactionType of Insert means that the data entity is new (does not currently exist in the study) and must be added to the study data along with all the properties provided. It is an error if the data entity already exists, or if the data entity's parent does not exist.

A TransactionType of Update means that the data entity already exists and must be modified to have the new properties provided. Properties not mentioned are not modified. It is an error if the data entity does not exist.

A TransactionType of Remove means that the data entity already exists and must be deleted along with all its properties and children. It is an error if the data entity does not exist.

Note: The use of the word "delete" above does not imply that all record of the data entity is expunged, just that the next transaction on that entity (if any) must be an Insert rather than Update or Remove.

A TransactionType of Upsert is the same as Update if the data entity exists, and the same as Insert otherwise.

Note: Upsert allows the sender to ignore whether the data entity exists or not. (A capability that may be needed by certain data collection systems.) This capability is potentially dangerous and may be removed in future versions of this standard.

A TransactionType of Context means that the data is explicitly being resent for context purposes only. An example of this would be sending an ItemGroup containing demographic data every time (with a TransactionType of Context) to permit matching and checking of Patient IDs between the sender and receiver systems.

A child element that does not specify its own TransactionType inherits the TransactionType of its parent. The TransactionType of a top level data element must be explicit for Archive and Incremental transfers.

Transaction processing proceeds in the order in which data elements appear in the ODM document. If two transactions for an entity are included in an ODM document, they are applied in the order in which they appear.

If an entity has a TransactionType of Remove, the only TransactionType its descendants can have is Remove (they can also have no TransactionType, and thus inherit the Remove type). A program that processes ODM files should look ahead far enough to determine if an element breaks this rule before processing the element.

2.10   Element Ordering

The elements in an ODM file that apply to a single entity must occur in temporal order. That is, the transactions on each entity are applied in the order in which that entity's elements occur in the file, and Signatures and AuditRecords must occur in increasing value of their DateTimeStamps.

In general, the elements for distinct entities do not have to be ordered relative to one another. However, when an entity is signed, all transactions on that entity that occurred before the time of the signature must be present earlier in the same ODM file or in a prior ODM file in a linked series.

All the DateTimeStamps in a file must precede the CreationDateTime of that file.

In a linked series of ODM files, the AsOfDateTimes of those files must occur in temporal order, and the DateTimeStamps in each file must be later than the AsOfDateTimes of the prior file.

A data entity (like a form) can be represented as a series of data elements. These elements can contain data for disjoint parts of the entity (properties and children), sequential changes to the same parts, or a mixture of the two.

In a study, the initial or default value of any clinical data is assumed to be NULL. Thus it is not necessary to include NULL valued items in a Snapshot transfer. Neither is it necessary to include a NULL value as the first in a series of insertions and updates of an item.

Systems that generate ODM files should attempt to minimize the number of elements in such files. Thus, if two elements for the same entity can be merged into one without changing the semantics of the events described (and without violating any of the ordering rules), the merged version is recommended. Similarly, unnecessary elements should be omitted.

2.11   Element Identifiers and References

In the ODM model, there are many instances where one element needs to reference another -- both within the same file and across files within a series of ODM documents. To accomplish this, the target element is given a unique "name" (its OID). All elements that need to reference that target element just use its OID.

Example: Say we have an item definition (ItemDef) called "Systolic Blood Pressure". We set the OID attribute of this ItemDef to "SBP". Then any specific instance of that data item (ItemData) can link back to the definition by setting its own ItemOID attribute to "SBP".

The OIDs used have to be unique, but only within certain contexts. Here are the uniqueness rules:

• The OID for a Study, User, Location, or SignatureDef must be unique within a related series of ODM documents.
• The OID for a MeasurementUnit, MetaDataVersion, StudyEventDef, FormDef, ItemGroupDef, ItemDef, CodeList, ImputationMethod, or Presentation must be unique within a single study (within a related series of ODM documents). It is permitted to reuse OIDs for these elements in different studies.
• The OID for an ArchiveLayout must be unique within a single form definition (within a study). It is permitted to reuse OIDs for this element in different form definitions.

We explicitly allow two metadata elements (StudyEventDef, FormDef, ItemGroupDef, ItemDef, CodeList, ImputationMethod, or Presentation) to have the same OID if these elements are of the same kind and are in different MetaDataVersions. The meaning is that these elements represent two versions of the same metadata entity. The later one is an update of the earlier. (See Metadata Elements for more details.)

Whenever an element uses an OID to reference another element, the referenced element must occur within the same document as the reference or within a prior document in a linked series. Thus, the referenced element can always be found by tracing back the PriorFileOID links.

Note: The fact that OID references need to cross files prevents the use of standard XML ID values (which are solely within file references). This is highlighted in our element definitions by using the types oid and oidref instead of ID and IDREF.

Note: The above reference rules imply the following.

• You cannot send a reference to an OID value unless that OID value has been defined, either in the current document, or in a prior document within the series.
• If a definition identified by an OID has changed, the change in its definition must be transmitted before or in the document in which the changed definition is referenced.
• A document that initiates a series must contain all definitions that it references.
• A Transactional document must include any supporting definitions that are new or changed relative to its prior document. For example, suppose that document B3207 includes references to item definition X, and that a codelist constraint has been added to X since B3207's predecessor document. In that case, B3207 must also include a MetaDataVersion element (with an new OID) containing an updated definition of item X.

2.12   Syntax Notation

The syntax of each XML element is defined in two ways. First, it is defined informally as follows:

Element-Name

Body:

content-specification

Attributes:

attribute-name data-format optionality semantic-details
...

The content specification can be "EMPTY", a data format name, or an element group. EMPTY means that this element has no body (nested content). A data format name means that the body can be any text string matching the named format. An element group means that the named elements can be directly nested within this element.

An element group consists of one or more element names (or element groups) enclosed in parentheses, and separated with commas or vertical bars. Commas indicate that the elements (or element groups) must occur in the XML sequentially in the order listed in the group. Vertical bars indicate that exactly one of the elements (or element groups) must occur. An element or element group can be followed by a ? (meaning optional), a * (meaning zero or more occurrances), or a + (meaning one or more occurrances).

Attributes are listed in tabular form, one attribute per row, including the attribute's name, its data format, its optionality, and possibly some semantic details. All attributes are required unless the optionality column contains "(optional)".

Second, the element's syntax is defined formally using XML Schema. The complete XML Schema for ODM consists of the following header plus all the individual element definition.

XML Schema:

 
<xs:schema
 targetNamespace="http://www.cdisc.org/ns/odm/v1.2"
 xmlns="http://www.cdisc.org/ns/odm/v1.2"
 xmlns:xs="http://www.w3.org/2001/XMLSchema"
 xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
 elementFormDefault="qualified"
 attributeFormDefault="unqualified"
 >
 <xs:import namespace="http://www.w3.org/XML/1998/namespace"
 schemaLocation="http://www.w3.org/2001/03/xml.xsd"/>
 <xs:import namespace="http://www.w3.org/2000/09/xmldsig#"
 schemaLocation="http://www.w3.org/TR/xmldsig-core/xmldsig-core-schema.xsd"/>

2.13   Data Formats

All attribute values and some element bodies are text strings. These strings are defined by data format. Each data format specifies the allowable form of the string, the corresponding XML Schema datatype, and the intended use of the value. The ODM data formats are

Format Name	Schema Datatype	Allowed String Pattern
integer	xs:integer	-?digit+
float	xs:decimal	-?digit+(.digit+)?
date	xs:date	YYYY-MM-DD
time	xs:time	hh:mm:ss(.n+)? ((+|-)hh:mm)?
datetime	xs:dateTime	YYYY-MM-DD T hh:mm:ss(.n+)? ((+|-)hh:mm)?
text	xs:string	any sequence of characters
oid	xs:string	any sequence of characters
oidref	xs:string	any sequence of characters
value	xs:string	any of the above
subjectKey	xs:string	any sequence of characters
repeatKey	xs:string	any sequence of characters
name	xs:string	any sequence of characters
sasName	xs:string	( letter | _ )( letter | digit | _ )*
sasFormat	xs:string	( letter | _ | $ )( letter | digit | _ | . )*
fileName	xs:string	( letter | digit | _ | . )+
languageTag	xs:language	LL (-CC)* (see below)

Numbers (integer and float) are represented in base 10. Floats are allowed to have fractional parts.

Note: Certain integer attributes (KeySequence, OrderNumber, and SeqNum) are used to define an order among related entities. For these attributes, we recommend using consecutive integer values starting at 1.

A text value is any sequence of Unicode characters. When embedded in ODM files, text strings must be represented using the XML quoting rules.

Dates are represented in the Gregorian calendar. The year (YYYY) ranges from 0001 to 9999. The month (MM) ranges from 01 to 12. The day (DD) ranges from 01 to 31. ODM dates are a slightly restricted form of the XML Schema datatype date: no timezone specification is allowed.

Times are clock readings within a 24 hour period. The hour (hh) ranges from 00 to 23. The minutes (mm) and the seconds (ss) range from 00 to 59. The optional fractional part (.nnn) expresses fractional seconds. ODM times are a slightly restricted form of the XML Schema datatype time: only the ±hh:mm form of timezone is allowed.

Datetimes combine a date, a time and (optionally) a timezone. ODM datetimes are a slightly restricted form of the XML Schema datatype dateTime: only the ±hh:mm form of timezone is allowed.

Dates, times, and datetimes are to be interpreted as local clock readings at the place the data was collected. In a datetime, the ±hh:mm is the offset in hours and minutes to add to (or subtract from) Universal Time to get the local clock reading at the time the data was collected. A missing timezone specification means that the relationship between the local clock and Universal Time is not known.

Example: 3:14 pm on 3 January 2001 in Chicago (6 timezones west of Greenwich, standard time) would be represented as "2001-01-03T15:14:00-06:00". 3.5 seconds after midnight on the morning of July 20th 2001 in Chicago (daylight time) would be represented as "2001-07-20T00:00:03.500-05:00".

Note: The above formats for dates, times, and datetimes are compatible with ISO 8601.

Note: Dates and times are complete, not partial. Partial date and time types may be added in the future.

Note: ODM 1.1 allowed a timezone specification of -99:99 to designate "no timezone information." This is no longer allowed in ODM 1.2. However, applications that process both versions of ODM should be forgiving.

An oid (OID) is a string that uniquely identifies an element (see Element Identifiers and References for details). An oidref is the use of an OID to reference an element (as opposed to the defining occurrence of that OID). OIDs and oidrefs are non-empty strings.

The value format is simply the union of all the preceding formats: integer, float, date, time, datetime, text, oid, oidref. The value format is used when the specific value type is determined by metadata rather than by the immediately containing element.

A subjectKey or repeatKey helps designate a clinical data entity (see Clinical Data Keys). They are non-empty strings.

A name is intended to be a human readable name for some entity. Names are non-empty strings.

A sasName (or sasFormat) is any valid SAS Version 5 Transport Format name (or format). These are limited to 8 characters in length.

A fileName designates a file. File names are system dependent, and expressed relative to the directory that contains the ODM file being processed. FileNames are non-empty strings.

A languageTag represents a natural language or a country-specific variant of a natural language. The allowed values are specified in IETF RFC 3066: Tags for the Identification of Languages.

Example: "fr-CA" denotes the French language, Canadian variant. See TranslatedText for a discussion of how languageTags are used.

In general, if you want to represent a NULL attribute value for any of these formats, use an empty string (e.g., attribute-name=""). To represent a NULL for data transmitted in an element body, send the element as empty (e.g. <element-name/>). There is a special IsNull indicator for clinical data, to differentiate between the case where there is no known value, and the case where you want to replace a value with NULL. See the IsNull attribute of the ItemData element.

In the DTD for this standard, all formats are expressed as CDATA or %PCDATA. In the Schema, the definitions can be made more precise as follows.

XML Schema:

 
 <xs:simpleType name="text">
 <xs:restriction base="xs:string"/>
 </xs:simpleType>
 
 <xs:simpleType name="integer">
 <xs:restriction base="xs:integer">
 <xs:pattern value="-?[0-9]+"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="float">
 <xs:restriction base="xs:decimal">
 <xs:pattern value="-?[0-9]+(\.[0-9]+)?"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="date">
 <xs:restriction base="xs:date">
 <xs:pattern value="[0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="time">
 <xs:restriction base="xs:time">
 <xs:pattern value="[0-2][0-9]:[0-5][0-9]:[0-5][0-9](\.[0-9]+)?((\+|-)[0-2][0-9]:[0-5][0-9])?"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="datetime">
 <xs:restriction base="xs:dateTime">
 <xs:pattern value="[0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]T[0-2][0-9]:[0-5][0-9]:[0-5][0-9](\.[0-9]+)?((\+|-)[0-2][0-9]:[0-5][0-9])?"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="oid">
 <xs:restriction base="xs:string">
 <xs:minLength value="1"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="oidref">
 <xs:restriction base="xs:string">
 <xs:minLength value="1"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="value">
 <xs:restriction base="xs:string"/>
 </xs:simpleType>
 
 <xs:simpleType name="subjectKey">
 <xs:restriction base="xs:string">
 <xs:minLength value="1"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="repeatKey">
 <xs:restriction base="xs:string">
 <xs:minLength value="1"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="name">
  <xs:restriction base="xs:string">
 <xs:minLength value="1"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="sasName">
 <xs:restriction base="xs:string">
 <xs:pattern value="[A-Za-z_][A-Za-z0-9_]*"/>
 <xs:maxLength value="8"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="sasFormat">
 <xs:restriction base="xs:string">
 <xs:pattern value="[A-Za-z_$][A-Za-z0-9_.]*"/>
 <xs:maxLength value="8"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="fileName">
 <xs:restriction base="xs:string">
 <xs:pattern value="[A-Za-z0-9_.]+"/>
 </xs:restriction>
 </xs:simpleType>

The following Schema definitions define the enumeration types used in various ODM elements.

XML Schema:

 
 <xs:simpleType name="FileType">
 <xs:restriction base="xs:string">
 <xs:enumeration value="Snapshot"/>
 <xs:enumeration value="Transactional"/>
 <xs:maxLength value="13"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="Granularity">
 <xs:restriction base="xs:string">
 <xs:enumeration value="All"/>
 <xs:enumeration value="Metadata"/>
 <xs:enumeration value="AdminData"/>
 <xs:enumeration value="ReferenceData"/>
 <xs:enumeration value="AllClinicalData"/>
 <xs:enumeration value="SingleSite"/>
 <xs:enumeration value="SingleSubject"/>
 <xs:maxLength value="15"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="EventType">
 <xs:restriction base="xs:string">
 <xs:enumeration value="Scheduled"/>
 <xs:enumeration value="Unscheduled"/>
 <xs:enumeration value="Common"/>
 <xs:maxLength value="11"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="DataType">
 <xs:restriction base="xs:string">
 <xs:enumeration value="integer"/>
 <xs:enumeration value="float"/>
 <xs:enumeration value="date"/>
 <xs:enumeration value="datetime"/>
 <xs:enumeration value="time"/>
 <xs:enumeration value="text"/>
 <xs:maxLength value="8"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="CLDataType">
 <xs:restriction base="xs:string">
 <xs:enumeration value="integer"/>
 <xs:enumeration value="float"/>
 <xs:enumeration value="text"/>
 <xs:maxLength value="7"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="Comparator">
 <xs:restriction base="xs:string">
 <xs:enumeration value="LT"/>
 <xs:enumeration value="LE"/>
 <xs:enumeration value="GT"/>
 <xs:enumeration value="GE"/>
 <xs:enumeration value="EQ"/>
 <xs:enumeration value="NE"/>
 <xs:enumeration value="IN"/>
 <xs:enumeration value="NOTIN"/>
 <xs:maxLength value="5"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="SoftOrHard">
 <xs:restriction base="xs:string">
 <xs:enumeration value="Soft"/>
 <xs:enumeration value="Hard"/>
 <xs:maxLength value="4"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="TransactionType">
 <xs:restriction base="xs:string">
 <xs:enumeration value="Insert"/>
 <xs:enumeration value="Update"/>
 <xs:enumeration value="Remove"/>
 <xs:enumeration value="Upsert"/>
 <xs:enumeration value="Context"/>
 <xs:maxLength value="7"/>
 </xs:restriction>
 </xs:simpleType>
 
 <xs:simpleType name="UserType">
 <xs:restriction base="xs:string">
 <xs:enumeration value="Sponsor"/>