diff --git a/NAMESPACE b/NAMESPACE
index 52a6ca514..7f3980cd9 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -1,9 +1,15 @@
 # Generated by roxygen2: do not edit by hand
 
 S3method("[",JoinKeys)
+S3method("[",Placeholder)
 S3method("[<-",JoinKeys)
+S3method("[<-",Placeholder)
 S3method("get_join_keys<-",JoinKeys)
 S3method("get_join_keys<-",teal_data)
+S3method("join_keys<-",Placeholder)
+S3method("parents<-",Placeholder)
+S3method("parents[",Placeholder)
+S3method("parents[<-",Placeholder)
 S3method(as_cdisc,TealDataset)
 S3method(as_cdisc,TealDatasetConnector)
 S3method(dataset,MultiAssayExperiment)
@@ -52,7 +58,10 @@ S3method(mutate_dataset,TealDataAbstract)
 S3method(mutate_dataset,TealDataset)
 S3method(mutate_dataset,TealDatasetConnector)
 S3method(mutate_join_keys,JoinKeys)
+S3method(mutate_join_keys,Placeholder)
 S3method(mutate_join_keys,TealData)
+S3method(parents,Placeholder)
+S3method(print,Placeholder)
 S3method(set_args,CallableCode)
 S3method(set_args,CallableFunction)
 S3method(set_args,TealDatasetConnector)
@@ -68,6 +77,10 @@ export("col_labels<-")
 export("data_label<-")
 export("datanames<-")
 export("get_join_keys<-")
+export("parents<-")
+export("parents[")
+export("parents[<-")
+export("parents[[<-")
 export(as_cdisc)
 export(callable_code)
 export(callable_function)
@@ -113,9 +126,11 @@ export(join_keys)
 export(load_dataset)
 export(load_datasets)
 export(mae_dataset)
+export(merge_join_keys)
 export(mutate_data)
 export(mutate_dataset)
 export(mutate_join_keys)
+export(parents)
 export(python_cdisc_dataset_connector)
 export(python_code)
 export(python_dataset_connector)
@@ -127,6 +142,7 @@ export(script_cdisc_dataset_connector)
 export(script_dataset_connector)
 export(set_args)
 export(set_keys)
+export(split_join_keys)
 export(teal_data)
 export(teal_data_file)
 export(to_relational_data)
diff --git a/R/JoinKeys.R b/R/JoinKeys.R
index 0b9255fb2..44604a46a 100644
--- a/R/JoinKeys.R
+++ b/R/JoinKeys.R
@@ -37,43 +37,16 @@ JoinKeys <- R6::R6Class( # nolint
     #' Split the current `JoinKeys` object into a named list of join keys objects with an element for each dataset
     #' @return (`list`) a list of `JoinKeys` object
     split = function() {
-      list_of_list_of_join_key_set <- lapply(
-        names(self$get()),
-        function(dataset_1) {
-          lapply(
-            names(self$get()[[dataset_1]]),
-            function(dataset_2) join_key(dataset_1, dataset_2, self$get()[[dataset_1]][[dataset_2]])
-          )
-        }
-      )
-      res <- lapply(
-        list_of_list_of_join_key_set,
-        function(x) {
-          y <- JoinKeys$new()
-          y$set(x)
-        }
-      )
-      names(res) <- names(self$get())
-
-      logger::log_trace("JoinKeys$split keys split.")
-      return(res)
+      split_join_keys(self)
     },
     #' @description
     #' Merging a list (or one) of `JoinKeys` objects into the current `JoinKeys` object
     #' @param x  `list` of `JoinKeys` objects or single `JoinKeys` object
     #' @return (`self`) invisibly for chaining
     merge = function(x) {
-      if (inherits(x, "JoinKeys")) x <- list(x)
-      checkmate::assert_list(x, types = "JoinKeys", min.len = 1)
-      for (jk in x) {
-        for (dataset_1 in names(jk$get())) {
-          for (dataset_2 in names(jk$get()[[dataset_1]])) {
-            self$mutate(dataset_1, dataset_2, jk$get()[[dataset_1]][[dataset_2]])
-          }
-        }
-      }
-      logger::log_trace("JoinKeys$merge keys merged.")
-      return(invisible(self))
+      result <- merge_join_keys(self, x)
+      class(result) <- "list"
+      private$.keys <- result
     },
     #' @description
     #' Get join keys between two datasets.
@@ -83,19 +56,11 @@ JoinKeys <- R6::R6Class( # nolint
     #' @details if one or both of `dataset_1` and `dataset_2` are missing then
     #' underlying keys structure is returned for further processing
     get = function(dataset_1, dataset_2) {
-      if (missing(dataset_1) && missing(dataset_2)) {
-        return(private$.keys)
-      }
-      if (missing(dataset_2)) {
-        return(private$.keys[[dataset_1]])
-      }
-      if (missing(dataset_1)) {
-        return(private$.keys[[dataset_2]])
-      }
-      if (is.null(private$.keys[[dataset_1]][[dataset_2]])) {
-        return(character(0))
-      }
-      return(private$.keys[[dataset_1]][[dataset_2]])
+      new_keys <- private$.keys
+      class(new_keys) <- "Placeholder"
+      res <- get_join_key(new_keys, dataset_1, dataset_2)
+      if (checkmate::test_class(res, "Placeholder")) class(res) <- "list"
+      res
     },
     #' @description
     #' Change join_keys for a given pair of dataset names (or
@@ -103,20 +68,12 @@ JoinKeys <- R6::R6Class( # nolint
     #' @param val (named `character`) column names used to join
     #' @return (`self`) invisibly for chaining
     mutate = function(dataset_1, dataset_2, val) {
-      checkmate::assert_string(dataset_1)
-      checkmate::assert_string(dataset_2)
-      checkmate::assert_character(val, any.missing = FALSE)
-
-      private$join_pair(join_key(dataset_1, dataset_2, val))
+      new_keys <- private$.keys
+      class(new_keys) <- "Placeholder"
+      res <- mutate_join_keys(new_keys, dataset_1, dataset_2, val)
+      class(res) <- "list"
 
-      logger::log_trace(
-        sprintf(
-          "JoinKeys$mutate updated the keys between %s and %s to %s",
-          dataset_1,
-          dataset_2,
-          paste(val, collapse = ", ")
-        )
-      )
+      private$.keys <- res
       return(invisible(self))
     },
     #' @description
@@ -127,24 +84,11 @@ JoinKeys <- R6::R6Class( # nolint
     #' to be specified once
     #' @return (`self`) invisibly for chaining
     set = function(x) {
-      if (length(private$.keys) > 0) {
-        stop("Keys already set, please use JoinKeys$mutate() to change them")
-      }
-      if (inherits(x, "JoinKeySet")) {
-        x <- list(x)
-      }
-
-      # check if any JoinKeySets share the same datasets but different values
-      for (idx_1 in seq_along(x)) {
-        for (idx_2 in seq_len(idx_1)) {
-          private$check_compatible_keys(x[[idx_1]], x[[idx_2]])
-        }
-      }
-
-      checkmate::assert_list(x, types = "JoinKeySet", min.len = 1)
-      lapply(x, private$join_pair)
-
-      logger::log_trace("JoinKeys$set keys are set.")
+      jk <- private$.keys
+      class(jk) <- c("Placeholder", "list")
+      join_keys(jk) <- x
+      class(jk) <- "list"
+      private$.keys <- jk
       return(invisible(self))
     },
     #' @description
@@ -153,18 +97,7 @@ JoinKeys <- R6::R6Class( # nolint
     #' @param ... additional arguments to the printing method
     #' @return invisibly self
     print = function(...) {
-      check_ellipsis(...)
-      keys_list <- self$get()
-      if (length(keys_list) > 0) {
-        cat(sprintf(
-          "A JoinKeys object containing foreign keys between %s datasets:\n",
-          length(keys_list)
-        ))
-        print(keys_list)
-      } else {
-        cat("An empty JoinKeys object.")
-      }
-      invisible(self)
+      print.Placeholder(private$.keys)
     },
     #' @description
     #' Sets the parents of the datasets.
@@ -254,63 +187,9 @@ JoinKeys <- R6::R6Class( # nolint
     .keys = list(),
     parents = list(),
     join_pair = function(join_key) {
-      dataset_1 <- join_key$dataset_1
-      dataset_2 <- join_key$dataset_2
-      keys <- join_key$keys
-
-      if (is.null(private$.keys[[dataset_1]])) {
-        private$.keys[[dataset_1]] <- list()
-      }
-      private$.keys[[dataset_1]][[dataset_2]] <- keys
-
-      if (dataset_2 != dataset_1) {
-        if (is.null(private$.keys[[dataset_2]])) {
-          private$.keys[[dataset_2]] <- list()
-        }
-
-        if (length(keys) > 0) {
-          keys <- setNames(names(keys), keys)
-        }
-        private$.keys[[dataset_2]][[dataset_1]] <- keys
-      }
-    },
-    # helper function to deterimine if two key sets contain incompatible keys
-    # return TRUE if compatible, throw error otherwise
-    check_compatible_keys = function(join_key_1, join_key_2) {
-      error_message <- function(dataset_1, dataset_2) {
-        stop(
-          paste("cannot specify multiple different join keys between datasets:", dataset_1, "and", dataset_2)
-        )
-      }
-
-
-      # if first datasets and the second datasets match and keys
-      # must contain the same named elements
-      if (join_key_1$dataset_1 == join_key_2$dataset_1 && join_key_1$dataset_2 == join_key_2$dataset_2) {
-        if (!identical(sort(join_key_1$keys), sort(join_key_2$keys))) {
-          error_message(join_key_1$dataset_1, join_key_1$dataset_2)
-        }
-      }
-
-      # if first dataset of join_key_1 matches second dataset of join_key_2
-      # and the first dataset of join_key_2 must match second dataset of join_key_1
-      # and keys must contain the same elements but with names and values swapped
-      if (join_key_1$dataset_1 == join_key_2$dataset_2 && join_key_1$dataset_2 == join_key_2$dataset_1) {
-        # have to handle empty case differently as names(character(0)) is NULL
-        if (length(join_key_1$keys) == 0 && length(join_key_2$keys) == 0) {
-          return(TRUE)
-        }
-
-        if (
-          xor(length(join_key_1$keys) == 0, length(join_key_2$keys) == 0) ||
-            !identical(sort(join_key_1$keys), sort(setNames(names(join_key_2$keys), join_key_2$keys)))
-        ) {
-          error_message(join_key_1$dataset_1, join_key_1$dataset_2)
-        }
-      }
-
-      # otherwise they are compatible
-      return(TRUE)
+      res <- join_pair(self, join_key)
+      class(res) <- "list"
+      private$.keys <- res
     },
     # checks the parent child relations are valid
     check_parent_child = function() {
@@ -365,6 +244,17 @@ JoinKeys <- R6::R6Class( # nolint
 #'
 join_keys <- function(...) {
   x <- rlang::list2(...)
+
+  # Getter
+  if (checkmate::test_list(x, len = 1, types = c("Placeholder", "JoinKeys"))) {
+    return(x[[1]])
+  } else if (checkmate::test_list(x, len = 1, types = c("teal_data"))) {
+    return(x[[1]]@join_keys)
+  } else if (checkmate::test_list(x, len = 1, types = c("TealData"))) {
+    return(x[[1]]$get_join_keys())
+  }
+
+  # Constructor
   res <- JoinKeys$new()
   if (length(x) > 0) {
     res$set(x)
diff --git a/R/new_join_keys.R b/R/new_join_keys.R
new file mode 100644
index 000000000..b20e45ba6
--- /dev/null
+++ b/R/new_join_keys.R
@@ -0,0 +1,337 @@
+#' Setter for join keys
+#'
+#' @param data (`JoinKeys`) empty object to set the new relationship pairs.
+#' @param value (`JoinKeySet` or list of `JoinKeySet`) relationship pairs to add
+#' to `JoinKeys` list.
+#'
+#' @rdname get_keys
+`join_keys<-` <- function(join_keys_obj, value) {
+  UseMethod("join_keys<-", join_keys_obj)
+}
+
+#' @rdname get_keys
+#' @export
+#' @examples
+#' jk <- new_join_keys()
+#' join_keys(jk)
+#' join_keys(jk) <- join_key("ds1", "ds2", "some_col2")
+`join_keys<-.Placeholder` <- function(join_keys_obj, value) {
+  if (missing(value)) {
+    return(join_keys_obj)
+  }
+
+  if (length(join_keys_obj) > 0) {
+    stop("Keys already set, please use mutate_join_keys() or to change them")
+  }
+
+  if (inherits(value, "JoinKeySet")) value <- list(value)
+
+  checkmate::assert_list(value, types = "JoinKeySet", min.len = 1)
+
+  # check if any JoinKeySets share the same datasets but different values
+  for (idx_1 in seq_along(value)) {
+    for (idx_2 in seq_along(value[idx_1])) {
+      assert_compatible_keys(value[[idx_1]], value[[idx_2]])
+    }
+    join_keys_obj <- join_pair(join_keys_obj, value[[idx_1]])
+  }
+
+  logger::log_trace("JoinKeys keys are set.")
+
+  join_keys_obj
+}
+
+#' @title Getter for JoinKeys that returns the relationship between pairs of datasets
+#' @param x JoinKeys object to extract the join keys
+#' @param dataset_1 (`character`) name of first dataset.
+#' @param dataset_2 (`character`) name of second dataset.
+#'
+#' @export
+#'
+#' @examples
+#' jk <- new_join_keys()
+#' join_keys(jk) <- list(ds1 = list(ds2 = "some_col"))
+#' jk["ds1", "ds2"]
+`[.Placeholder` <- function(x, dataset_1, dataset_2 = dataset_1) {
+  checkmate::assert_string(dataset_1)
+  checkmate::assert_string(dataset_2, null.ok = TRUE)
+
+  x[[dataset_1]][[dataset_2]]
+}
+
+#' @rdname sub-.Placeholder
+#' @param keys value to assign
+#' @export
+#' @keywords internal
+#' @examples
+#' jk <- new_join_keys()
+#' jk["ds1", "ds2"]
+#' join_keys(jk) <- join_key("ds1", "ds2", "some_col")
+#' jk["ds1", "ds2"]
+#' jk["ds1", "ds2"] <- "new_col"
+#' jk["ds1", "ds2"]
+`[<-.Placeholder` <- function(data, dataset_1, dataset_2 = dataset_1, value) {
+  checkmate::assert_string(dataset_1)
+  checkmate::assert_string(dataset_2, null.ok = TRUE)
+
+  if (is.null(data[[dataset_1]])) data[[dataset_1]] <- list()
+
+  data[[dataset_1]][[dataset_2]] <- value
+
+  if (identical(dataset_1, dataset_2)) {
+    return(data)
+  }
+
+  if (is.null(data[[dataset_2]])) data[[dataset_2]] <- list()
+
+  if (
+    checkmate::test_character(value, min.len = 1) &&
+      !checkmate::test_names(names(value))
+  ) {
+    value <- setNames(value, value)
+  } else if (
+    checkmate::test_character(value, min.len = 1)
+  ) {
+    # Invert key
+    value <- setNames(names(value), value)
+  }
+
+  data[[dataset_2]][[dataset_1]] <- value
+
+  data
+}
+
+#' @rdname mutate_join_keys
+#' @export
+#' @examples
+#' jk <- new_join_keys()
+#' join_keys(jk) <- list(ds1 = list(ds2 = "some_col"))
+#' mutate_join_keys(jk, "ds2", "ds3", "another")
+mutate_join_keys.Placeholder <- function(x, dataset_1, dataset_2, value) {
+  checkmate::assert_string(dataset_1)
+  checkmate::assert_string(dataset_2)
+  checkmate::assert_character(value, any.missing = FALSE)
+
+  res <- join_pair(x, join_key(dataset_1, dataset_2, value))
+
+  logger::log_trace(
+    sprintf(
+      "JoinKeys updated the keys between %s and %s to %s",
+      dataset_1,
+      dataset_2,
+      paste(val, collapse = ", ")
+    )
+  )
+
+  res
+}
+
+#' Split the `JoinKeys` object into a named list of join keys objects with an
+#' element for each dataset
+#'
+#' @return (`list`) a list of `JoinKeys` object
+#' @export
+#' @examples
+#' jk <- new_join_keys()
+#' jk["ds1", "ds2"] <- "some_col"
+#' jk["ds1", "ds3"] <- "new_col"
+#' split_join_keys(jk)
+split_join_keys <- function(keys) {
+  checkmate::assert_multi_class(keys, classes = c("JoinKeys", "Placeholder"))
+
+  if (checkmate::test_class(keys, "JoinKeys")) {
+    keys <- keys$get()
+    class(keys) <- "Placeholder"
+  }
+
+  list_of_list_of_join_key_set <- lapply(
+    names(keys),
+    function(dataset_1) {
+      lapply(
+        names(keys[[dataset_1]]),
+        function(dataset_2) join_key(dataset_1, dataset_2, get_join_key(keys, dataset_1, dataset_2))
+      )
+    }
+  )
+  res <- lapply(list_of_list_of_join_key_set, function(.x) do.call(join_keys, .x))
+  names(res) <- names(keys)
+
+  logger::log_trace("JoinKeys keys split.")
+  return(res)
+}
+
+#' Merging a list (or one) of `JoinKeys` objects into the current `JoinKeys` object
+#'
+#' @param keys_1 `JoinKeys` object
+#' @param keys_2  `list` of `JoinKeys` objects or single `JoinKeys` object
+#'
+#' @return (`JoinKeys`) a new object with the resulting merge
+#'
+#' @export
+#'
+#' @examples
+#' jk1 <- new_join_keys()
+#' jk1["ds1", "ds2"] <- "some_col"
+#' jk2 <- new_join_keys()
+#' jk2["ds1", "ds3"] <- "new_col"
+#' merge_join_keys(jk1, jk2)
+merge_join_keys <- function(keys_1, keys_2) {
+  if (checkmate::test_class(keys_1, "JoinKeys")) {
+    keys_1 <- keys_1$get()
+    class(keys_1) <- "Placeholder"
+  }
+  checkmate::assert_multi_class(keys_1, c("JoinKeys", "Placeholder"))
+
+  if (inherits(keys_2, c("JoinKeys", "Placeholder"))) keys_2 <- list(keys_2)
+  checkmate::assert_list(keys_2, types = c("JoinKeys", "Placeholder"), min.len = 1)
+
+  new_keys <- keys_1
+
+  for (jk in keys_2) {
+    if (checkmate::test_class(jk, "JoinKeys")) jk <- jk$get()
+    for (dataset_1 in names(jk)) {
+      for (dataset_2 in names(jk[[dataset_1]])) {
+        new_keys[dataset_1, dataset_2] <- jk[[dataset_1]][[dataset_2]]
+      }
+    }
+  }
+  logger::log_trace("JoinKeys keys merged.")
+  return(new_keys)
+}
+
+#' Prints `JoinKeys`.
+#'
+#' @param ... additional arguments to the printing method
+#' @return the `x` parameter
+#'
+#' @export
+print.Placeholder <- function(x, ...) {
+  check_ellipsis(...)
+  keys_list <- x
+  class(keys_list) <- "list"
+  if (length(keys_list) > 0) {
+    cat(sprintf(
+      "A JoinKeys object containing foreign keys between %s datasets:\n",
+      length(keys_list)
+    ))
+    print.default(keys_list)
+  } else {
+    cat("An empty JoinKeys object.")
+  }
+  invisible(x)
+}
+
+# -----------------------------------------------------------------------------
+#
+#
+# Helpers (non-exported)
+#
+
+#' Internal constructor
+#'
+#' @return an empty `JoinKeys` list
+#'
+#' @keywords internal
+new_join_keys <- function() {
+  result <- list()
+  class(result) <- c("Placeholder", "list")
+  result
+}
+
+#' Get value of a single relationship pair
+#'
+#' @param join_keys_obj (`JoinKeys`) object that holds the relationship keys.
+#' @param dataset_1 (`character(1)`) one of the datasets to retrieve keys (
+#' order of the datasets is irrelevant).
+#' @param dataset_2 (`character(1)`) the other dataset to retrieve keys (the
+#' order of the datasets is irrelevant).
+#'
+#' @return Character vector with keys or (if one of the datasets is omitted) a
+#' list of relationship pairs. If both datasets are omitted it returens the
+#' `JoinKeys` object
+#'
+#' @keywords internal
+get_join_key <- function(join_keys_obj, dataset_1, dataset_2) {
+  checkmate::assert_multi_class(join_keys_obj, c("teal_data", "Placeholder"))
+  jk <- join_keys(join_keys_obj)
+
+  if (missing(dataset_1) && missing(dataset_2)) {
+    return(jk)
+  }
+  if (missing(dataset_2)) {
+    return(jk[[dataset_1]])
+  }
+  if (missing(dataset_1)) {
+    return(jk[[dataset_2]])
+  }
+  if (is.null(jk[[dataset_1]][[dataset_2]])) {
+    return(character(0))
+  }
+  return(jk[[dataset_1]][[dataset_2]])
+}
+
+#' Helper function to add a new pair to a `JoinKeys` object
+#'
+#' @param join_keys_obj (`JoinKeys`) Object with existing pairs.
+#' @param join_key_obj (`JoinKeySet`) relationship pair to add.
+#'
+#' @examples
+#' jk <- new_join_keys()
+#' jk <- join_pair(jk, join_key("ds1", "ds2", "value"))
+#' jk <- join_pair(jk, join_key("ds3", "ds2", "value"))
+join_pair <- function(join_keys_obj, join_key_obj) {
+  checkmate::assert_multi_class(join_keys_obj, c("JoinKeys", "Placeholder"))
+  checkmate::assert_class(join_key_obj, "JoinKeySet")
+
+  if (checkmate::test_class(join_keys_obj, "JoinKeys")) {
+    join_keys_obj <- join_keys_obj$get()
+    class(join_keys_obj) <- "Placeholder"
+  }
+
+  dataset_1 <- join_key_obj$dataset_1
+  dataset_2 <- join_key_obj$dataset_2
+  keys <- join_key_obj$keys
+
+  join_keys_obj[dataset_1, dataset_2] <- keys
+  join_keys_obj
+}
+
+#' Helper function to assert if two key sets contain incompatible keys
+#'
+#' return TRUE if compatible, throw error otherwise
+#' @keywords internal
+assert_compatible_keys <- function(join_key_1, join_key_2) {
+  error_message <- function(dataset_1, dataset_2) {
+    stop(
+      paste("cannot specify multiple different join keys between datasets:", dataset_1, "and", dataset_2)
+    )
+  }
+
+  # if first datasets and the second datasets match and keys
+  # must contain the same named elements
+  if (join_key_1$dataset_1 == join_key_2$dataset_1 && join_key_1$dataset_2 == join_key_2$dataset_2) {
+    if (!identical(sort(join_key_1$keys), sort(join_key_2$keys))) {
+      error_message(join_key_1$dataset_1, join_key_1$dataset_2)
+    }
+  }
+
+  # if first dataset of join_key_1 matches second dataset of join_key_2
+  # and the first dataset of join_key_2 must match second dataset of join_key_1
+  # and keys must contain the same elements but with names and values swapped
+  if (join_key_1$dataset_1 == join_key_2$dataset_2 && join_key_1$dataset_2 == join_key_2$dataset_1) {
+    # have to handle empty case differently as names(character(0)) is NULL
+    if (length(join_key_1$keys) == 0 && length(join_key_2$keys) == 0) {
+      return(TRUE)
+    }
+
+    if (
+      xor(length(join_key_1$keys) == 0, length(join_key_2$keys) == 0) ||
+        !identical(sort(join_key_1$keys), sort(setNames(names(join_key_2$keys), join_key_2$keys)))
+    ) {
+      error_message(join_key_1$dataset_1, join_key_1$dataset_2)
+    }
+  }
+
+  # otherwise they are compatible
+  return(TRUE)
+}
diff --git a/R/parents.R b/R/parents.R
new file mode 100644
index 000000000..545b590a5
--- /dev/null
+++ b/R/parents.R
@@ -0,0 +1,83 @@
+#' A name
+#' @export
+parents <- function(join_keys_obj) {
+  UseMethod("parents", join_keys_obj)
+}
+
+#' @rdname parents
+#' @export
+#' @examples
+#' jk <- new_join_keys()
+#' parents(jk)
+parents.Placeholder <- function(join_keys_obj) {
+  rlang::`%||%`(attr(join_keys_obj, "__parents__"), list())
+}
+
+#' @rdname parents
+#' @export
+#' @examples
+#' jk <- new_join_keys()
+#' parents(jk) <- list(ADSL = "ADTTE")
+`parents<-` <- function(join_keys_obj, value) {
+  UseMethod("parents<-", join_keys_obj)
+}
+
+#' @rdname parents
+#' @export
+#' @examples
+#' jk <- new_join_keys()
+#' parents(jk)["ADTTE"] <- "ADSL"
+`parents<-.Placeholder` <- function(join_keys_obj, value) {
+  checkmate::assert_list(value, types = "character", names = "named", min.len = 1)
+  attr(join_keys_obj, "__parents__") <- value
+  join_keys_obj
+}
+
+
+#' @rdname parents
+#' @export
+#' @examples
+`parents[` <- function(join_keys_obj, dataset) {
+  UseMethod("parents[", join_keys_obj)
+}
+
+#' @rdname parents
+#' @export
+#' @examples
+#' jk <- new_join_keys()
+#' parents(jk)["ADTTE"] <- "ADSL"
+#' parents(jk)["YADA"]
+`parents[.Placeholder` <- function(join_keys_obj, dataset) {
+  checkmate::assert_list(dataset, min.len = 1, names = "named")
+  res <- attr(join_keys_obj, "__parents__")[[dataset]]
+  if (is.null(res)) {
+    return(NULL)
+  }
+  res
+}
+
+#' @rdname parents
+#' @export
+`parents[[<-` <- function(join_keys_obj, dataset, value) {
+  UseMethod("parent[<-", join_keys_obj)
+}
+
+#' @rdname parents
+#' @export
+`parents[<-` <- function(join_keys_obj, dataset, value) {
+  UseMethod("parent[<-", join_keys_obj)
+}
+
+#' @rdname parents
+#' @export
+#' @examples
+#' jk <- new_join_keys()
+#' parents(jk)["ADTTE"] <- "ADSL"
+`parents[<-.Placeholder` <- function(join_keys_obj, dataset, value) {
+  checkmate::assert_character(dataset, min.len = 1)
+  if (is.null(attr(join_keys_obj, "__parents__"))) {
+    attr(join_keys_obj, "__parents__") <- list()
+  }
+  attr(join_keys_obj, "__parents__") <- dataset
+  join_keys_obj
+}
diff --git a/inst/WORDLIST b/inst/WORDLIST
index bf67939a4..b1ea8634f 100644
--- a/inst/WORDLIST
+++ b/inst/WORDLIST
@@ -1,16 +1,17 @@
 CDISC
+cloneable
 Forkers
+formatters
+funder
 Getter
 Hoffmann
+iteratively
 JoinKeys
 Pre
-Reproducibility
-SCDA
-UI
-cloneable
-formatters
-funder
-iteratively
 pre
 repo
+Reproducibility
 reproducibility
+returens
+SCDA
+UI
diff --git a/man/assert_compatible_keys.Rd b/man/assert_compatible_keys.Rd
new file mode 100644
index 000000000..e7b9751bb
--- /dev/null
+++ b/man/assert_compatible_keys.Rd
@@ -0,0 +1,12 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/new_join_keys.R
+\name{assert_compatible_keys}
+\alias{assert_compatible_keys}
+\title{Helper function to assert if two key sets contain incompatible keys}
+\usage{
+assert_compatible_keys(join_key_1, join_key_2)
+}
+\description{
+return TRUE if compatible, throw error otherwise
+}
+\keyword{internal}
diff --git a/man/get_join_key.Rd b/man/get_join_key.Rd
new file mode 100644
index 000000000..2b31c51a3
--- /dev/null
+++ b/man/get_join_key.Rd
@@ -0,0 +1,26 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/new_join_keys.R
+\name{get_join_key}
+\alias{get_join_key}
+\title{Get value of a single relationship pair}
+\usage{
+get_join_key(join_keys_obj, dataset_1, dataset_2)
+}
+\arguments{
+\item{join_keys_obj}{(\code{JoinKeys}) object that holds the relationship keys.}
+
+\item{dataset_1}{(\code{character(1)}) one of the datasets to retrieve keys (
+order of the datasets is irrelevant).}
+
+\item{dataset_2}{(\code{character(1)}) the other dataset to retrieve keys (the
+order of the datasets is irrelevant).}
+}
+\value{
+Character vector with keys or (if one of the datasets is omitted) a
+list of relationship pairs. If both datasets are omitted it returens the
+\code{JoinKeys} object
+}
+\description{
+Get value of a single relationship pair
+}
+\keyword{internal}
diff --git a/man/get_keys.Rd b/man/get_keys.Rd
index 447871856..63996f7e8 100644
--- a/man/get_keys.Rd
+++ b/man/get_keys.Rd
@@ -1,10 +1,12 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/get_keys.R
+% Please edit documentation in R/get_keys.R, R/new_join_keys.R
 \name{get_keys}
 \alias{get_keys}
 \alias{get_keys.TealDataset}
 \alias{get_keys.TealDatasetConnector}
 \alias{get_keys.TealDataAbstract}
+\alias{join_keys<-}
+\alias{join_keys<-.Placeholder}
 \title{Get dataset primary keys}
 \usage{
 get_keys(x, ...)
@@ -14,6 +16,10 @@ get_keys(x, ...)
 \method{get_keys}{TealDatasetConnector}(x, ...)
 
 \method{get_keys}{TealDataAbstract}(x, dataname, ...)
+
+join_keys(join_keys_obj) <- value
+
+\method{join_keys}{Placeholder}(join_keys_obj) <- value
 }
 \arguments{
 \item{x}{an object of \code{TealDataset} or \code{TealDatasetConnector} class}
@@ -21,6 +27,11 @@ get_keys(x, ...)
 \item{...}{not used, only for support of S3}
 
 \item{dataname}{(\code{character}) name of dataset to return keys for}
+
+\item{value}{(\code{JoinKeySet} or list of \code{JoinKeySet}) relationship pairs to add
+to \code{JoinKeys} list.}
+
+\item{data}{(\code{JoinKeys}) empty object to set the new relationship pairs.}
 }
 \value{
 (\code{character}) vector of column names
@@ -60,4 +71,7 @@ get_keys(
   ),
   "x"
 )
+jk <- new_join_keys()
+join_keys(jk)
+join_keys(jk) <- join_key("ds1", "ds2", "some_col2")
 }
diff --git a/man/join_pair.Rd b/man/join_pair.Rd
new file mode 100644
index 000000000..85a29e096
--- /dev/null
+++ b/man/join_pair.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/new_join_keys.R
+\name{join_pair}
+\alias{join_pair}
+\title{Helper function to add a new pair to a \code{JoinKeys} object}
+\usage{
+join_pair(join_keys_obj, join_key_obj)
+}
+\arguments{
+\item{join_keys_obj}{(\code{JoinKeys}) Object with existing pairs.}
+
+\item{join_key_obj}{(\code{JoinKeySet}) relationship pair to add.}
+}
+\description{
+Helper function to add a new pair to a \code{JoinKeys} object
+}
+\examples{
+jk <- new_join_keys()
+jk <- join_pair(jk, join_key("ds1", "ds2", "value"))
+jk <- join_pair(jk, join_key("ds3", "ds2", "value"))
+}
diff --git a/man/merge_join_keys.Rd b/man/merge_join_keys.Rd
new file mode 100644
index 000000000..97589295a
--- /dev/null
+++ b/man/merge_join_keys.Rd
@@ -0,0 +1,26 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/new_join_keys.R
+\name{merge_join_keys}
+\alias{merge_join_keys}
+\title{Merging a list (or one) of \code{JoinKeys} objects into the current \code{JoinKeys} object}
+\usage{
+merge_join_keys(keys_1, keys_2)
+}
+\arguments{
+\item{keys_1}{\code{JoinKeys} object}
+
+\item{keys_2}{\code{list} of \code{JoinKeys} objects or single \code{JoinKeys} object}
+}
+\value{
+(\code{JoinKeys}) a new object with the resulting merge
+}
+\description{
+Merging a list (or one) of \code{JoinKeys} objects into the current \code{JoinKeys} object
+}
+\examples{
+jk1 <- new_join_keys()
+jk1["ds1", "ds2"] <- "some_col"
+jk2 <- new_join_keys()
+jk2["ds1", "ds3"] <- "new_col"
+merge_join_keys(jk1, jk2)
+}
diff --git a/man/mutate_join_keys.Rd b/man/mutate_join_keys.Rd
index 78a4ef57c..b075abce6 100644
--- a/man/mutate_join_keys.Rd
+++ b/man/mutate_join_keys.Rd
@@ -1,9 +1,10 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/JoinKeys.R
+% Please edit documentation in R/JoinKeys.R, R/new_join_keys.R
 \name{mutate_join_keys}
 \alias{mutate_join_keys}
 \alias{mutate_join_keys.JoinKeys}
 \alias{mutate_join_keys.TealData}
+\alias{mutate_join_keys.Placeholder}
 \title{Mutate \code{JoinKeys} with a new values}
 \usage{
 mutate_join_keys(x, dataset_1, dataset_2, val)
@@ -11,6 +12,8 @@ mutate_join_keys(x, dataset_1, dataset_2, val)
 \method{mutate_join_keys}{JoinKeys}(x, dataset_1, dataset_2, val)
 
 \method{mutate_join_keys}{TealData}(x, dataset_1, dataset_2, val)
+
+\method{mutate_join_keys}{Placeholder}(x, dataset_1, dataset_2, value)
 }
 \arguments{
 \item{x}{(\code{JoinKeys}) object to be modified}
@@ -52,4 +55,7 @@ x$get_join_keys()$get("ADSL", "ADRS")
 
 mutate_join_keys(x, "ADSL", "ADRS", c("COLUMN1" = "COLUMN2"))
 x$get_join_keys()$get("ADSL", "ADRS")
+jk <- new_join_keys()
+join_keys(jk) <- list(ds1 = list(ds2 = "some_col"))
+mutate_join_keys(jk, "ds2", "ds3", "another")
 }
diff --git a/man/new_join_keys.Rd b/man/new_join_keys.Rd
new file mode 100644
index 000000000..4fa64a9c8
--- /dev/null
+++ b/man/new_join_keys.Rd
@@ -0,0 +1,15 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/new_join_keys.R
+\name{new_join_keys}
+\alias{new_join_keys}
+\title{Internal constructor}
+\usage{
+new_join_keys()
+}
+\value{
+an empty \code{JoinKeys} list
+}
+\description{
+Internal constructor
+}
+\keyword{internal}
diff --git a/man/parents.Rd b/man/parents.Rd
new file mode 100644
index 000000000..8956145e8
--- /dev/null
+++ b/man/parents.Rd
@@ -0,0 +1,48 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/parents.R
+\name{parents}
+\alias{parents}
+\alias{parents.Placeholder}
+\alias{parents<-}
+\alias{parents<-.Placeholder}
+\alias{parents[}
+\alias{parents[.Placeholder}
+\alias{parents[[<-}
+\alias{parents[<-}
+\alias{parents[<-.Placeholder}
+\title{A name}
+\usage{
+parents(join_keys_obj)
+
+\method{parents}{Placeholder}(join_keys_obj)
+
+parents(join_keys_obj) <- value
+
+\method{parents}{Placeholder}(join_keys_obj) <- value
+
+`parents[`(join_keys_obj, dataset)
+
+\method{parents[}{Placeholder}(join_keys_obj, dataset)
+
+`parents[[`(join_keys_obj, dataset) <- value
+
+`parents[`(join_keys_obj, dataset) <- value
+
+\method{parents[}{Placeholder}(join_keys_obj, dataset) <- value
+}
+\description{
+A name
+}
+\examples{
+jk <- new_join_keys()
+parents(jk)
+jk <- new_join_keys()
+parents(jk) <- list(ADSL = "ADTTE")
+jk <- new_join_keys()
+parents(jk)["ADTTE"] <- "ADSL"
+jk <- new_join_keys()
+parents(jk)["ADTTE"] <- "ADSL"
+parents(jk)[["YADA"]]
+jk <- new_join_keys()
+parents(jk)["ADTTE"] <- "ADSL"
+}
diff --git a/man/print.Placeholder.Rd b/man/print.Placeholder.Rd
new file mode 100644
index 000000000..71ccad877
--- /dev/null
+++ b/man/print.Placeholder.Rd
@@ -0,0 +1,17 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/new_join_keys.R
+\name{print.Placeholder}
+\alias{print.Placeholder}
+\title{Prints \code{JoinKeys}.}
+\usage{
+\method{print}{Placeholder}(x, ...)
+}
+\arguments{
+\item{...}{additional arguments to the printing method}
+}
+\value{
+the \code{x} parameter
+}
+\description{
+Prints \code{JoinKeys}.
+}
diff --git a/man/split_join_keys.Rd b/man/split_join_keys.Rd
new file mode 100644
index 000000000..50af6fb5f
--- /dev/null
+++ b/man/split_join_keys.Rd
@@ -0,0 +1,22 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/new_join_keys.R
+\name{split_join_keys}
+\alias{split_join_keys}
+\title{Split the \code{JoinKeys} object into a named list of join keys objects with an
+element for each dataset}
+\usage{
+split_join_keys(keys)
+}
+\value{
+(\code{list}) a list of \code{JoinKeys} object
+}
+\description{
+Split the \code{JoinKeys} object into a named list of join keys objects with an
+element for each dataset
+}
+\examples{
+jk <- new_join_keys()
+jk["ds1", "ds2"] <- "some_col"
+jk["ds1", "ds3"] <- "new_col"
+split_join_keys(jk)
+}
diff --git a/man/sub-.Placeholder.Rd b/man/sub-.Placeholder.Rd
new file mode 100644
index 000000000..f5052abea
--- /dev/null
+++ b/man/sub-.Placeholder.Rd
@@ -0,0 +1,35 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/new_join_keys.R
+\name{[.Placeholder}
+\alias{[.Placeholder}
+\alias{[<-.Placeholder}
+\title{Getter for JoinKeys that returns the relationship between pairs of datasets}
+\usage{
+\method{[}{Placeholder}(x, dataset_1, dataset_2 = NULL)
+
+\method{[}{Placeholder}(data, dataset_1, dataset_2 = NULL) <- value
+}
+\arguments{
+\item{x}{JoinKeys object to extract the join keys}
+
+\item{dataset_1}{(\code{character}) name of first dataset.}
+
+\item{dataset_2}{(\code{character}) name of second dataset.}
+
+\item{keys}{value to assign}
+}
+\description{
+Getter for JoinKeys that returns the relationship between pairs of datasets
+}
+\examples{
+jk <- new_join_keys()
+join_keys(jk) <- list(ds1 = list(ds2 = "some_col"))
+jk["ds1", "ds2"]
+jk <- new_join_keys()
+jk["ds1", "ds2"]
+join_keys(jk) <- join_key("ds1", "ds2", "some_col")
+jk["ds1", "ds2"]
+jk["ds1", "ds2"] <- "new_col"
+jk["ds1", "ds2"]
+}
+\keyword{internal}