Migrating from v3 to v4
Guide for upgrading your integration from PaperStack v3 schema to v4.
Migrating from v3 to v4
The PaperStack v4 schema (released May 2026) introduces a cleaner, more consistent response format. This guide covers the changes and migration steps.
What Changed
Top-Level Fields
| v3 Field | v4 Field | Notes |
|---|---|---|
schema_version | schema | Now a simple string ("v4") |
subjects[] (array of strings) | subjects[] | Unchanged |
total_questions | total | Renamed for brevity |
time_allowed_minutes | duration | Renamed |
correct_mark | marksCorrect | Renamed |
negative_mark | marksIncorrect | Renamed |
unanswered_mark | marksUnanswered | Renamed |
sections | sections | Now uses total/required/mandatory (not min/max) |
answer_key_status | answerKeyFound | Boolean instead of string |
data_hash | checksum | Renamed |
source | provenance | Now an object with author, repo, license, pipeline version |
questions[] | questions[] | See question object changes below |
| — | passages[] | New — comprehension passages |
Question Object Changes
| v3 Field | v4 Field | Notes |
|---|---|---|
id | id | Unchanged format (neet-2024-05may-s1-ph-001) |
q_no | number | Renamed |
subject | subject | Unchanged |
topic | topic | Unchanged |
section | section | Unchanged |
q_type | type | Now lowercase: "mcq", "msq", "nat", "assertion-reason" |
question_text | text | Renamed |
options | options | Unchanged |
answer | answer | Unchanged |
answer_rationale | — | Removed (was rarely populated) |
marks | marks | Unchanged |
negative_marks | negativeMarks | Renamed |
passage_ref | passageId | Renamed |
diagram_ref | diagrams[] | Now an array of { file, label, caption } objects |
difficulty | difficulty | Unchanged (null in current data) |
tags | tags | Unchanged |
| — | numberLabel | New — official question number label if different from number |
| — | answers | New — array for multi-select questions |
| — | answerPrecision | New — required decimal precision for NAT questions |
| — | revision | New — data revision counter |
Section Object Changes
v3 format:
{
"a": { "min": 0, "max": 50, "required": true },
"b": { "min": 0, "max": 15, "required": false }
}v4 format:
{
"a": { "label": "Section A", "total": 100, "required": 100, "mandatory": true },
"b": { "label": "Section B", "total": 100, "required": 100, "mandatory": true }
}Migration Steps
1. Update JSON Paths
Search for these field accesses in your code and update:
- data.schema_version
+ data.schema
- data.total_questions
+ data.total
- data.time_allowed_minutes
+ data.duration
- data.correct_mark
+ data.marksCorrect
- data.negative_mark
+ data.marksIncorrect
- question.q_no
+ question.number
- question.q_type
+ question.type
- question.question_text
+ question.text
- question.negative_marks
+ question.negativeMarks2. Handle New Fields
Add handling for these v4-only fields if your code processes them:
// New: passages array (may be empty)
if (data.passages) {
data.passages.forEach(passage => { /* ... */ });
}
// New: numberLabel (may be null)
const displayNumber = question.numberLabel ?? question.number;
// New: multiple answers for MSQ
if (question.type === 'msq' && question.answers) {
// question.answers is an array
}
// New: precision for numerical answers
if (question.type === 'nat' && question.answerPrecision) {
// Round your answer to question.answerPrecision decimal places
}3. Update Checksum Verification
- const hash = data.data_hash;
+ const hash = data.checksum;4. Replace Section Logic
- const isRequired = section.required;
+ const isMandatory = section.mandatory;Timeline
| Date | Event |
|---|---|
| May 2026 | v4 schema released as default |
| Jun 2026 | v3 endpoints deprecated |
| Jul 2026 | v3 endpoints removed |
If you need extended time to migrate, contact support for a custom deprecation schedule.
Need Help?
Was this page helpful?