DSpace migration and upgrade: move to DSpace 10 without breaking a single citation

What migrates, what gets rebuilt and what is lost

A repository is not a single database. It has four layers with different formats and risks, and the most common planning mistake is quoting "repository migration" with only the metadata in mind (budget figures are in our guide to DSpace implementation cost):

• Descriptive metadata: the description of each item, usually in qualified Dublin Core. It travels as XML or CSV and is mapped field by field.
• Bitstreams: the files themselves, such as the thesis PDF, the dataset or the audio, which DSpace keeps in the assetstore, outside the database. They are heavy and move separately.
• Community and collection structure: the tree of faculties, programs and document types. It is rebuilt in the destination before anything is loaded, because every item needs a collection to land in.
• Persistent identifiers: the handles or DOIs already published. This is the only layer that, if broken, also breaks everything outside the repository.

Some things are rebuilt rather than migrated: deposit and review workflows, groups and permissions, submission forms, embargoes configured as access policies, and the visual customization. One layer rarely migrates in full: the usage statistics history. DSpace stores statistics in a Solr core, not in the database, and they only move when the source is also DSpace. Coming from another platform, the normal approach is to start the counters at zero and keep the old reports as a separate archive.

Persistent identifiers: the part you cannot break

DSpace assigns each item a handle, an identifier of the form hdl.handle.net/prefix/suffix. The prefix is issued to the institution through the Handle.Net Registry run by CNRI, for an annual fee, and the promise of the system is that the URL keeps resolving even when the domain, the server or the platform changes. So if the previous repository already published identifiers that appear in theses, articles and CVs, you have to take them with you. There are two paths, and the choice belongs at the start of the project, not the end:

• Transfer the prefix, so that resolution of the existing prefix points to the new server. It is the clean option, but it is all or nothing: the whole prefix moves to the new repository and the old platform stops resolving any remaining handles.
• Keep the old identifier as metadata and publish redirects from the old URLs. It is the way out when the prefix belongs to a consortium or to a provider that will not release it.

If the source used DataCite DOIs, the operation is equivalent: update the target URL registered for each DOI. It is mechanical, bulk work, but it is not optional. When BiblioLabTech migrates a repository, identifier verification is a named task in the schedule, done after cutover with a manual sample and an automated check of the full list. Redirects from the old direct item URLs help too, since those are linked from many places.

Import formats: what DSpace accepts

Two warnings apply to almost every project. ZIP uploads through the interface are limited to 2 GB by default, so a repository with thousands of PDFs is loaded in batches or from the command line. And a CSV edited in Excel often arrives with broken accented characters, because Excel handles UTF-8 poorly and tends to insert an invisible byte-order mark: better to know that before loading 12,000 records than after.

DSpace migration and upgrade scenarios by difficulty

The last scenario is common and the most underestimated, because it looks the simplest. It is not: the difficulty moves from the code to the institution, which must decide what gets published, obtain author permissions, define licenses, build the community tree and, above all, make sure the repository is not born empty. Formally active, practically empty repositories are common; that is exactly the problem we solved at Universidad Americana in Paraguay, where AI metadata extraction built into the deposit workflow meant that filling the repository no longer depended on transcribing every title page by hand.

The seven-step DSpace migration methodology

This is the sequence we follow, and the order matters. Skipping the mirror environment is the shortcut that costs the most.

1. Inventory the source: items, bitstreams and gigabytes; metadata schema and exact system version; database access or only an export; which identifiers were published and who controls the prefix.
2. Map the metadata field by field to the DSpace registry, deciding what goes to standard Dublin Core and what goes to the local schema, where custom fields must live so that no future upgrade touches them.
3. Design communities and collections in the destination, with item types, submission forms and access policies already defined.
4. Test load in a mirror environment identical to production, with a pilot batch of 100 to 500 representative items: a thesis under embargo, an article with several authors, an item with five files, one with special characters in the title and one from each problematic collection.
5. Validate with the library team on the real repository, not on a spreadsheet: search by author, filter by facets, open the PDF, confirm the embargo blocks the download.
6. Full load and freeze: set the moment after which nothing is deposited in the old system, load everything, reconcile counts (items per collection, bitstreams per item, total size) and migrate the delta captured between the dump and the freeze.
7. Cutover and identifier verification: point the domain, open the repository and verify that handles and DOIs resolve, with a manual sample and an automated check of the full list.

On timelines: in our projects, a migration with a standard-format export and a library team taking part in validation takes four to ten weeks of effective work for a repository of a few thousand items. Source metadata quality, gigabytes of files and pending institutional decisions move that range far more than the item count.

Upgrading from DSpace 5, 6 or 7 to DSpace 10

An upgrade resembles a platform migration more than people expect. Start with the support picture: DSpace 10.0 was released on May 28, 2026 and DSpace 10.1 on September 14, 2026. Under the DSpace software support policy, the 10.0 release moved support to the 8.x, 9.x and 10.x lines, and DSpace 7.6.7, published the same day, is the final 7.x release. The 5.x and 6.x lines received their last updates in July 2022, and DSpace 11.0 is scheduled for May or June 2027. The official documentation covers upgrading from any past release, so a DSpace 5 or 6 site can go straight to DSpace 10, but the effort depends on where you start.

The interface jump

Since DSpace 7, XMLUI and JSPUI are gone and the frontend is an independent Angular application. Theme customizations built on XMLUI do not migrate; budget their rebuild as development, not configuration.

Entities, relationships and a new choice in DSpace 10

DSpace 7 introduced the configurable entities and relationships model, which stores links in a dedicated table. No script converts old items into entities in bulk, so the recommendation, from the community and from us, is to decouple the two projects: first the technical upgrade with entities disabled, then adoption of the model. DSpace 10 adds a decision: each site chooses between traditional relationships with virtual metadata and the new DSpace-CRIS-style relationships managed through the authority framework, using the item.enable-virtual-metadata setting, which defaults to the traditional model that suits upgrading sites. One rule prevents future pain: never edit the dc or dcterms schemas; custom fields belong in the local schema.

Statistics and the target version

Statistics and authority cores are exported and imported explicitly, while search and OAI are reindexed. If old statistics were sharded by year, expect extra work, because modern versions do not handle that sharding. Then choose the target carefully: DSpace 10.0 pushed 7.x out of support, and landing on the oldest supported line buys the least time. Upgrading to a branch close to its end of life means paying twice.

What usually goes wrong

• Broken handles. The repository opens, everything looks fine and published citations stop resolving: the only error on this list that harms people outside the library.
• Incomplete backup before cutover: the database without the assetstore, or the reverse. Back up the database first, then the files, because DSpace treats the database as the authoritative record.
• Broken accents from badly declared encoding, usually a CSV that went through Excel, and items without bitstreams, where the metadata arrived and the file did not. Reconciling counts catches both; eyeballing does not.
• Embargoes that did not carry over, publishing in the open a thesis that should have stayed restricted. It is the failure with legal consequences, which is why the pilot batch always includes an embargoed item.
• Collections invented during the load instead of designed beforehand. Reorganizing a tree with 10,000 items inside costs far more than a meeting.
• Not freezing the old system, and ending up with two diverging repositories for weeks.

After the cutover

A migrated repository is not finished on the day it opens. Three fronts remain. The first is visibility: configuring OAI-PMH contexts so that aggregators such as OpenAIRE can harvest it, which means meeting their metadata guidelines, not just switching on the OAI server. The second is infrastructure: where the instance lives, under which backup policy and who applies the patches, as covered in our DSpace hosting guide. The third is strategic: if the university needs to answer "what did researcher X produce?" or "what came out of funded project Y?", a document repository is not enough and the conversation moves toward DSpace-CRIS. Raise it before migrating, because deciding in time changes how collections and authorship metadata are modeled.

At the Escuela Colombiana de Ingeniería Julio Garavito, the DSpace repository works alongside the Koha catalog and the rest of the library platform because it was planned as a system, not as a one-off purchase. If you need to migrate or upgrade a repository, BiblioLabTech prepares a proposal that includes inventory, mapping, a test environment and identifier verification, priced on your collection's real figures, through our DSpace implementation service.