relation: Add or retrieve related items (DataCite/Dublin Core)

In dataset: Create Data Frames for Exchange and Reuse

Add or retrieve related items (DataCite/Dublin Core)

Description

Manage related resources for a dataset using a unified accessor.

• For DataCite 4.x, this maps to relatedIdentifier (+ type & relation).

• For Dublin Core, this maps to dct:relation (string).

Usage

relation(x)

relation(x) <- value

related_create(
  relatedIdentifier,
  relationType,
  relatedIdentifierType,
  resourceTypeGeneral = NULL
)

is.related(x)

related_item(x)

related_item(x) <- value

Arguments

x	A dataset object created with dataset_df() or as_dataset_df().
value	A related object from related_create() or a character. Vectors of characters are also supported and will be converted to a list of "related" objects.
relatedIdentifier	A string with the identifier of the related resource.
relationType	A string naming the relation type (per DataCite vocabulary).
relatedIdentifierType	A string naming the identifier type ("DOI", "URL", etc.).
resourceTypeGeneral	Optional: a string naming the general type of the related resource.

Details

To remain compatible with utils::bibentry(), the bibentry stores only the string identifier (e.g., DOI/URL). The full structured object created by related_create() is preserved in the "relation" attribute.

A "related" object is a small S3 list with the following elements:

• relatedIdentifier: the related resource identifier (DOI, URL, etc.)

• relationType: the DataCite relation type (e.g., "IsPartOf", "References")

• relatedIdentifierType: the type of identifier ("DOI", "URL", etc.)

• resourceTypeGeneral: optional, the general type of the related resource (e.g., "Text", "Dataset")

Value

• relation(x) returns:

  • a single structured "related" object (from related_create()) if only one relation is present,

  • a list of "related" objects if multiple relations are present,

  • otherwise it falls back to the bibentry field (relatedidentifier for DataCite or relation for Dublin Core).

• relation(x) <- value sets the "relation" attribute (structured object or list of objects) and the bibentry string fields (relatedidentifier and relation), and returns the dataset invisibly.

• related_create() constructs a structured "related" object.

• is.related(x) returns TRUE if x inherits from class "related".

See Also

Other bibliographic helper functions: contributor(), creator(), dataset_format(), dataset_title(), description(), geolocation(), get_bibentry(), language, publication_year(), publisher(), rights(), subject()

Examples

df <- dataset_df(data.frame(x = 1))
relation(df) <- related_create(
  relatedIdentifier = "10.1234/example",
  relationType = "IsPartOf",
  relatedIdentifierType = "DOI"
)
relation(df) # structured object
get_bibentry(df)$relation # "10.1234/example"
get_bibentry(df)$relatedidentifier # "10.1234/example"

# Character input is normalized to a DOI/URL with default types
relation(df) <- "https://doi.org/10.5678/xyz"
relation(df) # structured object (relationType/Type filled with defaults)

# Create related object directly
rel <- related_create("https://doi.org/10.5678/xyz", "References", "DOI")
is.related(rel) # TRUE

dataset documentation built on Nov. 16, 2025, 5:06 p.m.