USDM object model
USDM 4.0 defines 86 classes with 833 attributes between them. This is a reference to all of them, generated from the official release, with each class on its own page.
Where the main classes sit
The boxes nest the way the JSON does. Select a class to see what it is and which classes it points to by id.
- Structure
- Schedule
- Purpose
- People
StudyVersion
study.versions[]
One version of the plan. It owns the titles, identifiers, organizations, interventions and one or more study designs, plus the amendments that produced it.
CDISC definition. A plan at a particular point in time for a study.
Points to, by id
documentVersionIdsStudyDefinitionDocumentVersion
How to read the model
- Classes become objects. Each object in a file names its class in
instanceType. 6 of the 86 classes are abstract: they exist to share attributes between their subclasses and never appear in a file themselves. - Two kinds of relationship. An attribute either holds another object (nested) or holds its id (a reference). Reference attributes end in
IdorIds. The class pages mark which is which. - Cardinality.
1is exactly one,0..1is optional,0..*is any number and1..*is at least one. - Coded values name their codelist. Where an attribute is a code, its page says which codelist the value must come from, and lists the values when the codelist is one USDM defines itself.
- Required is stricter in the API. The pages mark an attribute as required when the USDM API schema requires it in a JSON file, which is what a parser will enforce.
Study, versions and amendments
The root of every USDM file: the study, each version of its plan, its titles and identifiers, and the amendments that moved it from one version to the next.
- Study8 attributesThe top of the tree. A Study is little more than a name and a list of versions: everything of substance hangs off a StudyVersion.
- StudyVersion28 attributesOne version of the plan. It owns the titles, identifiers, organizations, interventions and one or more study designs, plus the amendments that produced it.
- StudyTitle5 attributesOne title of the study, typed by a code: official, brief, public, scientific or acronym. A study normally carries several.
- IdentifierAbstract3 attributesThe shared shape of every identifier in the model: a text value and the organization that issued it.
- StudyIdentifier5 attributesAn identifier for the study together with the organization that issued it. The sponsor protocol number and the registry number are two StudyIdentifiers with different scopes.
- ReferenceIdentifier6 attributesAn identifier of something the study refers to, such as a paediatric investigation plan or a clinical development plan, with the organization that issued it.
- GovernanceDate9 attributesA dated milestone for a study version, a document version or an amendment, such as an approval date, with the geographic scope it applies to.
- GeographicScope5 attributesWhere something applies: globally, in a region or in a country, with the code for the region or country.
- StudyAmendment17 attributesA formal change to the plan: its number, summary, primary and secondary reasons, what changed and who is affected.
- StudyAmendmentReason5 attributesWhy the protocol was amended, as a coded reason, with free text when the reason is Other.
- StudyAmendmentImpact7 attributesOne effect of an amendment, by type (participant safety, participant rights, data reliability, data robustness), with a flag for whether it is substantial.
- StudyChange9 attributesOne change made by an amendment: a summary, the rationale, and the document sections it altered.
- SubjectEnrollment10 attributesHow many participants were enrolled when an amendment was made, overall or for a particular country, cohort or site.
Organizations, roles and sites
Who is involved and in what capacity: sponsors, registries, CROs, sites, named people and who is masked.
- Organization10 attributesA company, agency, registry or institution. Identifiers and roles point at organizations by id.
- StudyRole12 attributesA capacity in which an organization or person takes part in the study: sponsor, investigator, CRO, laboratory, data monitoring committee and so on.
- AssignedPerson9 attributesA named person assigned to a study role, with a job title and optionally the organization they belong to.
- PersonName8 attributesA person's name, as one string or split into family name, given names, prefixes and suffixes.
- Address10 attributesA postal address, held as one string, as separate lines, city, district, state and postal code, or both.
- StudySite7 attributesA place where an investigator carries out the study, with its country. Sites are listed under the organization that manages them.
- Masking5 attributesWhether a study role is masked, and a description of how the masking is kept.
- ProductOrganizationRole9 attributesThe part an organization plays for a product or device: manufacturer or supplier.
Study design
The shape of the trial: arms, epochs, the cells where they meet, the elements inside each cell, and the indication under study.
- StudyDesignAbstract26 attributesThe shared shape of every study design: arms, epochs, cells, encounters, activities, timelines, objectives, population and eligibility criteria.
- InterventionalStudyDesign32 attributesThe design of an interventional trial: phase, model, blinding, arms, epochs, visits, activities, schedule, objectives, population and eligibility all hang off this object.
- ObservationalStudyDesign32 attributesThe design of an observational study, with sampling method, time perspective and observational model in place of blinding and intervention model.
- StudyArm11 attributesA planned path through the study that a participant is assigned to, such as active treatment or placebo.
- StudyEpoch10 attributesA named period of the study that applies to every arm, such as screening, treatment and follow-up. Epochs are ordered with previousId and nextId.
- StudyCell6 attributesThe intersection of one arm and one epoch. It lists the elements a participant in that arm passes through during that epoch.
- StudyElement10 attributesA building block of time inside a cell, with a rule for when it starts and optionally when it ends, and the interventions given during it.
- TransitionRule7 attributesA rule, in text, for when a participant moves into or out of an element or an encounter.
- Indication9 attributesThe disease or condition under study, with codes from medical dictionaries and a flag for rare disease.
- BiospecimenRetention8 attributesWhether biological samples are kept after their first use, and whether the retained samples include DNA.
Schedule and timing
The schedule of activities as data: visits, activities, the timeline that orders them, and the timings and windows between them.
- Encounter15 attributesA visit or other planned contact with the participant, with its setting and contact mode. An encounter is where activities happen; it does not hold the activities itself.
- Activity15 attributesSomething planned to be done or observed: a procedure, an assessment, a questionnaire, dispensing drug. Activities can be nested with childIds to form groups.
- Procedure10 attributesA coded procedure that an activity involves, with a pointer to an external dictionary code.
- ScheduleTimeline13 attributesAn ordered schedule: an entry point, a sequence of scheduled instances, the timings between them and one or more exits. A study has one main timeline and may have others for sub-schedules.
- ScheduleTimelineExit3 attributesA marker for the end of a timeline. It has no content of its own.
- ScheduledInstanceAbstract6 attributesThe shared shape of a point on a timeline: its epoch and the default next step.
- ScheduledActivityInstance12 attributesOne planned point on a timeline: these activities, at this encounter, in this epoch. It is the object that ties what to when.
- ScheduledDecisionInstance9 attributesA point on a timeline where the path depends on a condition. Each condition assignment names a condition and the instance to go to when it holds.
- ConditionAssignment5 attributesOne branch of a decision: a condition in text and the scheduled instance to go to when it is met.
- Condition11 attributesA condition under which something applies, written as templated text. It names what it is about (an activity, a procedure, a biomedical concept) and where on the schedule it holds.
- Timing15 attributesThe time between two scheduled instances, with an optional window. Timings are either a fixed reference (the anchor, usually Day 1) or relative: a duration before or after another instance.
- Duration7 attributesHow long something lasts: as text, as a quantity or range, with a flag for whether it will vary between participants and why.
Objectives, endpoints and estimands
What the study sets out to learn and how it will be measured, including the ICH E9(R1) estimand attributes.
- Objective11 attributesOne objective of the study with its level (primary, secondary, exploratory) and its endpoints.
- Endpoint11 attributesA variable used to assess an objective, with its level and purpose. Endpoints are nested inside the objective they belong to.
- Estimand12 attributesThe precise treatment effect being estimated: the population, the variable, the interventions being compared, the intercurrent events and how each is handled.
- IntercurrentEvent10 attributesAn event after treatment starts that affects how the outcome can be interpreted, with the strategy for handling it.
- AnalysisPopulation9 attributesA population an analysis is run on, such as the full analysis set or the per-protocol set, described in text.
Population and eligibility
Who can take part: the planned population, cohorts within it, and each inclusion and exclusion criterion.
- PopulationDefinitionAbstract11 attributesThe shared shape of a study population and of a cohort within it: planned numbers, age, sex, healthy participants, and the criteria that apply.
- StudyDesignPopulation14 attributesThe population the study plans to enrol: planned numbers, age range, sex, whether healthy participants are included, and the eligibility criteria that define it.
- StudyCohort15 attributesA subgroup of the study population with its own characteristics, criteria and planned numbers, used for cohort and basket designs.
- Characteristic9 attributesA characteristic that defines a cohort, written as templated text in the same way as a criterion.
- EligibilityCriterion12 attributesOne inclusion or exclusion criterion in this study: its category, its number, and a pointer to the reusable text.
- EligibilityCriterionItem9 attributesThe text of a criterion, kept separate so the same wording can be reused across designs and studies.
Interventions and products
What participants receive: the intervention, how it is administered, and the product, ingredients, strengths and devices behind it.
- StudyIntervention12 attributesA treatment, product or procedure being studied or used in the study, with its role (experimental, placebo, comparator, rescue) and how it is administered.
- Administration13 attributesHow an intervention is given: dose, route, frequency and duration.
- AdministrableProduct14 attributesA product in the form it is given to a participant: its dose form, whether it is investigational or auxiliary, how it is sourced, and what it is made of.
- AdministrableProductIdentifier5 attributesAn identifier for an administrable product, with the organization that issued it.
- AdministrableProductProperty7 attributesA named property of a product, such as its pH, given as text with an optional quantity.
- Ingredient5 attributesA component of a product and the role it plays, with the substance it is made of.
- Substance9 attributesA material of defined composition that an ingredient is made of, with its strengths, dictionary codes, and optionally the reference substance its strength is expressed against.
- Strength8 attributesHow much of a substance a product contains, as a numerator and an optional denominator: 10 mg per tablet, 5 mg per mL.
- MedicalDevice12 attributesA device used in the study, with hardware and software versions, how it is sourced, its identifiers, and the product it contains if it delivers one.
- MedicalDeviceIdentifier6 attributesAn identifier for a device, typed as a batch number, lot number, model number or FDA unique device identifier.
Biomedical concepts
The data layer: what is actually collected when an activity is performed, down to the property and its allowed responses.
- BiomedicalConcept10 attributesA unit of data collected by an activity, such as systolic blood pressure, with its properties and coded responses. It is what lets an EDC build be derived from the design.
- BiomedicalConceptCategory10 attributesA named group of biomedical concepts, such as vital signs. Categories can nest.
- BiomedicalConceptProperty11 attributesOne property of a biomedical concept: the result, its unit, the body position, the method. Each has a datatype and can list its allowed responses.
- BiomedicalConceptSurrogate8 attributesA placeholder for data an activity collects when no standard biomedical concept exists for it yet: a name, a description and an optional reference.
- ResponseCode7 attributesOne allowed answer for a biomedical concept property, as a coded value that a study can switch on or off.
Documents and narrative
The protocol as a document: its versions, its sections of prose, and the templated text and abbreviations that prose uses.
- StudyDefinitionDocument12 attributesA document that defines the study, normally the protocol, with its language, template and versions.
- StudyDefinitionDocumentVersion8 attributesOne version of a document, with its status (draft, final, approved), its dates and its sections.
- NarrativeContent12 attributesOne section of a document: its number, title and position, with a pointer to the text of the section.
- NarrativeContentItem5 attributesThe text of a section, as XHTML. This is where the prose of the protocol lives next to the structured design.
- DocumentContentReference6 attributesA pointer to a section of a study definition document, by section number and title.
- SyntaxTemplateAbstract7 attributesThe shared shape of text that can contain tags standing for structured values. Objectives, endpoints, criteria, conditions, characteristics and intercurrent events all have it.
- SyntaxTemplateDictionary7 attributesA lookup table for templated text: each entry maps a tag used in the text to a value held elsewhere in the study.
- ParameterMap5 attributesOne entry in a syntax template dictionary: a tag name and what it stands for, either a reference to a value held elsewhere in the study or a fixed string.
- Abbreviation6 attributesAn abbreviation and what it stands for, defined once on the study version and reused wherever the text needs it.
- CommentAnnotation5 attributesA free-text note, optionally with codes, attached to another object. Most classes carry a notes list, added in version 4.0.
Codes, quantities and extensions
The building blocks every other class uses: coded values, numbers with units, ranges, and the mechanism for carrying data the standard does not define.
- Code7 attributesA coded value: the code, the system it comes from, the version of that system and the human-readable decode.
- AliasCode5 attributesA standard code together with alternative codes for the same concept, used where a sponsor term has to sit beside the CDISC one.
- Quantity5 attributesA number with an optional unit, where the unit is itself a coded value.
- Range6 attributesA minimum and a maximum Quantity, with a flag for whether the range is approximate.
- QuantityRangeAbstract1 attributesA placeholder type meaning either a single Quantity or a Range. Attributes such as planned enrolment accept either.
- ExtensionAttribute13 attributesThe standard's own escape hatch. Any object can carry extension attributes, each identified by a URL, to hold information USDM does not define.
- ExtensionClass4 attributesA structured extension value: a group of extension attributes identified by a URL, for when one extra value is not enough.
Where this comes from
The class names, definitions, attributes, types and cardinalities on these pages are read from the USDM 4.0 release in the CDISC DDF-RA repository: the logical model for definitions and the API specification for which attributes a JSON file must carry. The grouping and the plain-language notes are Concordare’s. Where the two differ in emphasis, the standard is right. To look an attribute up by name, use the attribute index. See also the glossary.