Systems and records
Dataset artifact path portability: a path convention and replay check
By SourceX Editorial · Updated
10 sections
Short answer
Write every artifact reference as a relative path from the package root, with forward slashes, portable characters, no leading slash, drive letter or parent-directory step, and names that stay unique when case is ignored. Then prove it with a replay check: extract the package safely into a new location, resolve every reference, including those inside records, confirm each stays inside the root, and rerun the loader to match the supplier's counts and checksums.
Agent run
Dataset artifact path
Key takeaways
- Absolute paths break a dataset because they describe the supplier's disk, not the package; the same is true of drive letters, home directories and links to internal storage.
- The hardest references to find are inside the records, such as image paths in JSONL rows or file paths in agent tool outputs, not in the manifest.
- Packaging standards agree on the core rule: Data Package, Croissant and BagIt all resolve local files relative to the package or container root.
- Windows and POSIX filename rules add constraints that only show up when a package crosses systems: reserved names, reserved characters, case collisions and path length.
- A replay check relocates the package, resolves every reference and reruns the loader, so a pass means the package works somewhere the supplier has never been.
- A path that is content, such as a file-system path a model must learn to produce, is data and should be marked as such rather than rewritten.
How do you prevent absolute file paths from breaking a delivered dataset?
Ban them at the source and test for them at the door. The supplier writes every reference to a file in the package as a relative path from the package root, using a fixed set of rules, and ships a check that enforces those rules. The buyer runs the same check after moving the package to a new location and, ideally, a different operating system. If every reference resolves and the loader reproduces the supplier's counts and checksums, the paths are portable.
Absolute paths fail because they encode where the exporter happened to work: a home directory, a mounted drive, a network share, a bucket the buyer cannot reach. They often go unnoticed because the supplier's own validation runs on the same machine, where every one of them resolves. The first person to see the failure is the buyer's engineer, typically after integration has started.
This guide covers only the reference layer: how a path to an artifact is written and how to prove it resolves. Byte integrity, field meaning and acceptance terms are separate checks covered by the pages linked below.
Where do absolute paths hide in a dataset package?
Mostly outside the manifest. Packaging tools usually write the manifest correctly, so the absolute paths that survive are in places nobody lints. Search all of these before calling a package clean.
A quick first pass is to search every text file in the package for strings that start with a slash, a drive letter followed by a colon, two backslashes, a tilde or a file URL scheme. The hits are not all errors, but each one is a reference someone must classify as content, a declared remote location or a defect.
- Record fields that point to artifacts, such as image_path, audio_file or attachment columns in CSV, JSONL and Parquet files.
- Agent trajectories and tool logs, where a tool call or its output names the file it read or wrote on the collection machine.
- Configuration and loader files, such as YAML split definitions, dataset scripts and notebook cells that set a data directory.
- Symbolic links in the package tree, which can point at an absolute location or outside the root.
- Archive member names inside zip or tar files, which can carry absolute names or parent-directory steps.
- URLs that point to the supplier's internal storage or a signed link that will expire.
What do packaging standards already say about paths?
They agree on the core rule: local files are named relative to the package, never by absolute location. The Data Package standard's security guidance says local file references follow POSIX naming conventions and must be relative to the package descriptor, and that absolute paths are disallowed because they could be used to exfiltrate data and would rarely be useful, since you cannot know the layout of the user's computer.
Croissant applies the same idea to archives. When a FileObject declares the archive or file set it is contained in, its contentUrl is evaluated as a relative path within that container, and FileSet include and exclude glob patterns are evaluated from the root of the contained contents.
BagIt, published as RFC 8493, is the most explicit. Each manifest line names a file by its path relative to the bag's base directory, the slash is mandatory as the separator, only line feed, carriage return and the percent sign are percent-encoded, and a payload manifest must not reference files outside the payload directory. Any of these three standards is a reasonable model. The convention below adopts their shared rule and adds the cross-platform constraints that they leave to implementers.
The portable path convention
Adopt these rules for every artifact reference in the package, whether it appears in a manifest, a record field or a config file. The character and naming rules come from the POSIX definition of portable filenames and Microsoft's Windows naming guidance; together they keep names valid on both families of systems.
| Rule | Passes | Rejected | Why |
|---|---|---|---|
| Relative to the package root | media/t0007/step03.png | /Users/ana/export/media/t0007/step03.png | Absolute paths describe the exporter's disk |
| Forward slash as the only separator | logs/t0007.jsonl | logs\t0007.jsonl | BagIt mandates slash; backslash is outside the POSIX portable filename set |
| No drive letters, UNC prefixes, home shortcuts or file URLs | docs/readme.txt | C:/data/readme.txt or ~/data/readme.txt | Each binds the path to one machine or user |
| No dot or dot-dot components | tables/orders.parquet | ../shared/orders.parquet | Parent steps can escape the root on extraction |
| Portable characters only | invoice_2026-03_a.pdf | invoice: march?.pdf | POSIX portable names use letters, digits, period, underscore and hyphen; Windows reserves colon and question mark |
| No Windows reserved names, even with an extension | null_record.json | NUL.json or con.txt | Windows treats these as device names |
| No trailing space or period; no leading hyphen | notes.txt | notes. or -notes.txt | Windows shells do not support the first; POSIX advises against the second |
| Unique when case is ignored | img/A1.png and img/A2.png | img/a1.png and img/A1.png | Windows guidance says not to assume case sensitivity, so one file overwrites the other |
| Short total length | Paths kept well under 260 characters from the root | Deeply nested IDs repeated in every directory name | Legacy Windows APIs stop at MAX_PATH unless long paths are enabled |
| Regular files only | A copied file | A symbolic link to /mnt/raw | Links can point outside the root or to nothing |
The replay check
Run it in a fresh directory with a different name and depth from the supplier's, with no network route to the supplier. Extract archives with a safe method: Python's zipfile documentation warns never to extract archives from untrusted sources without inspection, because members with absolute names or dot-dot components can create files outside the target, and its tarfile module offers extraction filters that refuse absolute members and links that would land outside the destination, with the data filter as the default since Python 3.14.
| Step | Method | Pass condition | Typical failure |
|---|---|---|---|
| 1. Safe extraction | Extract with a filter that refuses absolute and escaping members | No member refused | An archive member named ../../config |
| 2. Inventory the tree | List every file and link under the root | No symbolic links; every file listed in the manifest | A link to the exporter's raw folder |
| 3. Lint every name | Apply the convention table to every file name and directory name | Zero violations | A reserved name or a colon in a file name |
| 4. Harvest embedded references | Scan manifests, records, configs and logs for strings that look like paths or file URLs | Every reference is relative or a declared remote URL | A /home/ prefix in an agent tool output |
| 5. Resolve and contain | Join each reference to the root, normalize it and confirm it stays under the root | Every reference exists and stays inside | A reference that resolves only on the supplier's disk |
| 6. Case collision scan | Lowercase every path and look for duplicates | No duplicates | Two screenshots differing only in letter case |
| 7. Relocate and reload | Move the package to a second location, ideally on another operating system, and run the shipped loader | Loader runs with no path edits | A hard-coded data directory in the loader |
| 8. Compare outputs | Match record counts and file checksums with the supplier's report | Exact match | Rows silently dropped because their files did not resolve |
Can a buyer rebuild the package without the supplier's internal systems?
Only if every reference the replay check harvests resolves inside the package or to a declared, reachable remote location. Steps 4 and 5 answer this directly: any path or URL that resolves only on the supplier's network is a dependency the buyer does not have.
The failure is usually quiet. Loaders often skip rows whose files are missing and report a smaller dataset rather than an error. That is why step 8 compares counts with the supplier's report rather than accepting a successful run as proof.
Run the replay on a second operating system at least once per package version, not once per project. A package that passed on Linux last quarter can fail on a Windows workstation this quarter because a new batch introduced a reserved name or a case collision. Keeping the replay output with each version also gives both parties a dated record of what resolved, which is easier to discuss than a description of a broken import.
Worked example (illustrative): an agent trajectory package with screenshots
This example is hypothetical and its counts are invented for illustration. A supplier delivers 120 agent tasks, each with a JSONL trajectory and screenshots, for a total of 2,400 artifact references across manifests and records.
The manifest is clean, but step 4 finds 310 references inside trajectory records that begin with the exporter's home directory, because the recording tool logged full paths. Step 6 finds 14 screenshot pairs whose names differ only in case, which collapse to 7 files when the package is extracted on a case-insensitive file system. Step 3 flags 2 files named aux.json, a reserved name on Windows. On the relocated copy, the loader drops about 13 percent of steps without raising an error.
The supplier rewrites the embedded paths relative to the package root, renames the colliding screenshots with a step index, renames the reserved files and reissues the package with a new version. The replay then passes on both operating systems with exact count and checksum matches.
The exception in this package: some tasks ask the agent to type a file path into a form, so a path string is the correct answer, not a reference. Those fields are marked as content in the data dictionary and excluded from steps 4 and 5, so the check does not rewrite the very thing the model must learn.
When is a non-relative reference acceptable?
When it is declared and testable. Some artifacts are too large to ship inside the package, or must stay in the supplier's storage. In that case the reference should be a stable remote URL in a field reserved for URLs, with a checksum and an access method the buyer has been given, never a mix of local and remote forms. The Data Package standard draws the same line: a resource's path array must be either all relative paths or all URLs, not both.
Paths that are themselves data, such as file names a model must generate or parse, are acceptable in any form as long as they are flagged as content. The convention applies to references the loader follows, not to strings the model reads.
Which results need a security or integration engineer before acceptance?
Bring in a security engineer when step 1 refuses any archive member, when links point outside the root, or when embedded references include system locations rather than data files. Those are signs the package was assembled carelessly or could write outside its directory, and the package should be inspected before anyone extracts it with default tools.
Bring in the integration owner when the loader itself needs path edits to run, when remote references require credentials nobody has issued, or when fixing paths would change record identifiers that other systems already use. Those decisions affect more than one delivery.
Writing the path convention into a data request
The simplest way to get portable paths is to ask for them before the data is assembled. Put the convention table and the replay steps in the request, and ask for the supplier's own replay output with each delivery.
Buyers who ask SourceX for data get datasets sourced to order from U.S. businesses rather than pulled from stock, and the request form's format section is the natural home for the path convention, next to scope, volume, language, timing and licensing needs. Multi-terabyte packages often remain in the seller's storage or ship on encrypted drives, the two cases where declared remote references and a relocation replay matter most.
Frequently asked questions
Why do absolute paths work in testing but fail on delivery?
Because the supplier's tests run on the machine where those paths exist. Once the package is copied anywhere else, the same strings point to locations that are missing. A replay check in a fresh directory exposes the problem before integration.
Should dataset paths use forward slashes or backslashes?
Forward slashes. BagIt makes the slash mandatory in manifests and the Data Package standard follows POSIX naming, where the slash is the separator. A loader on Windows can convert at load time, which is safer than shipping two conventions.
Are case-sensitive file names a problem in datasets?
Yes, when two names differ only by case. Microsoft's naming guidance says not to assume case sensitivity, so on a case-insensitive file system one file overwrites the other during extraction. Require names that stay unique when lowercased.
Can a dataset reference files by URL instead of relative path?
Yes, if the URLs are stable, reachable by the buyer, declared as remote and paired with checksums. Do not mix URLs and local paths for the same resource. Expiring signed links and internal storage addresses are not portable references.
Is it safe to extract a delivered dataset archive with default tools?
Not without inspection. Python's documentation warns that archive members with absolute names or dot-dot components can write outside the target directory. Use an extraction method that refuses such members, and treat any refusal as a reason to inspect the package.
Sources
- Data Package local file references follow POSIX naming conventions, are relative to the descriptor, and absolute paths are disallowed. Source
- A Data Package resource path array must be all relative paths or all URLs. Source
- Croissant evaluates contentUrl as a relative path within its container and evaluates FileSet globs from the container root. Source
- BagIt manifest paths are relative to the base directory, use slash separators, percent-encode only LF, CR and percent, and stay inside the payload directory. Source
- POSIX.1-2024 requires portable filenames to use only the portable filename character set. Source
- Windows naming rules reserve certain characters and device names, advise against assuming case sensitivity or ending names with a space or period, and describe the legacy 260-character MAX_PATH. Source
- Python warns that archive members with absolute names or dot-dot components can create files outside the extraction path. Source
- Python's tarfile extraction filters refuse absolute or escaping members and links; the data filter is the default since Python 3.14. Source
Tell us what data you need
Share scope, volume, format, timing and licensing needs. Datasets are sourced on request.