Properties and annotations

Properties and annotations, implementation details

In Synapse, entities have both properties and annotations. Properties are used by the system, whereas annotations are completely user defined. In synapser, each entity is an object such as a File, Folder, or Project:

Properties are the object’s own fields, such as id, name, description, and parent_id. You read them with $, for example file$description.
Annotations are stored together in a single field, annotations, which is a named list where each name is an annotation key, for example file$annotations.

Printing an entity will show its properties, with its annotations listed under annotations.

library(synapser)
synLogin()

file <- synGet("syn123", file_options = FileOptions(download_file = FALSE))
print(file)

Properties and annotations are kept separate

Because annotations live in their own named list, a property and an annotation can share a name without overwriting each other. Each one is always read from its own place:

file <- file |>
  synSetProperties(
    description = "One thing",
    annotations = list(description = "A different thing")
  ) |>
  synStore()

file$description # the property
#> [1] "One thing"
file$annotations[["description"]] # the annotation

Even so, it is recommended to avoid defining annotations with names that collide with properties, because the two are easy to confuse when you read or query your data.

Setting properties and annotations

Use synSetProperties() to change both properties and annotations, then synStore() to save the changes to Synapse. Properties are set by name, and annotations are set through the annotations argument:

file <- file |>
  synSetProperties(
    name = "new name",
    annotations = append(file$annotations, list(species = "Homo sapiens"))
  ) |>
  synStore()

synSetProperties() only accepts names that are properties of the entity. Passing any other name is an error, rather than silently creating a new annotation:

file |> synSetProperties(species = "Homo sapiens")
#> Error: The following are not valid attributes of this entity: species

To add, update, or remove annotations, change the annotations named list as shown in Add, Update and Remove Annotations.