Data export and import format

Protocol version:zhixu.data-package/v1. Update date: 2026-10-17. Personal and organizational exports use the same public format; this article explains the archive's structure, validation rules, and recoverability boundaries. The interface base path is /question-bank/data-transfers。

Export or import from application

1. In the personal space, open "Export and Migrate" on the question bank page; the organization leader or administrator opens "Export Organization Data" in "Services and Packages".
2. Select "Export Data" to retain the list, all data fragments, and original files; switch to "Import Data" when migrating, first upload the file and complete the pre-check, and then check the target space and conversion list.
3. For unfinished tasks, the original task number can be read in "Continue Task". When the result is uncertain, use the original task and try again to avoid repeated creation.

Moving in will create new information, and historical test scores and personal study facts will only be archived. The target space, permissions, and capacity must still meet the constraints below. Ordinary users can complete the above operations first; subsequent chapters are for readers who need to check protocols, fields or develop docking.

Identity and Permissions

Use real Accounts JWT, scoped PAT or MCP OAuth Authorization: Bearer …. Local employees of the organization cannot call this interface when logging in. The task is bound to the actual user, authentication type, credential/connection/authorization ID; changing the credentials will not obtain the original task. The service is used in creation, status query, same key readback, file download/Range, upload, confirmation, retry, each worker transaction re-verifies the current identity, scope, organization member/business read or write permissions, organization authorization and frozen question bank collection. The package does not contain tokens, passwords or storage addresses.

Personal export includes a personal question bank that can be read by oneself, with optional originals and one's own practice/wrong question files. Organization export requires the current owner/admin: members, positions and exams require the entire organization all_banks Authorized and explicit is not allowed bankIds. All members/exams of the organization cannot be obtained implicitly through the question bank, and individual employee exercises cannot be exported. Organizational retention limits also apply to generated download packages; downloads do not extend retention.

Export scopes:banks:read;Original added sources:read;Personal learning increased practice:read; Increase of members/positions organizations:read;Examination added organizations:read、exams:read、results:read. Move-in needs banks:write、imports:write, including release version increase banks:publish, including increase in members/positions organizations:manage. The move-in only accepts all_banks target authorization. The target organization must be writable, have no question bank, no positions, and only have existing real owners; individuals can move in and create a new personal question bank.

Routing and DTO

The response is direct JSON DTO, no nesting success/data. time as UTC ISO string,byteSize is a decimal string. Failure follows existing exception format {code,message,...}。

type ExportInput = {
  organizationId?: string | null;
  bankIds?: string[];
  components?: ('banks'|'sources'|'members'|'positions'|'exams'|'learning')[];
  idempotencyKey: string; // 8..100 chars
}; // default components=['banks','sources']; banks is mandatory

type ImportInput = {organizationId?:string|null;manifest:Manifest;idempotencyKey:string};
type ConfirmInput = {planHash:string;confirmationToken:string;idempotencyKey:string};
type UploadDescriptor = {fileId:string;method:'PUT';url:string;
  headers:{'Content-Type':'application/octet-stream'};byteSize:string;sha256:string};
type TransferJob = {id:string;kind:'export'|'import';status:string;
  schemaVersion:'zhixu.data-package/v1';organizationId:string|null;
  progress:{stage:string;processed:number;total:number|null};snapshotAt:string|null;
  expiresAt:string;manifestHash:string|null;preview:ImportPreview|null;
  report:VerificationReport|null;error:{code:string;message:string;retryable:boolean}|null;
  createdAt:string;updatedAt:string};
type ImportPreview = {planHash:string;confirmationToken:string;expiresAt:string;
  target:{organizationId:string|null;fingerprint:string};counts:Record<string,number>;
  restorableSections:string[];archivedSections:string[];
  transformations:{code:string;count:number;message:string}[];
  blockers:{code:string;message:string}[]};
type VerificationReport = {verifiedAt:string;counts:Record<string,number>;
  restored:Record<string,number>;archived:Record<string,number>;
  transformations:{code:string;count:number;message:string}[];
  differences:{section:string;sourceRef:string;field:string}[];passed:boolean};

organizationId Default organization by current credentials/identity when omitted, explicit null means individual. Bao Neiyuan scope.organizationId Only source metadata is used, and the migration target is not selected.members Automatically bring in the position to close the position reference. The export paging default is 20 and the maximum is 100. Create will be rejected if there are already active tasks of the same type as the subject; retry/verify is serialized according to its own job and does not commit to the global concurrency quota across jobs.

Read back the original task with the same idempotent key and the same input for the first time, change the body and return TRANSFER_IDEMPOTENCY_CONFLICT. Confirm that the token is valid for 10 minutes, bind the original body, manifest, target fingerprint and current plan; confirm that the replay is relatively complete and the original body (including token) is relatively complete. The same confirmation that has been accepted will not be re-executed because the original 10 minutes have passed, and the task TTL and current permissions must still be valid.

File and Recovery Protocol

Export queued → snapshotting → exporting → ready, the failure is failed. GET files only ready and not expired returns manifest/files, including delivery-only id:'manifest' JSON descriptor. The customer downloads the manifest and all JSONL.gz/original files, verifies them by SHA256 based on actual bytes one by one and retains the files.

Move in uploading → validating → awaiting_confirmation → queued/importing → completed. POST imports are used after each file is uploaded using the returned authenticated PUT route, the declared byte size/SHA is from the immutable manifest, and the server core actually streams. POST preview and poll GET before confirmation; the server verifies all JSONL and the original real bytes/summary, schema, reference, original option sequence/answer/version summary, capacity, and target conflicts again before returning the executable preview. Do not write business lines in pre-check.

The new confirmation requires a strict seven-day task TTL of more than 24 hours + 120 seconds remaining; if insufficient, the transaction will be persisted and returned after expired TRANSFER_CONFIRMATION_TIME_WINDOW, release the creation quota, and the target remains unchanged. Please create the task with a new key. First confirmation of the launch of a new 24-hour absolute execution period. The business lines, ID map, and cursor in each transaction of up to 250 lines are submitted together; generation/token/lease/expiry is checked at entry and before submission. Task crashes can be restored along the same job/map bounded, the target question bank/organization remains restored, and the complete content, references and files will be re-read and verified independently before being opened.

TRANSFER_VERIFICATION_FAILED The confirmed isolation task of ZX00007 can expose the new retry key within the original period/TTL and when the current permission is still valid: keep the original IDs/map, repair the pointer and the original time metadata and then compare them; if they still do not match, keep the isolation. Targets that have been opened cannot be restored from this archive. Other retryable failures are subject to error.retryable and actual field judgment. Expired or expired semi-finished products will remain isolated and cleaned. There is no promise of permanent recovery, nor will business data be automatically deleted.

POST verify will queue an independent new verification and return verifying and report=null, poll GET import to obtain the results of this round. The verify-only target that has been completed will not be re-sealed and the open status will not be changed; the last passed cannot be used as a real-time verification.

All file I/O includes start request to completion, up to 120 seconds; object delete up to 10 seconds and retains the retry ledger. Download returns Content-Length, Content-Disposition, ETag(SHA), Accept-Ranges, private/no-store. Range supports single range and suffix;bytes=0-99 Truncate 8-byte files to 0-7, starting with>=size, multiple ranges/unsafe integers/invalid format returns 416 and Content-Range: bytes */size. Each resume download reauthenticates and verifies the retention period.

v1 public package format

type Manifest = {schemaVersion:'zhixu.data-package/v1';packageId:string;capturedAt:string;
  scope:{organizationId:string|null;bankIds:string[]};sections:Record<string,number>;
  restorableSections:string[];archivedSections:string[];
  omitted:{component:string;reason:string}[];files:FileDescriptor[]};
type FileDescriptor = {id:string;section:string;kind:'jsonl-gzip'|'source';filename:string;
  mimeType:string;byteSize:string;sha256:string;rowCount:number};
type JsonlRow = {section:string;sourceRef:string;record:Record<string,unknown>};

All original IDs are UUID, passed sourceRef Reference; migrate new ID persistent mapping, reference/hash is recalculated synchronously. The filename does not contain a path; the URL is not fetched from the package, and the internal objectKey is not accepted. JSONL gzip A complete object per line, UTF8 (illegal encoding rejected), must have a newline at the end. Fields must be complete and only from the following whitelist; nullable fields are represented by null and dates must be canonical UTC ISO (milliseconds). The JSON content retains the original value, integer/boolean by field type, and the original byte size as a decimal string.

The id of each original descriptor is equal to sources.sourceRef, section=sources, rowCount=0, and the real bytes/SHA/mimeType corresponds to the sources row; delivery file name source-<sourceUUID>-<safe original basename> Unique and ≤255 UTF16 units, the complete originalFilename is retained in JSONL. The manifest's own descriptor does not write back to the manifest to avoid self-referential hashes.

Business can be restored in the first 12 fields (banks to members, in order of field dependency). Organizational exams, final exam answers, and personal exercises/mistakes only save the migration history files, and formal exams/exercise answers are not constructed or written. The fact of participation in exams that are in progress/not started/cancelled is explicitly excluded by omitted; employee personal learning is not taken into account when exported by the organization. The currently active authorization question bank closure is selected/frozen within the same REPEATABLE READ snapshot, and subsequent downloads will also freeze the current authorization of IDs.

The source owner/admin does not map the account or authorization, and the ordinary imported member is role=member; the original active/pending → pending needs to be reactivated, the suspended/left status is maintained, and the original identity/role/time is saved in lineage. Only when the source owner and the real target owner have the same ID OWNER_RECORD_ARCHIVED_COLLISION: The complete source row is only archived, and the work number is not changed, members are not created, owner is not bound, and new capacity is not accounted for. Other job ID conflicts will be blocked. report.restored.members+report.archived.members equals the number of sources. Position name/status and member location references are preserved by mapping.

The lineage and archive payload are persisted after confirmation; the archive is not in the general member/exam list, and there is no independently exposed archive-read API. Customers should retain the complete download package. At the end of seven days, only the temporary export/unconfirmed-import staging payload/delivery object will be cleared; the real restored original and confirmed lineage will be retained. The cleanup of the business retention period is governed by the lifecycle independent contract; this time there is no entry for deleting the production business.

Download field type catalog

record-fields.json: 19 partitions, 202 public fields(34,120 bytes, SHA256 1b16d336c24e28add9073c85e9010c192f7ce9b7f241970442e5404b0f46ad36). It contains only field definitions, types, limits, and descriptions, not table names, internal entities, account numbers, customer profiles, or credentials. This file is an additional format reference that is not included in the files in the sample manifest and does not need to be uploaded as a move-in piece.

• fields[section] is the complete required field name of the partition record; fields not listed are not accepted. Nullable fields cannot be omitted and should be written explicitly null。
• fieldTypes[section][field] Provide type(string/integer/boolean/json) vs. nullable;Add according to field needs maxLength、unsigned、format, date precision/canonical。
• date field format=date-time requires canonical UTC ISO string with milliseconds, e.g. 2026-10-14T00:00:00.000Z. Original byteSize of format=unsigned-decimal is an unsigned decimal string and cannot be converted to a floating point number.
• restorableSections、archivedSections and limits Description v1 classification and transfer caps. It is a public field reference,Not a complete JSON Schema;Semantic validations such as enumerations, question/answers, references, sequences, content summaries, target capacities and permissions are still determined by normal preflight of the actual API.

Quota and synthesis example

Total number of lines: 1,000,000, question bank 10,000, files 10,000, total delivered bytes 5GiB; manifest 8MiB; each line 1MiB; maximum 1,000 lines per gzip fragment, compression/expansion ≤16MiB respectively; single original ≤20MiB (along with the upload limit of existing originals). These are public upper limits and do not mean that full capacity performance acceptance has been done. Export SQL batch 500, import transactions 250, seven-day task TTL, 24-hour execution period, 120-second CAS lease. The source file can be held for up to 5 minutes each time and does not exceed the absolute execution period. After copying, the artifact is independent and the organizational retention period will not be extended.

The public synthesis package contains 21rows/11files: 1 question with fixed C-A-B order, correct identity of A, two versions of parsing, working and two legal published versions, pure synthesized original JSON. There is no customer data, account binding or official answers. The manifest and each file summary are generated based on actual bytes; the title, release version and reference map are verified according to the same rules. Static ZIP is only convenient for downloading. Customers use manifest+files after decompression. The API does not parse ZIP upload.

The sample content is fully synthesized for format checking and migration experience in the authorized test space. The actual migration must still be uploaded, pre-checked, confirmed and checked according to the following steps; the source identifier in the example will not be used to overwrite the existing question bank.

Download and use the pure synthesis data package

Download synthesis example ZIP (10,075 bytes). ZIP is only used for centralized downloads. The current page and API areDirect upload of ZIP is not accepted. Decompress JSONL.gz first without recompressing it; then select manifest.json and all 11 data fragments/originals.

SHA256 of ZIP:

698301b6fba92b6c55ed5118b4af2e2faaf26f90c85c31536f80a5ee813f0b18

You can also save the files in the following table one by one to the same directory. Browsers may add suffixes to downloads with duplicate names; importing matches files based on actual length and SHA256, without relying on local renaming or File.type.

1. Log in to the program and enter the clearly selected personal testing space; or use an authorized target organization that meets the empty organization and service conditions. The scope in the source manifest is just a description of the source and does not select the target for you.
2. Open "Export and Migrate", select the decompressed manifest.json, and then select all data fragments and original JSON. The page must check the original byte summary one by one and upload it. You cannot only upload the ZIP or decompressed JSONL text.
3. Start pre-check and the waiting state enters awaiting_confirmation. Check current targets, conversion/archive lists and blockers; no business data is written in preflight. Explicit confirmation within ten minutes after passing.
4. Wait for the background processing to be completed and read the verification report of this round. Check restored, archived, differences and passed. The previous passed cannot replace the result of this round.

SHA256 calculation of both original and gzip filesactual file bytes. If the JSONL content or compression parameters change, the file SHA may change even if the question text appears to be the same; you cannot just modify the SHA in the manifest to bypass content, answer identity, version, and reference verification.

Linux/macOS can execute on each file shasum -a 256 文件名;Windows PowerShell executable Get-FileHash -Algorithm SHA256 文件名, and then compare it with the above table and manifest. Question contentHash, answerKeyHash, and question bank contentDigest belong to content/version verification, not gzip file SHA, and cannot be interchanged.

Listing and JSONL raw line example

The following is the actual list in the download package; it does not include tokens, account bindings, storage addresses or customer information. Please use the full export or public example structure as a starting point when generating new source packages; support is determined by normal preflight, and unknown schemas, fields, states, or summaries are not silently accepted.

{
  "schemaVersion": "zhixu.data-package/v1",
  "packageId": "00000000-0000-4000-8000-000000000100",
  "capturedAt": "2026-10-14T00:00:00.000Z",
  "scope": {
    "organizationId": null,
    "bankIds": [
      "00000000-0000-4000-8000-000000000001"
    ]
  },
  "sections": {
    "banks": 1,
    "sources": 1,
    "questions": 1,
    "options": 3,
    "questionVersions": 2,
    "optionVersions": 6,
    "answerKeys": 2,
    "bankVersions": 2,
    "bankVersionItems": 2,
    "workingItems": 1
  },
  "restorableSections": [
    "banks",
    "sources",
    "questions",
    "options",
    "questionVersions",
    "optionVersions",
    "answerKeys",
    "bankVersions",
    "bankVersionItems",
    "workingItems"
  ],
  "archivedSections": [],
  "omitted": [
    {
      "component": "members,positions,exams,learning",
      "reason": "This synthetic personal package contains no identities or activity facts"
    }
  ],
  "files": [
    {
      "id": "part-000001",
      "section": "banks",
      "kind": "jsonl-gzip",
      "filename": "part-000001.jsonl.gz",
      "mimeType": "application/gzip",
      "byteSize": "299",
      "sha256": "3e1409ab04086aa02f36d79e6b6efd6537a30c1a339648b9ab30c669096f02b6",
      "rowCount": 1
    },
    {
      "id": "part-000002",
      "section": "sources",
      "kind": "jsonl-gzip",
      "filename": "part-000002.jsonl.gz",
      "mimeType": "application/gzip",
      "byteSize": "273",
      "sha256": "ee52dd03b464514524ccbed0fec8f969a79b67c74df7ec709dae4fddf14cba30",
      "rowCount": 1
    },
    {
      "id": "part-000003",
      "section": "questions",
      "kind": "jsonl-gzip",
      "filename": "part-000003.jsonl.gz",
      "mimeType": "application/gzip",
      "byteSize": "177",
      "sha256": "7b90ee68aaf8b515105f4020efe3ef8a5a10dd1e6fa446652e5fb45b4a3744a3",
      "rowCount": 1
    },
    {
      "id": "part-000004",
      "section": "options",
      "kind": "jsonl-gzip",
      "filename": "part-000004.jsonl.gz",
      "mimeType": "application/gzip",
      "byteSize": "162",
      "sha256": "a3c30a885c4438f6aaab75b9dcfc8cfda49f88792737cb39d51fc5aa3f14f625",
      "rowCount": 3
    },
    {
      "id": "part-000005",
      "section": "questionVersions",
      "kind": "jsonl-gzip",
      "filename": "part-000005.jsonl.gz",
      "mimeType": "application/gzip",
      "byteSize": "660",
      "sha256": "b03fe6dc8e1cdc25a79d374e02890dd27ca9b759e443db726fb0dc094b594d7f",
      "rowCount": 2
    },
    {
      "id": "part-000006",
      "section": "optionVersions",
      "kind": "jsonl-gzip",
      "filename": "part-000006.jsonl.gz",
      "mimeType": "application/gzip",
      "byteSize": "430",
      "sha256": "73ba1ce448477441896c5292f5dfe452a5e4287eeec13b929440690d63568c24",
      "rowCount": 6
    },
    {
      "id": "part-000007",
      "section": "answerKeys",
      "kind": "jsonl-gzip",
      "filename": "part-000007.jsonl.gz",
      "mimeType": "application/gzip",
      "byteSize": "178",
      "sha256": "4c51dc64684048eafbb5424253b5065b5430562c473d44f8720f83d819d80f58",
      "rowCount": 2
    },
    {
      "id": "part-000008",
      "section": "bankVersions",
      "kind": "jsonl-gzip",
      "filename": "part-000008.jsonl.gz",
      "mimeType": "application/gzip",
      "byteSize": "316",
      "sha256": "7c83407c6387735a6f90cb0a0aa97bd4ed94ae28b12a1d2366497f4da16f094a",
      "rowCount": 2
    },
    {
      "id": "part-000009",
      "section": "bankVersionItems",
      "kind": "jsonl-gzip",
      "filename": "part-000009.jsonl.gz",
      "mimeType": "application/gzip",
      "byteSize": "195",
      "sha256": "32a358a7a1bc8f6b80c540d3265e5238376ec20e3e323f5dc9af94f43a640a09",
      "rowCount": 2
    },
    {
      "id": "part-000010",
      "section": "workingItems",
      "kind": "jsonl-gzip",
      "filename": "part-000010.jsonl.gz",
      "mimeType": "application/gzip",
      "byteSize": "178",
      "sha256": "03124c4bbb7379f281228d94b1a8cfc5025481b9dcb3c13b3f7c5564fd34909e",
      "rowCount": 1
    },
    {
      "id": "00000000-0000-4000-8000-000000000003",
      "section": "sources",
      "kind": "source",
      "filename": "source-00000000-0000-4000-8000-000000000003-minimal-source.json",
      "mimeType": "application/json",
      "byteSize": "151",
      "sha256": "7570b1a38b91d6777f24ac2aa9de9b5ad4a1c2f56aa0c699d50a30899250389b",
      "rowCount": 0
    }
  ]
}

The following is the JSON object of the only line after decompression of the first gzip fragment (displayed with newlines for reading, the entire object in the original JSONL occupies one line, and the end of the file is LF):

{
  "section": "banks",
  "sourceRef": "00000000-0000-4000-8000-000000000001",
  "record": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "迁移格式合成示例",
    "description": "纯合成资料；固定选项顺序与两版解析",
    "status": "active",
    "usageMode": "practice_and_exam",
    "currentBankVersionId": "00000000-0000-4000-8000-000000000011",
    "workingRevision": 2,
    "createdAt": "2026-10-14T00:00:00.000Z",
    "updatedAt": "2026-10-14T00:00:00.000Z"
  }
}

section consistent with the descriptor of the fragment;sourceRef equal to the original primary key of record. The original primary key ofanswerKeys is questionVersionId, and the other partitions are id. Check-in generates new IDs for new resources and keeps package references, question/answer identities, and release versions closed. The option uses originalPosition to represent the original order; the release/working order uses position respectively, and does not reorder by display letters.

In the example, a question has two versions of the question content and two published versions. The original order of the three options is C, A, B, and the correct identity is A. The complete map has been generated according to the same question strategy and reference verification, and does not mean that any employee has completed the exam or answered the questions.