JSON format

Complete specification for Rebuttr's JSON data format used in imports, exports, and API interactions.

Overview

Rebuttr uses JSON for data interchange, allowing you to:

Paper Schema

The root object for a complete paper export:

paper.json
{ "id": "paper-uuid-1234", "title": "My Research Paper Title", "journal": "Nature Communications", "authors": ["Author One", "Author Two"], "status": "inprogress", "currentRound": 1, "tags": ["priority", "grant-123"], "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-20T14:22:00Z", "reviews": [ ... ], "metadata": { ... } }

Paper Fields

Field Type Required Description
id string Auto Unique identifier (UUID)
title string Yes Paper title
journal string No Target journal name
authors array No List of author names
status string No One of: draft, inprogress, completed, submitted
currentRound number No Current revision round (default: 1)
tags array No List of tag strings
createdAt string Auto ISO 8601 timestamp
updatedAt string Auto ISO 8601 timestamp
reviews array No Array of Review objects
metadata object No Custom metadata

Review Schema

Each review represents one reviewer's comments:

Review Object
{ "id": "review-uuid-5678", "reviewer": "Reviewer 1", "round": 1, "receivedAt": "2024-01-15T10:30:00Z", "overallSentiment": "constructive", "comments": [ ... ] }

Review Fields

Field Type Required Description
id string Auto Unique identifier
reviewer string Yes Reviewer identifier (e.g., "Reviewer 1", "Editor")
round number No Revision round number
receivedAt string No When review was received
overallSentiment string No positive, constructive, critical, mixed
comments array Yes Array of Comment objects

Comment Schema

Individual reviewer comments with responses:

Comment Object
{ "id": "comment-uuid-9012", "text": "The methodology section lacks detail about sample selection criteria.", "category": "major", "lineReference": "Lines 45-67", "section": "Methods", "status": "completed", "response": { "text": "We thank the reviewer for this observation...", "createdAt": "2024-01-18T09:15:00Z", "aiGenerated": true, "edited": true }, "solutions": [ { "text": "Add detailed sample selection criteria to Methods", "completed": true } ] }

Comment Fields

Field Type Required Description
id string Auto Unique identifier
text string Yes The reviewer's comment text
category string No major, minor, technical, editorial
lineReference string No Reference to manuscript lines
section string No Manuscript section referenced
status string No pending, inprogress, completed
response object No Response object (see below)
solutions array No Array of Solution objects

Response Schema

Field Type Description
text string The response text
createdAt string ISO 8601 timestamp
aiGenerated boolean Whether AI generated the initial draft
edited boolean Whether user edited the response

Import Format

For importing reviews, a simplified format is supported:

import-reviews.json
{ "reviewer": "Reviewer 1", "comments": [ { "text": "The sample size is too small.", "category": "major" }, { "text": "Figure 2 needs better labels.", "category": "minor", "lineReference": "Figure 2" } ] }
Minimal Import

Only reviewer and comments[].text are required for import. All other fields are optional and will be auto-populated or left empty.

Bulk Import

Import multiple reviewers at once:

bulk-import.json
{ "reviews": [ { "reviewer": "Reviewer 1", "comments": [ ... ] }, { "reviewer": "Reviewer 2", "comments": [ ... ] }, { "reviewer": "Editor", "comments": [ ... ] } ] }

Validation

Rebuttr validates JSON on import. Common validation errors:

Error Cause Solution
Missing required field Required field not provided Add the missing field
Invalid category Category not in allowed list Use: major, minor, technical, editorial
Invalid status Status not in allowed list Use: pending, inprogress, completed
Invalid date format Date not ISO 8601 Use format: 2024-01-15T10:30:00Z
JSON Validation

Use rebuttr validate --file data.json to check your JSON before importing.

Next Steps