This document provides a comprehensive overview of the GSTR-1 JSON data format, its architectural requirements, and the strict validation rules necessary for successful submission to the GSTN portal. The GSTN hasn't published an official JSON schema.. So this has been reverse engineered based on validity testing against the official GST website, APIs found online, and the documentation associated with the "GST Offline Tool".
GSTR-1 is a mandatory return for all GST-registered businesses in India, used to report details of all outward supplies (sales).
- Monthly: For businesses with an aggregate turnover exceeding ₹1.5 Crore.
- Quarterly (QRMP Scheme): For smaller businesses with turnover up to ₹5 Crore.
At a high level, only a few sections are required for every filing. All others depend on the nature of transactions in the tax period.
- Mandatory (Tables 1, 2, 12, 13): GSTIN details, Financial Period, HSN Summary, and Documents Issued. These are required for every filing.
- Conditional (Table 3): Turnover summary (
gt,cur_gt). Mandatory only for FY 2017-18; omit for others. - Conditional (Tables 4 - 11, 14, 15): Only required if there are relevant transactions (e.g., B2B sales, Exports, or Amendments).
The following table maps common JSON keys to the official GSTR-1 Table numbers:
| JSON Key | GST Table | Description | Required Status |
|---|---|---|---|
gstin, fp |
Tables 1 & 2 | Taxpayer Identification & Return Period. | MANDATORY |
gt |
Table 3 | Gross Turnover: Aggregate turnover in the preceding financial year. (Mandatory only for FY 2017-18; omit for others). | Conditional |
cur_gt |
Table 3 | Current Gross Turnover: Cumulative aggregate turnover in the current financial year. (Mandatory only for FY 2017-18; omit for others). | Conditional |
b2b |
Table 4 | Taxable outward supplies to registered persons. | Conditional |
b2cl |
Table 5 | B2C Large: Inter-state supplies to unregistered persons where Invoice Value > ₹1 Lakh (for periods on/after Aug 2024) or > ₹2.5 Lakh (for periods before Aug 2024). | Conditional |
exp |
Table 6 | Exports (Overseas), including Deemed Exports and SEZ supplies. | Conditional |
b2cs |
Table 7 | B2C Small: Intra-state supplies or Inter-state < ₹1 Lakh. | Conditional |
nil |
Table 8 | Nil-rated, exempted, and non-GST outward supplies. | Conditional |
b2ba, b2cla, expa |
Table 9 | Amendments to previous period B2B, B2CL, or EXP invoices. | Conditional |
cdnr, cdnur |
Table 9B | Credit and Debit Notes. | Conditional |
b2csa, cdnra |
Table 10 | Amendments to B2CS and Credit/Debit Notes. | Conditional |
at, txpd |
Table 11 | Advances received and adjusted. | Conditional |
hsn |
Table 12 | HSN-wise summary of outward supplies. Now bifurcated into B2B and B2C segments. | MANDATORY |
doc_issue |
Table 13 | Summary of documents issued (Invoices, Credit Notes, etc.). | MANDATORY |
eco, ecoa, ecob2b, ecob2c, ecourp2b, ecourp2c, ecoab2b, ecoab2c, ecoaurp2b, ecoaurp2c |
Tables 14 & 15 | Supplies made through E-commerce Operators (Liable to collect TCS u/s 52 or pay tax u/s 9(5)). | Conditional |
The GSTN portal generates internal fields during processing. User-generated JSON files MUST NOT include these fields, or the upload will be rejected with a "Technical Error":
chksum: Hashes generated for integrity check.flag: Status indicators (e.g., "U", "N", "D").updby,cflag,cfs,fil_dt: Internal processing metadata.
The JSON standard enforces different nesting rules depending on the section:
- Nesting Rule (B2B, B2CL, CDNR): Tax and rate details must be wrapped in an
itm_detobject within the items array. - Flatness Rule (EXP, B2CS): Item details (rate, taxable value, tax amounts) are flat siblings under the items array or the main object.
- Leading Property: The key
hsn_sc(SAC/HSN code) must be the first property in every HSN entry. - Mandatory Fields:
hsn_sc,desc,uqc,qty,rt,txval, andnum. - Bifurcation: Separate lists for
hsn_b2bandhsn_b2care required. - Length Validation: Minimum 6 digits for taxpayers with Annual Aggregate Turnover (AATO) > ₹5 Crore.
- Strings: Identifiers (
inum,ctin,gstin,pos) and Dates (idt) must be double-quoted strings. - Numbers: Taxable values and tax amounts must be numeric (integers or decimals).
- Dates: Strictly
DD-MM-YYYY. - Period (
fp): StrictlyMMYYYY(e.g.,122025for Dec 2025).