Systems and records
Enterprise dataset JSONL task package: a portable layout with validators
By SourceX Editorial · Updated
10 sections
Short answer
Structure a portable JSONL task package as a folder: one tasks.jsonl line per business task, sibling events, artifacts and outcomes files keyed by stable task IDs, attachments stored as files, JSON Schemas for each record type, and a manifest with SHA-256 hashes and line counts. A buyer then runs twelve checks, from UTF-8 and schema validation to referential integrity and split leakage, without touching the supplier's systems.
Checklist
Enterprise dataset JSONL
Key takeaways
- Split a task dataset into tasks, events, artifacts and outcomes files joined by stable, opaque task IDs.
- Keep outcome fields off the task line so the prompt side cannot read how the task ended.
- Store attachments as files indexed with relative paths and SHA-256, never as base64 inside a line.
- A buyer should validate the whole package with the folder alone: encoding, schema, IDs, joins, paths, hashes, order and splits.
- Version schema and content separately, and never edit a released version in place.
What is a JSONL task package, and why is one file not enough?
A JSONL task package is a folder in which each business task, such as one support ticket and its fix, is a line in a tasks file, and everything that happened to that task lives in sibling JSONL files and attachments keyed by stable IDs. A manifest lists every file with its hash and count, and a small validator proves the parts still fit together.
One big JSONL file looks simpler, but it fails as soon as a task has attachments, a long event history and an outcome observed weeks later. Nesting all of that into one line makes lines huge, hides binary files inside base64 strings, and forces a buyer to parse everything to answer a simple question like how many tasks have an outcome. Splitting by entity keeps each line small, keeps binaries as files, and lets a buyer join only what a given experiment needs.
The format rules underneath are short. JSON Lines requires UTF-8 without a byte order mark, one valid JSON value per line, no blank lines, and a newline terminator. Everything else in this guide is a convention layered on top: how files are named, which keys each line carries, and which checks must pass before a delivery is accepted.
Which files belong in the package, and what does one line mean in each?
Ship four JSONL files, one folder of artifacts, a manifest, the JSON Schemas and a datasheet. The table is the layout this guide uses; the names are illustrative, but the rule that every file has one declared role and one declared line meaning is the part to keep.
| Path | Role | One line equals | Keys every line must carry |
|---|---|---|---|
| manifest.json | Index of the package | Not JSONL: one JSON object for the whole package | package_id, schema_version, content_version, created_at, files |
| schema/*.schema.json | Machine-readable contracts | Not JSONL: one JSON Schema per record type | $schema, $id, required, properties |
| data/tasks.jsonl | The unit a buyer samples, splits and grades | One business task, such as one ticket, work order or invoice exception | task_id, task_type, source_system, opened_at, split |
| data/events.jsonl | What happened, in order | One step: a message, a field change, a status change, a tool action | event_id, task_id, seq, ts, actor_role, event_type |
| data/artifacts.jsonl | Index of binary or long files | One file in artifacts/ and what it is for | artifact_id, task_id, path, media_type, sha256, bytes, role |
| data/outcomes.jsonl | What was observed after the task | One outcome label for one task | outcome_id, task_id, label, label_source, observed_at |
| artifacts/ | Attachments, exports, screenshots | Files referenced by artifacts.jsonl only | Relative paths, no parent directories |
| DATASHEET.md and validate.py | Human documentation and runnable checks | Free text and a script | Motivation, collection, de-identification, known gaps; exit code 0 on pass |
What fields does a task line need, and what does each one promise?
A task line needs only the fields that let a buyer identify, filter, split and join it; the history belongs in events and the result belongs in outcomes. Keeping outcome fields off the task line is deliberate, because a model trained to act on the task should not be able to read how the task ended.
Each field below carries a rule the validator enforces. Types follow JSON Schema, and the required list in the task schema names every field marked required, which JSON Schema 2020-12 treats as properties that must be present in the object.
| Field | Type | Meaning | Rule the validator enforces |
|---|---|---|---|
| task_id | string | Stable package-wide identifier, never the source system's raw ticket number | Required; unique across tasks.jsonl; pattern like T-000123; unchanged across content versions |
| task_type | string enum | The business process, for example refund_request or po_mismatch | Required; value in the enum declared in task.schema.json |
| source_system | string | The system family the record came from, for example helpdesk or ERP | Required; free of customer names and tenant URLs |
| opened_at and closed_at | string, RFC 3339 date-time | When the task started and when work on it stopped | opened_at required; closed_at not earlier than opened_at; UTC offset present |
| instruction | string | The request as the requester wrote it, after de-identification | Required for tasks used as prompts; no outcome text |
| initial_state_ref | string or null | Artifact ID of a snapshot of relevant state when the task opened | If present, must resolve to an artifact with role initial_state |
| split | string enum | train, validation or test | Required; every event, artifact and outcome inherits the task's split |
| provenance | object | record_origin, export_date, deid_method, rights_basis_ref | Required; rights_basis_ref points to a contract clause ID, not to the contract text |
How do events, artifacts and outcomes stay linked to the right task?
Every child line carries the parent task_id, and the validator rejects any child whose task_id does not exist in tasks.jsonl. This is the same idea as a foreign key: the Data Package Table Schema expresses it with foreignKeys, and Croissant links RecordSets with a references property whose values are taken from the target field. A JSONL package can declare the same joins in its manifest so that either metadata format can be generated later without guessing.
IDs need three properties to survive a hand-off. They are unique within their file, they are stable across content versions so that a corrected record keeps its ID, and they are opaque, so that a ticket number, email address or account code never doubles as a key.
- events.task_id must match a task_id; within one task, seq runs 1, 2, 3 with no gaps and ts never decreases as seq increases.
- artifacts.task_id must match a task_id; artifacts.path must exist on disk and its SHA-256 must equal the sha256 field.
- events may list artifact_ids, and each one must exist in artifacts.jsonl with the same task_id.
- outcomes.task_id must match a task_id; observed_at must be on or after the task's closed_at.
- No task may have two outcome lines with the same label_source unless the schema declares multiple raters.
Which checks should a buyer be able to run without the supplier's systems?
A buyer should be able to rebuild and validate the package with nothing but the folder, Python or a similar runtime, and a JSON Schema validator. If any check needs a call back to the supplier's helpdesk, ERP or database, the package is not portable yet.
At a glance
Which checks should a buyer be able to run without the supplier's systems
The ten checks in the table, plus the two manifest checks described in the versions section, make up the twelve-check validator this guide proposes. Each check prints the file, line number and rule ID that failed, counting lines from 1 as the JSON Lines convention recommends, so a supplier can fix the exact record.
| Check | What it tests | How to test it | Typical failure |
|---|---|---|---|
| V01 encoding | Every JSONL file is UTF-8 with no byte order mark | Decode bytes strictly as UTF-8; reject a leading EF BB BF | Export from a spreadsheet tool saved with a BOM or Windows-1252 |
| V02 line shape | Every line is exactly one JSON object; no blank lines | Parse line by line; reject empty lines and non-object values | Pretty-printed JSON spread across lines |
| V03 duplicate keys | No object repeats a key | Parse with a hook that fails on repeated names | Two status keys, where parsers silently keep different ones |
| V04 schema | Each line validates against its record schema | JSON Schema 2020-12 validation with additionalProperties false | Missing split, misspelled task_type, outcome text on a task line |
| V05 unique IDs | IDs are unique within each file | Count IDs; any count above one fails | Re-export appended the same tasks twice |
| V06 referential integrity | Every child task_id and artifact_id resolves | Set membership against tasks.jsonl and artifacts.jsonl | Events for tasks that were filtered out during de-identification |
| V07 path safety | Artifact paths are relative and stay inside the package | Reject leading slash, any .. segment and hidden folders | An absolute path from the exporter's laptop |
| V08 hashes | Each file's SHA-256 matches the manifest and the artifact index | Recompute digests and compare | An attachment re-saved after redaction without updating its hash |
| V09 order and time | seq is continuous and timestamps never go backwards per task | Group events by task_id, sort by seq, compare ts | Time zone dropped on half the rows |
| V10 leakage and splits | No outcome data on task lines; a task's children share its split | Schema plus a join on task_id across files | A test-split task with an event copied into training |
Illustrative worked record: one support-to-fix task, valid and broken
The lines below are invented to show structure. They are not customer records and do not describe any real dataset. They show one helpdesk task that ended in a product fix, written as it would appear in each file, followed by a broken variant and the checks that catch it.
Valid lines, one per file:
- tasks.jsonl: {"task_id": "T-000123", "task_type": "defect_report", "source_system": "helpdesk", "opened_at": "2025-03-04T14:02:00Z", "closed_at": "2025-03-11T09:40:00Z", "instruction": "Export to CSV drops rows with accented names.", "initial_state_ref": null, "split": "train", "provenance": {"record_origin": "helpdesk_export", "export_date": "2026-09-30", "deid_method": "entity_replacement_v2", "rights_basis_ref": "AGR-7.2"}}
- events.jsonl: {"event_id": "E-000123-03", "task_id": "T-000123", "seq": 3, "ts": "2025-03-05T10:15:00Z", "actor_role": "tier2_agent", "event_type": "status_change", "from": "open", "to": "escalated_engineering", "artifact_ids": ["A-000123-01"]}
- artifacts.jsonl: {"artifact_id": "A-000123-01", "task_id": "T-000123", "path": "artifacts/T-000123/export_sample_redacted.csv", "media_type": "text/csv", "sha256": "(64 hex characters)", "bytes": 18422, "role": "evidence"}
- outcomes.jsonl: {"outcome_id": "O-000123", "task_id": "T-000123", "label": "fixed_in_release", "label_source": "linked_issue_closed", "observed_at": "2025-03-18T00:00:00Z", "observation_window_days": 30}
- Broken variant: the artifact path becomes ../exports/export_sample.csv, the event's seq jumps from 3 to 5, and the task line gains "resolution": "fixed". V07 rejects the path, V09 reports the missing seq 4, and V04 rejects the extra property, which is also a leak of the outcome into the prompt side.
How do versions and hashes let a buyer rebuild the same package later?
Version the schema and the content separately, and hash every file. A buyer who trained on content version 1.2.0 must be able to prove, months later, which lines and attachments that was, and a supplier who corrects a redaction miss must be able to ship a fix without breaking the buyer's loaders.
Semantic Versioning fits the schema well: a new optional field is a MINOR change, a renamed or removed field is a MAJOR change, and a corrected description is a PATCH. Its rule that a released version must not be modified is the one that matters most for training data, because a silently edited file makes earlier experiments impossible to reproduce. Content gets its own version or a dated release tag, bumped whenever any line or file changes.
For hashes, use SHA-256, which FIPS 180-4 specifies for detecting whether a message has changed since its digest was produced. The Data Package standard defaults its hash field to MD5 but lets a package name another algorithm with a prefix such as sha256:, and Croissant uses a sha256 property on each file, so recording SHA-256 keeps both mappings straightforward. A hash catches corruption and silent edits; it does not prove who made the file, so a signed manifest or a trusted transfer channel is still needed when tampering is a concern.
- manifest.files[] carries path, role, bytes, sha256, record_count and the schema $id for JSONL files.
- record_count must equal the number of lines in the file; V11 compares them.
- schema_version must be valid Semantic Versioning, and V12 checks that each schema's $id includes it.
- A content_version change log lists added, removed and corrected task_ids, so a buyer can diff without reprocessing everything.
What should never be written into the JSONL lines?
Keep anything a buyer does not need to learn the task out of the lines: direct identifiers, credentials, tenant URLs and the contract itself. JSONL is plain text, so every line is easy to grep, copy and paste into a notebook, which is exactly why personal data and secrets in it travel further than intended.
At a glance
What should never be written into the JSONL lines
Four separate questions sit behind every line, and the package should not blur them. System access means someone could export the record. Privacy permission concerns the people named in it. Ownership asks who holds the underlying rights. Contractual licensing rights cover what the buyer may do with the delivered copy. De-identification addresses the second question only; it does not create a right to license, so the provenance object points to the clause that grants rights instead of asserting them.
- Replace names, emails, phone numbers and account numbers before export, and record the method in provenance.deid_method.
- Strip API keys, session tokens and internal hostnames from logs and event text; a regex pass plus manual sampling is a minimum.
- Store screenshots and documents as artifacts after redaction, never as base64 inside a line.
- Keep free-text fields, but log in the datasheet which fields were redacted and how often redaction changed the meaning of a record.
When does JSONL stop being the right container?
JSONL is the right container when records are nested, heterogeneous and read sequentially, which describes most task histories. It stops being the right choice when a buyer needs columnar scans over billions of rows, strict typed columns or random access to a single field, where Parquet or Arrow usually serve better.
The package design survives a format change because the semantics live in the schemas, the manifest and the IDs, not in the line format. A supplier can ship the same tasks, events, artifacts and outcomes as Parquet tables, describe them in a Croissant file or a Data Package descriptor, and keep the same validator rules. Datasheets for Datasets is a useful companion either way: its questions about motivation, composition, collection process and recommended uses become the DATASHEET.md that travels with the package.
Requesting task data delivered in this layout
If you are sourcing task histories from operating businesses, give suppliers this layout and the validator rules up front, and accept a delivery only when every check passes on your side. That way most cleanup happens before delivery, and acceptance becomes a run of validate.py.
There is no standing catalog to browse: SourceX sources each dataset from U.S. businesses once a buyer asks, and the request form's fields for scope, volume, language, format, timing and licensing needs are where this JSONL task layout can be named as the delivery format. Packages too large to transfer remain in the seller's storage or ship on encrypted drives; SourceX does not host them.
Frequently asked questions
Can a buyer validate and rebuild the package without the supplier's internal systems?
Yes, if the package is built as described here. Everything the validator needs is in the folder: JSONL files, schemas, a manifest with SHA-256 hashes and record counts, and the artifacts themselves. If any check needs a live connection to the source helpdesk or ERP, treat the delivery as incomplete.
Should a task package use one JSONL file or several?
Use one file per record type when tasks have histories, attachments or later outcomes. A single file works for flat prompt and response pairs, but nested histories make lines large and force every consumer to parse everything. Separate files joined by task_id keep each line small and each join explicit.
What makes a JSONL line invalid?
A line is invalid if it is not exactly one JSON value, if it is blank, or if the file is not UTF-8. A package adds its own rules on top, such as schema validation, unique IDs and no duplicate keys inside an object, which RFC 8259 warns lead to unpredictable behavior.
How should screenshots and attachments be stored in a JSONL dataset?
Store them as files under an artifacts folder and index each one in artifacts.jsonl with a relative path, media type, byte size, SHA-256 and role. Do not embed them as base64 inside a line. Redact them before hashing, because the hash should describe the file the buyer actually receives.
Do I need Croissant or a Data Package descriptor as well as a manifest?
Not to validate the package, but generating one helps buyers whose tooling reads those formats. Both can describe files with checksums and declare joins between record sets, so a well-formed manifest maps onto either one. Treat them as views of the same contract, generated from the manifest rather than maintained by hand.
Sources
- JSON Lines requires UTF-8 without a byte order mark, one valid JSON value per line (a blank line is not valid), and a newline line terminator; .jsonl is the conventional extension. Source
- RFC 8259 says names within a JSON object should be unique and that software receiving duplicate names behaves unpredictably. Source
- In JSON Schema 2020-12, the required keyword lists property names that must be present in an object instance. Source
- The Data Package standard gives each resource a unique name, a path, and an optional hash that defaults to MD5 and can name another algorithm with a prefix. Source
- The Data Package standard forbids absolute paths, parent-directory paths and hidden folders in resource paths so that a package only points inside its own directory. Source
- Croissant describes files as FileObject or FileSet with an optional sha256 checksum and links RecordSets with a references property that works like a foreign key. Source
- Semantic Versioning increments MAJOR for incompatible changes, MINOR for backward compatible additions and PATCH for backward compatible fixes, and a released version must not be modified. Source
- FIPS 180-4 specifies SHA-256 and states that digests are used to detect whether messages have changed since the digests were generated. Source
- Data Package Table Schema can declare a primaryKey and foreignKeys that link fields in one resource to fields in another. Source
- Datasheets for Datasets proposes that every dataset be accompanied by documentation of its motivation, composition, collection process and recommended uses. Source
Tell us what data you need
Share scope, volume, format, timing and licensing needs. Datasets are sourced on request.