Skip to content

Commit 087aade

Browse files
tnagaminetnagamine
authored
Update RWD-Lineage_Data_Standard_Specification.md
Update to spec after team meeting on May 12
1 parent 0fc4f95 commit 087aade

1 file changed

Lines changed: 131 additions & 42 deletions

File tree

‎documents/RWD-Lineage_Data_Standard_Specification.md‎

Lines changed: 131 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ The `structure` attribute classifies how a value within a source is addressed, n
124124

125125
This section defines the controlled terminology (codelists) governing enumerated attributes in RWD Lineage. Codelists are submitted to the CDISC Controlled Terminology team under the `RWDL` prefix and are intended to be published through CDISC and NCI Enterprise Vocabulary Services (NCI-EVS) on the standard CDISC release cadence.
126126

127-
The codelists in this section are finalized for V1. Source data model conformance (e.g., FHIR R4, OMOP CDM 5.4, PCORnet CDM) is not governed by an RWDL codelist; it is declared at the submission level via Define-XML's existing `def:Standards` mechanism. See "Source Data Standards" below.
127+
The codelists in this section are finalized for V1. Source data model conformance (e.g., FHIR R4, OMOP CDM 5.4, PCORnet CDM) is not governed by an RWDL codelist; it is declared at the document level via the `rwdl:sourceMetadata` element. See "Source Metadata" below.
128128

129129
### RWDL Storage Type
130130

@@ -221,37 +221,108 @@ Governs the `syntax` attribute on the `Path` element. Required when `structure="
221221

222222
**Note:** Several values appear in both this codelist and the Data Format codelist (`HL7V2`, `DICOM`/`DICOMTAG`). They are governing different attributes and are not redundant: the Data Format value declares what kind of bytes the source contains; the Path Syntax value declares what addressing language locates a value within those bytes. They commonly co-occur for the same data point.
223223

224-
### Source Data Standards
225224

226-
The data model that a source conforms to (e.g., FHIR R4, OMOP CDM 5.4, PCORnet CDM, FDA Sentinel CDM, HL7 CDA R2) is not governed by an RWDL codelist. It is declared at the submission level via Define-XML's existing `def:Standards` element (Define-XML v2.1, Section 5.3.6).
227225

228-
A sponsor pulling from one or more RWD source systems declares each source standard as a `def:Standard` child element of the `def:Standards` container, alongside the CDISC target standards. Per-coordinate declaration of source data model is therefore unnecessary: each Coordinate's source data model is implicit from the URI and the submission-level `def:Standards` declaration.
226+
## Source Metadata
229227

230-
**Example:**
228+
RWD Lineage provides a top-level `rwdl:sourceMetadata` element for declaring metadata about the source data systems referenced in the lineage file. This element sits at the root of the RWD Lineage document (alongside the array of `MapID` elements) and is populated once per source system rather than per data point.
229+
230+
The element is OPTIONAL. Source data characterization is authoritatively documented in the sponsor's Study Data Reviewer's Guide (SDRG) and, for RWE submissions, in the RWD Reliability Assessment. The `rwdl:sourceMetadata` element provides a structured pointer to the same information for reviewers and tooling working directly within the RWD Lineage file, but is not intended to replace the narrative documents that authoritatively characterize source data.
231+
232+
### Structure
233+
234+
`rwdl:sourceMetadata` contains one or more `rwdl:source` child elements. Each `rwdl:source` describes one source system (the physical or logical origin) and MAY contain a nested `rwdl:standard` child element describing the data model or standard to which the source conforms.
235+
236+
#### `rwdl:source` Attributes
237+
238+
| Attribute | XML Data Type | Usage | Description |
239+
|-----------|---------------|-------|-------------|
240+
| `OID` | string | Optional | A unique identifier for the source system, used if any MapID or Coordinate needs to reference this source explicitly. By convention, OIDs identify distinct source systems (e.g., `SRC.EHR.1`, `SRC.EDW.1`, `SRC.CLAIMS.1`, `SRC.EDC.1`). |
241+
| `name` | string | Optional | The physical or logical name of the origin system (e.g., `University Hospital Epic Interconnect`, `Memorial Healthcare Enterprise Data Warehouse`, `Optum Claims Repository`, `Site 042 Medidata Rave EDC`). |
242+
| `description` | string | Optional | Free-text description of the source. Use when the source is bespoke or when additional context is helpful beyond the structured attributes. |
243+
244+
#### `rwdl:standard` Child Element
245+
246+
The `rwdl:standard` element is OPTIONAL and is used to declare that the parent `rwdl:source` conforms to a named data model or interoperability standard. A sponsor populates this element when the source system implements a recognizable standard; sources without a named standard omit the element and rely on the parent `description` attribute.
247+
248+
| Attribute | XML Data Type | Usage | Description |
249+
|-----------|---------------|-------|-------------|
250+
| `name` | string | Optional | The specific data model or standard utilized by the source (e.g., `FHIR`, `OMOP-CDM`, `PCORNET-CDM`, `SENTINEL-CDM`, `CDA`). Free-text; not constrained by an RWDL codelist in V1. |
251+
| `version` | string | Optional | The version of the standard (e.g., `5.4`, `R4`, `1.0`). |
252+
| `status` | string | Optional | Publication status of the standard. Allowed values mirror Define-XML `def:Standard/@Status`: `Draft`, `Provisional`, `Final`. |
253+
254+
A sponsor populates whichever attributes meaningfully apply to their source. The `rwdl:standard` element is appropriate for sources that conform to a named, versioned standard. The `description` attribute on `rwdl:source` is appropriate for bespoke sources, or as a supplement to the structured attributes.
255+
256+
### Examples
257+
258+
A sponsor with a single OMOP CDM source:
259+
260+
```xml
261+
<rwdl:sourceMetadata>
262+
<rwdl:source OID="SRC.EDW.1"
263+
name="Hospital X Enterprise Data Warehouse"
264+
description="Hospital X OMOP warehouse, refreshed quarterly">
265+
<rwdl:standard name="OMOP-CDM" version="5.4" status="Final"/>
266+
</rwdl:source>
267+
</rwdl:sourceMetadata>
268+
```
269+
270+
A sponsor with multiple source systems (an EHR exposed via FHIR and a research data warehouse on OMOP CDM):
271+
272+
```xml
273+
<rwdl:sourceMetadata>
274+
<rwdl:source OID="SRC.EHR.1"
275+
name="University Hospital Epic Interconnect"
276+
description="EHR FHIR API at api.hospital.org">
277+
<rwdl:standard name="FHIR" version="R4" status="Final"/>
278+
</rwdl:source>
279+
<rwdl:source OID="SRC.EDW.1"
280+
name="Memorial Healthcare Enterprise Data Warehouse"
281+
description="Research data warehouse">
282+
<rwdl:standard name="OMOP-CDM" version="5.4" status="Final"/>
283+
</rwdl:source>
284+
</rwdl:sourceMetadata>
285+
```
286+
287+
A sponsor combining claims data and EDC data alongside an EHR feed:
288+
289+
```xml
290+
<rwdl:sourceMetadata>
291+
<rwdl:source OID="SRC.EHR.1"
292+
name="University Hospital Epic Interconnect"
293+
description="EHR FHIR API at api.hospital.org">
294+
<rwdl:standard name="FHIR" version="R4" status="Final"/>
295+
</rwdl:source>
296+
<rwdl:source OID="SRC.CLAIMS.1"
297+
name="Optum Claims Repository"
298+
description="Adjudicated medical and pharmacy claims feed">
299+
<rwdl:standard name="PCORNET-CDM" version="6.1" status="Final"/>
300+
</rwdl:source>
301+
<rwdl:source OID="SRC.EDC.1"
302+
name="Site 042 Medidata Rave EDC"
303+
description="Clinical trial EDC export, Q2 2025">
304+
<rwdl:standard name="CDISC ODM" version="1.3.2" status="Final"/>
305+
</rwdl:source>
306+
</rwdl:sourceMetadata>
307+
```
308+
309+
A sponsor with a bespoke source that does not conform to a named standard (the `rwdl:standard` child element is simply omitted):
231310

232311
```xml
233-
<def:Standards>
234-
<def:Standard OID="STD.SDTMIG-3.4"
235-
Name="SDTMIG"
236-
Type="IG"
237-
Version="3.4"
238-
Status="Final"/>
239-
<def:Standard OID="STD.OMOP-CDM-5.4"
240-
Name="OMOP-CDM"
241-
Type="IG"
242-
Version="5.4"
243-
Status="Final"/>
244-
<def:Standard OID="STD.FHIR-R4"
245-
Name="FHIR"
246-
Type="IG"
247-
Version="R4"
248-
Status="Final"/>
249-
</def:Standards>
312+
<rwdl:sourceMetadata>
313+
<rwdl:source OID="SRC.EDC.1"
314+
name="Site 17 CSV Export"
315+
description="CSV exports from clinical trial site EDC system, Q2 2025; bespoke schema documented in SDRG Section 3.2"/>
316+
</rwdl:sourceMetadata>
250317
```
251318

252-
The `def:Standard/@Name` attribute is constrained by an extensible CDISC Controlled Terminology codelist that currently scopes allowed values to CDISC standards (SDTMIG, SENDIG, ADaMIG, etc.). RWD Lineage submissions require this codelist to be extended to include common source-data standards (`OMOP-CDM`, `FHIR`, `PCORNET-CDM`, `SENTINEL-CDM`, `CDA`, etc.). This extension is submitted to the CDISC Controlled Terminology team as a separate, smaller ask alongside the four RWDL codelists.
319+
### Notes
253320

254-
Sponsors with multiple source data models (e.g., FHIR for EHR data and OMOP-CDM for warehouse data) declare each as a separate `def:Standard` element. Coordinates that need to reference a specific source data model in their lineage MAY do so via implementer-defined conventions (for example, embedding the standard OID in the source URI), but the controlled declaration of which standards the submission uses is centralized in `def:Standards`.
321+
- The `name` attribute on `rwdl:source` identifies the physical or logical origin system; the `name` attribute on the nested `rwdl:standard` element identifies the data model the system implements. Two distinct source systems implementing the same standard (e.g., two hospitals both exposing FHIR R4) are represented as two separate `rwdl:source` elements.
322+
- The `name` attribute on `rwdl:standard` is free-text in V1. If RWDL submissions accumulate enough usage of common standardized names (OMOP-CDM, FHIR, etc.) to warrant a controlled vocabulary, a Data Model codelist may be submitted to CDISC CT in a future RWDL revision, informed by actual usage patterns.
323+
- OID conventions: recommended forms use a source-class prefix and a system index, e.g., `SRC.EHR.1`, `SRC.EHR.2`, `SRC.EDW.1`, `SRC.CLAIMS.1`, `SRC.EDC.1`. This keeps OIDs stable when a source system's underlying standard or version changes, and lets multiple sources implementing the same standard be distinguished.
324+
- Coordinates within MapID elements do not declare source data model on a per-data-point basis. The data model of a source is implicit from the source URI and the submission-level `rwdl:sourceMetadata` declaration, with authoritative characterization in the SDRG and RWD Reliability Assessment.
325+
- Sponsors who want to bind a specific MapID or Coordinate to a specific declared source MAY do so via implementer-defined conventions referencing the `rwdl:source/@OID`, but no formal mechanism is specified in V1.
255326

256327

257328

@@ -320,25 +391,43 @@ The core of the RWD-Lineage file is a collection (array) of `<MapID>` elements.
320391

321392
### Example 3 — FHIR data via API
322393

394+
This example illustrates how `rwdl:sourceMetadata` is declared once at the document root using the nested `rwdl:source`/`rwdl:standard` architecture, and how the per-coordinate MapID then carries only the addressing information. The FHIR R4 conformance of the source is captured on the nested `rwdl:standard` element; the parent `rwdl:source` names the origin system. The conformance is declared once at the document root.
395+
323396
```xml
324-
<MapID uuid="e5e13010-0dg1-5222-9180-3f76452845c3">
325-
<Transformation type="Extraction">JSON Path Extraction</Transformation>
326-
<!-- Source: FHIR API Endpoint -->
327-
<Source>
328-
<Coordinate storage="API" structure="PATH">
329-
<URI>https://api.hospital.org/fhir/R4/MedicationRequest/med-abc-123</URI>
330-
<Path syntax="JSONPATH">$.medicationCodeableConcept.coding[0].code</Path>
331-
</Coordinate>
332-
</Source>
333-
<!-- Target: SDTM CM Domain -->
334-
<Target>
335-
<Coordinate storage="FILESYSTEM" structure="TABULAR">
336-
<URI>./sdtm/cm.xpt</URI>
337-
<RowIndex>8</RowIndex>
338-
<ColumnName>CMDECOD</ColumnName>
339-
</Coordinate>
340-
</Target>
341-
</MapID>
397+
<rwdl:lineage xmlns:rwdl="http://www.cdisc.org/ns/rwdl/v1.0">
398+
399+
<!-- Document-level source declaration: declared once for the file -->
400+
<rwdl:sourceMetadata>
401+
<rwdl:source OID="SRC.EHR.1"
402+
name="University Hospital Epic Interconnect"
403+
description="Hospital FHIR API at api.hospital.org">
404+
<rwdl:standard name="FHIR" version="R4" status="Final"/>
405+
</rwdl:source>
406+
</rwdl:sourceMetadata>
407+
408+
<MapID uuid="e5e13010-0dg1-5222-9180-3f76452845c3">
409+
<Transformation type="Extraction">JSON Path Extraction</Transformation>
410+
<!-- Source: FHIR API Endpoint -->
411+
<Source>
412+
<Coordinate storage="API" structure="PATH">
413+
<URI>https://api.hospital.org/fhir/R4/MedicationRequest/med-abc-123</URI>
414+
<Path syntax="JSONPATH">$.medicationCodeableConcept.coding[0].code</Path>
415+
</Coordinate>
416+
</Source>
417+
<!-- Target: SDTM CM Domain -->
418+
<Target>
419+
<Coordinate storage="FILESYSTEM" structure="TABULAR">
420+
<URI>./sdtm/cm.xpt</URI>
421+
<RowIndex>8</RowIndex>
422+
<ColumnName>CMDECOD</ColumnName>
423+
</Coordinate>
424+
</Target>
425+
</MapID>
426+
427+
<!-- Additional MapID elements pulling from the same FHIR source follow;
428+
each carries only addressing information, not source metadata -->
429+
430+
</rwdl:lineage>
342431
```
343432

344433
### Example 4 — XML data in filesystem

0 commit comments

Comments
 (0)