Skip to content

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

This page covers enterprise dataset JSONL task package: a portable layout with validators.Illustrative

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.

Which files belong in the package, and what does one line mean in each?
PathRoleOne line equalsKeys every line must carry
manifest.jsonIndex of the packageNot JSONL: one JSON object for the whole packagepackage_id, schema_version, content_version, created_at, files
schema/*.schema.jsonMachine-readable contractsNot JSONL: one JSON Schema per record type$schema, $id, required, properties
data/tasks.jsonlThe unit a buyer samples, splits and gradesOne business task, such as one ticket, work order or invoice exceptiontask_id, task_type, source_system, opened_at, split
data/events.jsonlWhat happened, in orderOne step: a message, a field change, a status change, a tool actionevent_id, task_id, seq, ts, actor_role, event_type
data/artifacts.jsonlIndex of binary or long filesOne file in artifacts/ and what it is forartifact_id, task_id, path, media_type, sha256, bytes, role
data/outcomes.jsonlWhat was observed after the taskOne outcome label for one taskoutcome_id, task_id, label, label_source, observed_at
artifacts/Attachments, exports, screenshotsFiles referenced by artifacts.jsonl onlyRelative paths, no parent directories
DATASHEET.md and validate.pyHuman documentation and runnable checksFree text and a scriptMotivation, 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.

What fields does a task line need, and what does each one promise?
FieldTypeMeaningRule the validator enforces
task_idstringStable package-wide identifier, never the source system's raw ticket numberRequired; unique across tasks.jsonl; pattern like T-000123; unchanged across content versions
task_typestring enumThe business process, for example refund_request or po_mismatchRequired; value in the enum declared in task.schema.json
source_systemstringThe system family the record came from, for example helpdesk or ERPRequired; free of customer names and tenant URLs
opened_at and closed_atstring, RFC 3339 date-timeWhen the task started and when work on it stoppedopened_at required; closed_at not earlier than opened_at; UTC offset present
instructionstringThe request as the requester wrote it, after de-identificationRequired for tasks used as prompts; no outcome text
initial_state_refstring or nullArtifact ID of a snapshot of relevant state when the task openedIf present, must resolve to an artifact with role initial_state
splitstring enumtrain, validation or testRequired; every event, artifact and outcome inherits the task's split
provenanceobjectrecord_origin, export_date, deid_method, rights_basis_refRequired; 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.

Which checks should a buyer be able to run without the supplier's systems?
CheckWhat it testsHow to test itTypical failure
V01 encodingEvery JSONL file is UTF-8 with no byte order markDecode bytes strictly as UTF-8; reject a leading EF BB BFExport from a spreadsheet tool saved with a BOM or Windows-1252
V02 line shapeEvery line is exactly one JSON object; no blank linesParse line by line; reject empty lines and non-object valuesPretty-printed JSON spread across lines
V03 duplicate keysNo object repeats a keyParse with a hook that fails on repeated namesTwo status keys, where parsers silently keep different ones
V04 schemaEach line validates against its record schemaJSON Schema 2020-12 validation with additionalProperties falseMissing split, misspelled task_type, outcome text on a task line
V05 unique IDsIDs are unique within each fileCount IDs; any count above one failsRe-export appended the same tasks twice
V06 referential integrityEvery child task_id and artifact_id resolvesSet membership against tasks.jsonl and artifacts.jsonlEvents for tasks that were filtered out during de-identification
V07 path safetyArtifact paths are relative and stay inside the packageReject leading slash, any .. segment and hidden foldersAn absolute path from the exporter's laptop
V08 hashesEach file's SHA-256 matches the manifest and the artifact indexRecompute digests and compareAn attachment re-saved after redaction without updating its hash
V09 order and timeseq is continuous and timestamps never go backwards per taskGroup events by task_id, sort by seq, compare tsTime zone dropped on half the rows
V10 leakage and splitsNo outcome data on task lines; a task's children share its splitSchema plus a join on task_id across filesA 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.

See if your company qualifies