---
title: "Properties and annotations"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Properties and annotations}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## 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`.

```{r eval=FALSE}
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:

```{r eval=FALSE}
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:

```{r eval=FALSE}
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:

```{r eval=FALSE}
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](data_upload_download.html#add-update-and-remove-annotations).

See also:

- [`synSetProperties`](../reference/synSetProperties.html)
- [Annotations](domain_models_of_synapse.html#annotations)