DEV Community

Fernando Paladini
Fernando Paladini

Posted on

Edit Lattes XML Safely with Node.js and lattes-toolkit

#typescript #node #tutorial #xml

Brazilian researchers often need to update the same fields in a Currículo Lattes XML export more than once. The web form is useful for review, but it is not a convenient batch-editing interface. Copying XML by hand is risky: one malformed change can make a previously valid export harder to inspect or restore.

This tutorial shows a local workflow with lattes-toolkit, an MIT-licensed Node.js and TypeScript toolkit. You will parse an exported file, read a field, change it from the command line, inspect the automatic backup, and understand how to constrain scripted or AI-assisted edits.

The important boundary is simple: the toolkit prepares a file on your computer. You still export the curriculum and use the Platform Lattes UI to import, review, and save it yourself.

TL;DR

Install @paladini/lattes-toolkit, keep the exported XML in a working directory, then use parse, get, and set. Existing files are backed up under .lattes-backup/ before they are overwritten. For batch changes, use the TypeScript API with an explicit allowlist and parse the result again before importing it.

Prerequisites

You need:

  • Node.js 18 or newer;
  • an XML export that you are allowed to edit;
  • a terminal and a separate backup location for important files;
  • enough time to review the generated XML in the Platform Lattes import screen.

The package is @paladini/lattes-toolkit at version 1.2.0 in the current repository metadata. It is independent and is not affiliated with CNPq. The core workflow is local and offline. The optional Extrator client is a separate integration and is not needed here.

Install the CLI

Create a small project directory and install the package locally:

mkdir lattes-edit
cd lattes-edit
npm init -y
npm install @paladini/lattes-toolkit@1.2.0
Enter fullscreen mode Exit fullscreen mode

Copy your exported file into this directory as curriculo.xml. Treat it as personal data. Do not commit the file, upload it to an issue, or use a real person's curriculum as a test fixture.

You can also use the package without a global install. The command name is lattes-toolkit:

npx lattes-toolkit --help
Enter fullscreen mode Exit fullscreen mode

Inspect before changing anything

Start with a summary. This lets you confirm that the file is an XML export or a supported ZIP containing one:

npx lattes-toolkit parse curriculo.xml
Enter fullscreen mode Exit fullscreen mode

To read one known field, use dot notation. The project maps common curriculum fields to a typed Curriculum object:

npx lattes-toolkit get curriculo.xml identification.summary
Enter fullscreen mode Exit fullscreen mode

List entries can use bracket notation. For example, this reads the title of the first mapped journal article when that field exists in the export:

npx lattes-toolkit get curriculo.xml bibliographicProduction.journalArticles[0].title
Enter fullscreen mode Exit fullscreen mode

If a field is not mapped yet, do not assume that the command can edit it safely. The project preserves unmapped XML nodes during its round-trip, but its typed editing surface is intentionally best effort rather than a complete, immutable schema for every Lattes variation.

Make one controlled edit

The simplest update changes a field and writes the serialized XML back to the same path:

npx lattes-toolkit set curriculo.xml identification.summary "Researcher and software engineer focused on reproducible data workflows."
Enter fullscreen mode Exit fullscreen mode

When the destination already exists, the toolkit creates a snapshot before overwriting it. The default location is .lattes-backup/ beside the edited file. Inspect the available snapshots with:

npx lattes-toolkit backup list
Enter fullscreen mode Exit fullscreen mode

If the result does not look right, restore the latest snapshot instead of guessing which XML lines to repair:

npx lattes-toolkit restore --last
Enter fullscreen mode Exit fullscreen mode

The restore operation uses the original path recorded in the backup manifest. Keep the backup directory local and treat its manifests as trusted local state.

Verify the result before import

Read the changed value again and produce a fresh summary:

npx lattes-toolkit get curriculo.xml identification.summary
npx lattes-toolkit parse curriculo.xml
Enter fullscreen mode Exit fullscreen mode

Then open the XML in the Platform Lattes import flow. Review the proposed changes there and save only after checking the visible result. This last step is deliberately manual. The toolkit does not log in, bypass a CAPTCHA, scrape public curricula, or click the platform's upload controls.

Use an allowlist for repeatable edits

For several changes, the TypeScript API gives you a reviewable patch list. An allowlist makes the intended edit surface explicit:

import { readFileSync } from "node:fs";
import {
  applyCurriculumPatches,
  readCurriculum,
  writeCurriculum,
} from "@paladini/lattes-toolkit";

const path = "./curriculo.xml";
const curriculum = await readCurriculum(readFileSync(path));

applyCurriculumPatches(
  curriculum,
  [
    {
      path: "identification.summary",
      value: "Researcher and software engineer focused on reproducible data workflows.",
    },
  ],
  { allowlist: ["identification.summary"] },
);

await writeCurriculum(curriculum, path);
Enter fullscreen mode Exit fullscreen mode

A useful review pattern is read, patch, write, read again. Keep the patch list in source control without the XML itself, and have a human review the exact paths and values before running it. The library's backup behavior still applies when writeCurriculum overwrites an existing file.

Why this workflow is safer

The command line and API expose a small sequence instead of asking a script to manipulate raw XML strings. Parsing creates a typed representation, path-based updates make the target visible, serialization handles the round-trip, and the backup gives you a recovery point.

The toolkit also keeps XML nodes that its typed model does not cover in an unmapped area and writes them back. That reduces the risk of losing unrelated content, but it is not a guarantee that every future platform change will be represented perfectly. Re-parse the output and review it in the official import UI.

Failure modes and limitations

The most common failure is editing the wrong path. Check a field with get before writing it, and use a small synthetic fixture when developing a script.

Other boundaries matter:

  • The core library does not download curricula from the public web.
  • It does not automate login or upload to Platform Lattes.
  • It does not provide full XSD validation for the entire, changing format.
  • Curriculum files contain personal information, so real exports should not be placed in public issues or test fixtures.
  • XML and ZIP inputs can be large or malicious. Do not process untrusted archives casually, and keep restore manifests local.
  • The optional SOAP client sends requests only to an endpoint configured by you. It is outside this local-only tutorial.

These are useful constraints, not missing promises. They make it clear which part is deterministic local file editing and which part still requires the platform and its rules.

FAQ

Does this publish the curriculum automatically?

No. It reads and writes local XML. Exporting, importing, reviewing, and saving in Platform Lattes remain manual.

Can I use an XML inside a ZIP?

The CLI documents XML and ZIP input for parsing. Confirm the output on a copy first, especially when the archive contains more than one candidate file.

What happens to fields the toolkit does not know?

The project documents round-trip preservation through unmapped, but its typed model is not a complete schema validator. Verify the generated file before importing it.

Should I use the optional Extrator client?

Only when your institution provides an appropriate endpoint and you understand its terms and data handling. It is not required for editing an XML export locally.

Takeaway

Treat a Lattes XML export like a data file, not like a text snippet. Parse it, make a narrow path-based change, preserve a backup, parse the result again, and review the final file in the official import flow. That workflow is small enough to automate locally while keeping personal data and platform actions under your control.

What field would you automate first, and what verification would you require before importing the generated XML?

AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The project behavior, commands, version, limitations, and security boundaries were checked against the repository, its documentation, the published package metadata, and a local CLI smoke test. Please verify the current release before applying the workflow to personal data.

Top comments (0)