Migrating to synapser 3.0

1. Instance-first, then pipe

Every entity is now a real object you construct directly — File(...), Folder(...), Table(...), Project(...), … — and every operation on it is a “verb” function (synStore(), synGet(), synSetProperties(), synAddColumn(), synDeleteRows(), …) that takes the instance as its first argument. You construct the object first, then thread it through a chain of these verbs with the native pipe, tidyverse-style, instead of reassigning a variable at every step:

# 2.x -- synStore() was one Python-backed function shared by every entity
# type, with Python duck-typing on `obj` internally; each step reassigned a
# variable rather than chaining
file <- File(path, parentId = "syn123")
file <- synStore(file)
file <- synGet(file$properties$id, downloadFile = FALSE)

# 3.0 -- construct the instance, then pipe it through verbs
file <- File(path = path, parent_id = "syn123") |>
  synStore() |>
  synGet(file_options = FileOptions(download_file = FALSE))

This is the change everything else in this guide follows from. Two kinds of function take an instance this way:

• synStore(), synGet(), and synDelete() are single factory functions that accept any supported entity — or, for synGet() and synDelete(), a Synapse ID string instead — and apply the behavior appropriate to that entity’s type.
• Every other verb (synAddColumn(), synGetAcl(), synCopy(), synWalk(), synBindSchema(), …) is a generic that dispatches on the class of the object you pipe in. The same verb name therefore works uniformly across every entity type that supports it, instead of each operation being its own hand-written function reconciling the differences between entity types internally.

2. Properties are no longer nested under $properties and synSetProperties

Properties and annotations are now plain fields on the object. Read them directly, and update them with the convenience function synSetProperties(), which sets any number of fields, including annotations, in one call and returns the entity so you can pipe it into synStore():

# 2.x
entity$properties$id
entity$properties$name
entity$annotations$assay

# 3.0
entity$id
entity$name
entity$annotations$assay

synGet(synapse_id) |>
  synSetProperties(
    name = "new name",
    version_label = "2",
    annotations = list(assay = "RNA-seq")
  ) |>
  synStore()

Setting annotations replaces all of the entity’s existing annotations. To add to them instead, combine them first: synSetProperties(annotations = append(entity$annotations, list(key = "value"))).

3. Arguments are snake_case, matching the Python client exactly

# 2.x
synGet(entity, downloadFile = FALSE)
synStore(obj, forceVersion = FALSE, versionLabel = "2")
File(path, parentId = project$properties$id)

# 3.0
synGet(entity, file_options = FileOptions(download_file = FALSE))

Some arguments moved rather than just changed case. Options that 2.x passed to synStore() — forceVersion, versionLabel — are fields on the entity itself in 3.0 (force_version, version_label), set at construction or with synSetProperties(). synStore() itself takes only the entity, an optional parent, and the per-type option objects (StoreFileOptions(), StoreContainerOptions(), StoreTableOptions(), …); there is no force_version argument on it.

4. Mutation goes through synSetProperties(), then an explicit synStore()

Directly assigning into $properties no longer works. Properties are set with synSetProperties() — which validates the field names against the object’s dataclass fields — and piped into synStore():

# 2.x
entity$properties$name <- "new name"
entity <- synStore(entity)

# 3.0
entity <- synGet(synapse_id) |>
  synSetProperties(name = "new name") |>
  synStore()

Table columns are the one exception — those are still mutated in place on the $columns list before synStore():

table$columns[["Expression"]]$name <- "Expression2"
table$columns[["Expression"]]$column_type <- "INTEGER"
table |> synStore()

The column verbs synAddColumn(), synDeleteColumn(), and synReorderColumn() work the same way: they change the table object in place and return nothing, so they are separate statements rather than links in a pipe into synStore():

table |> synAddColumn(Column(name = "Expression", column_type = "STRING"))
table |> synStore()

Renamed or restructured

• synBuildTable() → Table(...) |> synStore() |> synStoreRows(values = ..., schema_storage_strategy = "INFER_FROM_DATA"). The table has to exist before rows can be stored into it, so the synStore() step is not optional.
• synTableQuery() → synQuery()
• synMove() → synSetProperties(parent_id = ...) |> synStore()
• synGetChildren() → synSyncFromSynapse(recursive = FALSE, download_file = FALSE) and then the container’s $files/$folders, or synWalk() to traverse a whole tree
• synGetAnnotations() / synSetAnnotations() → the annotations field: read entity$annotations, write synSetProperties(annotations = list(...)) |> synStore()
• synGetProvenance() / synSetProvenance() / synDeleteProvenance() / synUpdateActivity() → the activity field (an Activity() object) set via synSetProperties(), and synDisassociateActivityFromEntity(Activity, parent = entity) to remove it
• synCreateColumn() / synCreateColumns() / synGetColumn() / synGetColumns() / synGetTableColumns() → the Column() constructor and the table’s own $columns list
• synCreateSnapshotVersion() → synSnapshot()
• synRestGET() / synRestPOST() / synRestPUT() / synRestDELETE(), and the 2.x synRestGetAsync() family → synRestGet(), synRestPost(), synRestPut(), synRestDelete()
• synCreateTeam() → Team(name = "...") |> synCreate(); synGetTeam() → Team |> synGetFromId(id = id) or Team |> synGetFromName(name = name); synDeleteTeam() → synDelete(team)
• synSendMembershipInvitation() → synInviteToTeam(); synGetTeamOpenInvitations() → synGetOpenInvitations(); synGetMembershipStatus() → synGetUserMembershipStatus()
• synGetUserProfile() → UserProfile |> synGetFromId(user_id = user_id) or UserProfile |> synGetFromUsername(username = username)
• Wikis: synGetWiki() → WikiPage(owner_id = ..., id = ...) |> synGet(); storing a wiki page → WikiPage(owner_id = ..., title = ..., markdown = ...) |> synStore(); synGetWikiHeaders() → as.list(WikiHeader() |> synGet(owner_id = ...)); synGetWikiAttachments() → synGetAttachmentHandles(), or synGetAttachment() to fetch one attachment. See Wikis.
• Evaluations: synGetEvaluation() → Evaluation(id = ...) |> synGet(); synGetEvaluationByName() → Evaluation(name = ...) |> synGet(); synGetEvaluationByContentSource() → synGetEvaluationsByProject(project_id = ...). See Evaluation.
• Submissions: synSubmit() → Submission(entity_id = ..., evaluation_id = ...) |> synStore(); synGetSubmission() → Submission(id = ...) |> synGet(); synGetSubmissionStatus() → SubmissionStatus(id = ...) |> synGet(), then synStore() to update it; synGetSubmissions() → Submission() |> synGetEvaluationSubmissions(evaluation_id = ...); synGetSubmissionBundles() → SubmissionBundle() |> synGetEvaluationSubmissionBundles(evaluation_id = ...). See Submission.
• Storage locations: synCreateS3StorageLocation() / synCreateStorageLocationSetting() → StorageLocation(...) |> synStore(); synGetMyStorageLocationSetting() → StorageLocation(storage_location_id = ...) |> synGet(); synSetStorageLocation(), synGetProjectSetting(), and synGetStsStorageToken() keep their names but are now verbs piped from a Folder or Project (folder |> synSetStorageLocation(storage_location_id = ...)).
• Download lists: synGetDownloadList() → synDownloadListFiles(); synGetDownloadListManifest() → synDownloadListManifest(); synRemoveFromDownloadList() → synDownloadListRemove(); synClearDownloadList() → synDownloadListClear(). synDownloadListAdd() is new.

Note the calling convention in the Team and UserProfile entries. synGetFromId(), synGetFromName(), synGetFromUsername(), and synDisassociateActivityFromEntity() wrap Python classmethods, so their first argument is the constructor (Team, UserProfile, Activity) — that is what selects the implementation — rather than an instance of it. An empty instance works as the marker too (Team() |> synGetFromId(id = id)), which is the style the reference pages use.

Not currently exposed in 3.0

These 2.x functions have no model-layer equivalent yet. Until they get one, call the REST API directly with synRestGet()/synRestPost()/synRestPut()/synRestDelete(), or keep that step of the pipeline in the Python client:

• File handles: synCreateExternalS3FileHandle(), synUploadFileHandle().
• Other: synDownloadTableColumns(), synGetConfigFile(), synInvalidateAPIKey().

Richer access control

synDeletePermissions() and synListAcl() are new. Both work over a single entity or an entire container hierarchy at once, so an audit or cleanup that used to mean writing your own recursive walk over 2.x’s synGetChildren() — and getting the edge cases (nested folders, inherited vs. local ACLs) right yourself — is now one call. dry_run lets you preview exactly what a recursive permissions change will touch before anything is deleted, which matters once you’re operating on an entire project tree instead of a single entity:

# Preview, then perform, a recursive ACL cleardown of a folder and its children
Folder(id = "syn123") |> synDeletePermissions(recursive = TRUE, include_container_content = TRUE, dry_run = TRUE)
Folder(id = "syn123") |> synDeletePermissions(recursive = TRUE, include_container_content = TRUE)

# List every ACL in a hierarchy, optionally as an ASCII tree
Folder(id = "syn123") |> synListAcl(recursive = TRUE, log_tree = TRUE)

One semantic change on an existing function: synGetPermissions(instance) now always returns your own effective permissions — the old principalId argument is gone. To check another user or team’s permissions, use synGetAcl(instance, principal_id = ...) instead, which still supports it:

# 2.x -- check someone else's permissions
synGetPermissions(entity, principalId = "273948")

# 3.0 -- synGetPermissions() is caller-only; use synGetAcl() for another principal
synGet(synapse_id) |> synGetAcl(principal_id = 273948L)

Container traversal and sync

synapser never exposed synapseutils’ copy, syncFromSynapse, or walk utilities — getting this functionality previously meant dropping out of R into a Python script, or reimplementing the recursion (and its failure handling) by hand with repeated synGetChildren()/synGet() calls. In 3.0 they’re methods on any container object, so a bulk copy, a full local mirror of a project, or a metadata-only inventory of an entity tree is a single pipeline that stays in R:

# Recursively copy a folder, and everything in it, to a new parent
Folder(id = "syn123") |> synCopy(parent_id = "syn456")

# Recursively download a folder tree, populating $files/$folders/$tables/...
folder <- Folder(id = "syn123") |> synSyncFromSynapse(path = "~/local-copy")

# Traverse a hierarchy without downloading anything
for (entry in as.list(folder |> synWalk())) {
  dirpath <- entry[[1]]; dirs <- entry[[2]]; nondirs <- entry[[3]]
  cat(dirpath[[1]], "\n")
}

synWalk() returns a GeneratorWrapper — the same lazy-iterator object 2.x returned from synGetChildren(), which no longer exists. Call as.list() on it to materialize every result into a plain list, or nextElem() to pull results one at a time; you can’t loop over it directly the way you can a list. For the narrower job synGetChildren() used to do — listing one container’s immediate children without downloading them — use synSyncFromSynapse(recursive = FALSE, download_file = FALSE) and read the resulting $files/$folders.

JSON Schema binding and validation

Also new: entities can be bound to a JSON Schema and validated against it directly from R. This lets you enforce metadata/annotation standards on Files, Folders, and Tables as part of an R pipeline — catching entities with missing or malformed annotations programmatically instead of relying on manual review or the web UI — and derive annotation values automatically from the schema rather than entering them by hand:

folder <- Folder(id = "syn123")
folder |> synBindSchema(json_schema_uri = "myOrg-mySchema-0.0.1")
folder |> synValidateSchema()
folder |> synUnbindSchema()

synBindSchema() returns the binding record rather than the entity, so bind the schema as its own statement and keep piping the entity itself.

This applies to Files, Folders, Tables, Projects, and other container/entity types. Creating the organization and schema themselves uses the new Organization/JSONSchema constructors — see ?Folder_synBindSchema for a full example. The rest of the family: synGetSchema() and synGetSchemaDerivedKeys() on any bindable entity, plus synGetSchemaValidationStatistics() and synGetInvalidValidation() on containers (Folder, Project).