Define.xml: What It Is and Why It Matters

$$ \text{Clinical Dataset} + \text{Metadata} \rightarrow \text{Understandable Submission} $$

USUBJID   TRT01P          AGE   SEX
ABC001    Drug A          62    M
ABC002    Placebo         54    F
ABC003    Drug A          71    M

<ItemGroupDef
    OID="IG.SDTM.DM"
    Name="DM"
    Repeating="No"
    SASDatasetName="DM">

    ...

</ItemGroupDef>

USUBJID
SUBJID
SITEID
AGE
SEX
ARM

Variable name:
AGE

Variable label:
Age

12.50

M
F
U

$$ \text{Variable} \rightarrow \text{CodeList} \rightarrow \text{Permitted Values} $$

Male
MALE
M
1

PARAMCD = "SYSBP"
AVAL    = Systolic Blood Pressure

PARAMCD = "DIABP"
AVAL    = Diastolic Blood Pressure

AVAL = Analysis Value

AGE

CHG

$$ CHG = AVAL - BASE $$

BASE = 120
AVAL = 108
CHG  = -12

$$ CHG = AVAL - BASE $$

CHG = -12

$$ CHG = AVAL - BASE $$

$$ USUBJID + PARAMCD + AVISIT $$

USUBJID
AESEQ
AETERM
AEDECOD
AESTDTC
AEENDTC
AESEV
AESER

BASE
AVAL
CHG
PCHG
ABLFL
ANL01FL

USUBJID
PARAM
PARAMCD
AVAL
BASE
CHG
PCHG
AVISIT
AVALCAT1

$$ BASE=120 $$

and:

Then:

The percentage change is:

Define-XML can document these derived variables and their associated methods.

Define-XML Does Not Replace the SAP

This distinction is extremely important.

The Define-XML document can describe the computational method associated with a variable.

It does not necessarily replace the full statistical analysis plan.

The SAP may contain the broader statistical rationale, estimand definitions, analysis populations, missing-data strategies, sensitivity analyses, and inferential methodology.

Define-XML and Traceability

Traceability is one of the most important concepts in clinical data standards.

A derived analysis variable should ideally be traceable through the analysis process to its source.

Conceptually:

Define-XML helps document portions of this chain by describing origins, derivations, and references.

What Does Origin Mean?

Origin describes where a variable's value comes from.

Common conceptual categories include:

Origin	Meaning
Collected	Value originates from collected study data
Derived	Value is calculated using other information
Assigned	Value is assigned according to study or sponsor rules
Predecessor	Value is inherited or carried forward from another dataset or variable context
Protocol	Information originates from protocol-defined information

The exact permitted and applicable origin concepts depend on the Define-XML version and implementation.

Define-XML Version Matters

Define-XML has evolved over time.

Different Define-XML versions provide different capabilities and structures.

A project should therefore establish the intended Define-XML version before metadata generation begins.

Define-XML 2.x

Define-XML 2.x is widely encountered in modern clinical-trial submissions.

It provides a structured way to describe:

• Datasets
• Variables
• Value-level metadata
• Codelists
• Methods
• Comments
• Documents
• Relationships

The specific implementation should always be checked against the applicable Define-XML specification and regulatory guidance.

XML Basics for Clinical Programmers

You do not need to become an XML software engineer to work effectively with Define-XML.

However, you should understand the basic concepts.

XML uses nested elements.

For example:

<ItemDef OID="IT.AGE" Name="AGE">
    ...
</ItemDef>

Here:

• ItemDef is the element.
• OID is an attribute.
• AGE is an attribute value.

XML Elements and Attributes

Consider:

<ItemDef
    OID="IT.AGE"
    Name="AGE"
    DataType="integer">
</ItemDef>

The element is:

<ItemDef>

The attributes include:

OID
Name
DataType

These attributes provide metadata about the item.

Object Identifiers

Define-XML uses identifiers extensively.

These identifiers allow metadata objects to reference one another.

For example:

IG.SDTM.DM
IT.SDTM.DM.USUBJID
IT.SDTM.DM.AGE
CL.SEX

The exact naming convention is implementation-specific.

The critical concept is that each metadata object needs an identifier that can be referenced elsewhere in the XML.

Why OIDs Matter

Suppose an ItemGroupDef references several variables.

The XML needs a reliable way to say:

Object identifiers provide that linkage.

Variable Ordering

Variable order can also matter.

For example, a dataset might be represented as:

USUBJID
SUBJID
SITEID
AGE
SEX
ARM

The Define-XML metadata should represent the intended structure and ordering appropriately.

This is one reason metadata generation should not simply consist of creating a random collection of variable definitions.

Comments

Comments provide another mechanism for communicating additional metadata.

They can be useful when a variable or dataset needs explanatory information that is not adequately represented by the basic metadata attributes.

For example:

Variable:
ANL01FL

Comment:
Flag identifies records included in the primary analysis.

The exact implementation should follow the Define-XML model.

Dataset Classes

Dataset metadata can also include information describing the general type or class of the dataset.

Examples in a CDISC environment can include concepts associated with:

• Findings
• Events
• Interventions
• Special-purpose domains
• ADaM dataset classes

The appropriate classification depends on the standard and dataset.

Structure Descriptions

The structure description is another important part of dataset metadata.

For example, an SDTM dataset may have a structure such as:

One record per subject per adverse event

An ADaM dataset may have:

One or more records per subject per parameter per analysis visit

The structure statement helps reviewers understand how to interpret the rows.

Define-XML and Supplemental Qualifiers

SDTM submissions can include supplemental qualifier datasets such as SUPP--.

Metadata must account for these datasets and their relationships to the corresponding parent domains.

This illustrates an important principle:

Define-XML and Relationships

Some datasets contain relationships that are important to interpretation.

Examples include relationships between:

• Parent domains and supplemental qualifiers
• Datasets and documents
• Variables and codelists
• Variables and methods
• Variables and value-level metadata

Define-XML provides mechanisms for representing these relationships.

What a Define-XML File Might Conceptually Describe

Object	Example
Dataset	ADSL
Variable	SAFFL
Label	Safety Population Flag
Type	text
Origin	Derived
Method	Safety population derivation
Supporting document	Statistical Analysis Plan

Creating Define-XML: The Practical Workflow

Step 1: Inventory the Datasets

Start with a complete inventory of the datasets included in the submission.

For example:

SDTM
  DM
  AE
  CM
  LB
  VS
  EX

ADaM
  ADSL
  ADAE
  ADLB
  ADVS
  ADEFF

Every submitted dataset needs appropriate metadata.

Step 2: Extract Variable Metadata

For each dataset, identify:

• Variable name
• Variable label
• Data type
• Length or significant digits where applicable
• Variable order
• Origin
• Codelist
• Method
• Value-level metadata

Step 3: Identify Codelists

Build an inventory of all controlled terminology relationships.

For example:

Dataset	Variable	Terminology
DM	SEX	Sex terminology
DM	RACE	Race terminology
AE	AESEV	Severity terminology
AE	AESER	Seriousness terminology

Step 4: Identify Derived Variables

One of the most important programming tasks is identifying variables whose values are derived.

Examples include:

CHG
PCHG
BASE
ABLFL
ANL01FL
SAFFL
ITTFL
TRTSDT
TRTEDT

The exact derivation should be documented according to the study's standards and specifications.

Step 5: Identify Value-Level Metadata

Next ask:

Does the meaning of this variable depend on another variable?

If yes, value-level metadata may be necessary.

Typical examples include:

• AVAL
• AVALC
• BASE
• CHG
• PCHG
• Analysis parameters

Step 6: Add Document References

Identify the documents needed to explain the metadata.

Examples include:

• Annotated CRF
• SAP
• Protocol
• Analysis Data Reviewer's Guide
• Study Data Reviewer's Guide

The exact documents required depend on the submission context.

Generating Define-XML From Metadata Tables

Many organizations maintain metadata in structured source tables before generating Define-XML.

For example:

DATASET  VARIABLE  LABEL                  TYPE
ADSL     USUBJID   Unique Subject ID      text
ADSL     AGE       Age                    integer
ADSL     SEX       Sex                    text
ADSL     SAFFL     Safety Population Flag text

A Define-XML generation process can transform this metadata into XML.

Why Metadata-Driven Programming Is Better

Manually typing hundreds or thousands of XML elements is error-prone.

A metadata-driven process can instead:

Example Metadata-Driven Structure

metadata/
    datasets.csv
    variables.csv
    codelists.csv
    methods.csv
    documents.csv
    vlm.csv

output/
    define.xml

The exact architecture varies by organization.

The important principle is to maintain a reproducible relationship between source metadata and generated Define-XML.

Programming Define-XML in SAS

Clinical programmers working in SAS may generate Define-XML using specialized metadata-generation tools, sponsor frameworks, or custom programming.

A simple metadata table might contain:

data variables;

length
  dataset $8
  variable $32
  label $200
  datatype $12
  origin $20;

dataset  = "ADSL";
variable = "AGE";
label    = "Age";
datatype = "integer";
origin   = "Derived";

run;

A production implementation would generally contain considerably more metadata.

Programming Define-XML in R

R can also be used to create and manipulate Define-XML metadata.

A metadata table can be represented as:

variables <- data.frame(
  dataset = c("ADSL", "ADSL", "ADSL"),
  variable = c("USUBJID", "AGE", "SEX"),
  label = c(
    "Unique Subject Identifier",
    "Age",
    "Sex"
  ),
  datatype = c(
    "text",
    "integer",
    "text"
  ),
  origin = c(
    "Collected",
    "Derived",
    "Collected"
  )
)

The metadata can then be transformed into the required Define-XML structure.

Do Not Confuse Dataset Generation With Define-XML Generation

A common misconception is that once the dataset is programmed, Define-XML is just documentation added at the end.

In reality, good Define-XML depends on metadata being available throughout the development lifecycle.

Define-XML and the Study Data Reviewer

A reviewer may need to answer questions such as:

• What does this variable mean?
• Why does this variable exist?
• Where did this value originate?
• How was it derived?
• Which terminology applies?
• What dataset contains the source information?
• What document explains the derivation?

A well-constructed Define-XML document makes these questions easier to answer.

Define-XML and Regulatory Review

Regulatory reviewers need to understand submitted datasets efficiently.

A submission that contains technically correct datasets but incomplete or inconsistent metadata creates unnecessary review burden.

Define-XML helps provide a standardized machine-readable description of the submission.

Common Define-XML Problems

1. Dataset exists but is missing from Define-XML. Every submitted dataset needs appropriate metadata representation.
2. Variable exists in the dataset but not in Define-XML. The dataset and metadata are inconsistent.
3. Variable is described with the wrong label. This can lead to reviewer confusion.
4. Incorrect data type. The metadata does not accurately represent the dataset.
5. Incorrect variable length or significant digits. The metadata does not accurately describe the stored data.
6. Missing codelist. A controlled variable lacks the expected terminology metadata.
7. Incorrect codelist. The variable is linked to terminology that does not match the data.
8. Missing origin. The reviewer cannot easily determine where the variable came from.
9. Missing computational method. A derived variable lacks adequate derivation metadata.
10. Missing value-level metadata. A variable with parameter-dependent meaning is described too generically.
11. Broken references. An OID or document reference points to something that does not exist.
12. Metadata describes an older dataset version. The Define-XML no longer matches the final submission datasets.

Define-XML Validation

Validation should occur at multiple levels.

Validation Type	Question
XML validation	Is the XML structurally valid?
Schema validation	Does the document conform to the applicable Define-XML schema?
Dataset comparison	Does Define-XML match the submitted datasets?
Terminology validation	Are codelists and codes represented correctly?
Traceability review	Can derived variables be understood and traced?
Regulatory review	Does the submission meet applicable agency expectations?

Dataset-to-Define Reconciliation

One of the most important QC checks is comparing the actual dataset metadata against Define-XML.

For every dataset:

Example of a Metadata Mismatch

Suppose the dataset contains:

AGE
integer

but Define-XML states:

AGE
float

The dataset may still contain values that appear correct.

Nevertheless, the metadata is inconsistent.

The Define-XML should accurately describe the submitted dataset.

Another Metadata Mismatch

Suppose the dataset contains:

TRT01P
"Drug A"
"Placebo"

but the Define-XML links the variable to an unrelated codelist.

The data and metadata are no longer semantically aligned.

This type of error is particularly important because it can be less obvious than a simple missing variable.

Value-Level Metadata QC

Value-level metadata deserves special attention.

For every VLM definition, verify:

• The parent variable exists.
• The where-clause variable exists.
• The where-clause value is valid.
• The parameter-specific label is correct.
• The parameter-specific unit is correct.
• The parameter-specific origin is correct.
• The parameter-specific method is correct.

Methods QC

For each computational method:

• Confirm the method identifier is unique.
• Confirm the method is referenced correctly.
• Confirm the description matches the actual derivation.
• Confirm the referenced documentation exists.
• Confirm the method has not been copied from an outdated version.

Document Reference QC

Document references can fail even when the underlying XML is technically valid.

Check:

• Document filename
• Document path
• Leaf identifier
• Document version
• Referenced page or section where applicable
• Actual availability of the referenced document

Define-XML Versus a Data Dictionary

A data dictionary and Define-XML are related but not identical.

Feature	Data Dictionary	Define-XML
Human-readable	Yes	Yes, when rendered
Machine-readable	Usually limited	Yes
Dataset metadata	Yes	Yes
Variable metadata	Yes	Yes
Codelists	Possible	Structured
Value-level metadata	Possible	Structured
Computational methods	Possible	Structured
XML relationships	No	Yes

A spreadsheet may be an excellent source for maintaining metadata, but it is not itself Define-XML.

Define-XML Versus Dataset-XML

These two names are easy to confuse.

They serve different purposes.

	Define-XML	Dataset-XML
Primary purpose	Describe dataset metadata	Represent dataset data in XML
Contains observations	Generally no	Yes
Contains variable metadata	Yes	Not its primary purpose
Contains codelists	Yes	Not its primary purpose

The distinction is important when working with electronic submissions.

Define-XML and XPT Files

Traditional regulatory submissions often include SAS transport-format datasets alongside Define-XML metadata.

The relationship is conceptually:

The XPT file contains the actual data.

Define-XML describes the structure and meaning of the data.

Why Define-XML Errors Are Dangerous

Suppose the underlying data are correct but Define-XML incorrectly describes the variable.

A reviewer may interpret the data incorrectly.

Alternatively, suppose the Define-XML says a variable is derived using a particular method, but the production program used another method.

The metadata no longer accurately represents the submitted data-generation process.

Define-XML as a Contract

A useful mental model is to think of Define-XML as a metadata contract.

It establishes expectations about:

• What datasets exist
• What variables exist
• What variables mean
• What values are permitted
• Where values came from
• How values were derived
• Which documents support the definitions

The actual datasets should satisfy that contract.

Define-XML and Automation

Modern clinical programming organizations often automate Define-XML generation.

A metadata repository may contain:

Dataset metadata
Variable metadata
Codelists
Origins
Methods
Value-level metadata
Document references

A generation engine can then produce:

define.xml

This approach provides important advantages.

Benefits of Automated Define-XML Generation

• Reduced manual XML editing
• Improved reproducibility
• Consistent naming conventions
• Automated OID generation
• Automated dataset reconciliation
• Reusable programming components
• Easier updates when datasets change
• Better auditability

Metadata-Driven Development

An advanced clinical programming workflow can treat metadata as a central development artifact.

Define-XML Quality-Control Checklist

Check	Question
Dataset coverage	Is every submitted dataset represented?
Variable coverage	Is every submitted variable represented?
Variable order	Does metadata reflect the intended dataset structure?
Labels	Are labels accurate?
Data types	Do types match the datasets?
Codelists	Are controlled terms correctly associated?
Origins	Are origins accurately documented?
Methods	Are derived variables adequately described?
VLM	Is value-level metadata complete where needed?
References	Do document references resolve correctly?
OIDs	Are metadata identifiers unique and consistently referenced?
Schema	Does the XML conform to the applicable schema?

Common Beginner Mistakes

1. Thinking Define-XML contains the clinical data. It describes the data rather than replacing the submitted datasets.
2. Treating Define-XML as a simple spreadsheet export. Define-XML represents relationships between metadata objects that a simple variable listing does not capture.
3. Ignoring value-level metadata. Some variables require conditional metadata based on parameter or another qualifying variable.
4. Forgetting origins. A reviewer should be able to understand where variables came from.
5. Documenting derivations inaccurately. The metadata must correspond to the actual production derivation.
6. Using stale metadata. Define-XML should describe the final submitted datasets.
7. Manually editing generated XML without reconciliation. Manual changes can easily introduce inconsistencies.
8. Validating only the XML syntax. Well-formed XML can still contain incorrect clinical metadata.
9. Assuming a successful schema validation means the metadata is correct. Schema validity does not guarantee semantic correctness.

Well-Formed XML vs. Correct Define-XML

These are different concepts.

An XML document can be syntactically well-formed while containing incorrect metadata.

For example:

<ItemDef
    Name="AGE"
    DataType="integer">
</ItemDef>

The XML may be syntactically valid.

But if the actual submitted variable is character data, the metadata is wrong.

Semantic Validation

Semantic validation asks whether the metadata actually makes sense.

Examples:

• Does SEX use an appropriate sex terminology codelist?
• Does AGE have the appropriate data type?
• Does CHG have a method consistent with the actual program?
• Does AVAL have appropriate value-level metadata?
• Does the dataset structure match the stated structure?

Independent Define-XML QC

For important regulatory submissions, independent QC is valuable.

One approach is:

Final Submission Reconciliation

The final Define-XML should be generated or finalized against the actual submission datasets.

Do not generate Define-XML against an intermediate programming version and assume the final datasets will remain unchanged.

A final reconciliation should confirm:

• Dataset names
• Dataset files
• Variable names
• Variable order
• Labels
• Types
• Lengths
• Codelists
• Methods
• Origins
• Value-level metadata
• Document references

Define-XML and Reviewer Experience

Good metadata has a practical effect on the review process.

A reviewer should be able to move from:

without encountering unexplained gaps.

This is one of the fundamental reasons Define-XML matters.

A Practical Example

Suppose an ADaM efficacy dataset contains:

USUBJID
PARAMCD
PARAM
AVAL
BASE
CHG
PCHG
AVISIT
ANL01FL

A reviewer might want to know:

• What is PARAMCD?
• What does AVAL represent for each parameter?
• How is BASE selected?
• How is CHG calculated?
• How is PCHG calculated?
• What does ANL01FL identify?

Define-XML can provide metadata for each of these concepts.

Example Derivation Chain

Variable	Example	Metadata Question
BASE	120	How was baseline selected?
AVAL	108	What does the analysis value represent?
CHG	−12	How was change calculated?
PCHG	−10%	How was percentage change calculated?
ANL01FL	Y	What qualifies a record for the analysis?

The metadata is therefore closely connected to the statistical programming logic.

Define-XML and Traceability to Programs

Define-XML does not mean that every line of SAS or R code must be embedded in the XML.

Instead, the metadata should communicate the derivation sufficiently and link to supporting documentation where appropriate.

The detailed programming implementation remains in the validated analysis programs and supporting documentation.

What Makes a Good Define-XML Document?

A high-quality Define-XML document should be:

• Complete: all required datasets and metadata are represented.
• Accurate: metadata matches the actual submission.
• Consistent: terminology and identifiers are used coherently.
• Traceable: important derived information can be understood.
• Machine-readable: the XML conforms to the applicable standard.
• Reviewable: a human reviewer can understand the submission.
• Reproducible: the document can be regenerated or maintained reliably.

The Most Important Mental Model

The easiest way to understand Define-XML is to think in layers.

Define-XML in the Clinical Programming Lifecycle

Define-XML should not be viewed as something that appears only during the final week of a submission.

Instead, it connects several stages of clinical programming.

The earlier metadata is maintained accurately, the easier the final Define-XML generation and validation become.

Practical Define-XML Checklist

Key Differences: Define-XML vs. Dataset Content

Question	Dataset	Define-XML
What is the subject's AGE?	Contains the value	Describes AGE
What does AGE mean?	Not necessarily	Yes
What values are allowed for SEX?	Contains observed values	Can describe controlled terminology
How was CHG derived?	Contains the result	Can describe the derivation method
Where did a variable originate?	Not necessarily	Yes
What supporting document applies?	Not necessarily	Can provide document references

The Bottom Line

Define-XML is much more than an electronic data dictionary.

It is a structured metadata representation that connects the submitted datasets to the information needed to understand them.

For clinical programmers, this means Define-XML sits at the intersection of:

• Dataset programming
• CDISC standards
• Controlled terminology
• Metadata management
• Derivation documentation
• Traceability
• Quality control
• Regulatory submission

References

CDISC. Define-XML. CDISC standards documentation and implementation resources.

CDISC. Define-XML 2.0 Specification. Clinical Data Interchange Standards Consortium.

CDISC. Define-XML 2.1 Specification. Clinical Data Interchange Standards Consortium.

CDISC. SDTM Implementation Guide. Clinical Data Interchange Standards Consortium.

CDISC. ADaM Implementation Guide. Clinical Data Interchange Standards Consortium.

U.S. Food and Drug Administration. Study Data Technical Conformance Guide. Guidance for submitting standardized study data and associated metadata.