.gjson 文件定义

`.gjson` 是 GenePad 的文本 JSON 交换格式，当前写出版本为 `1.9`。它适合人工查看、版本 diff、Web 导入导出和跨语言快速读取。

version = 1.9 JSON text 1-based inclusive

Example

最小有效结构

{
  "version": "1.9",
  "id": "gjson-1752000000000",
  "type_of_display": "file_name",
  "custom_name": "",
  "description": "示例序列",
  "sequence": "ATGCGTAC",
  "length": 8,
  "isCircular": false,
  "isDoubleStranded": true,
  "features": [
    {
      "id": "feature-0",
      "name": "示例 CDS",
      "type": "CDS",
      "start": 1,
      "end": 6,
      "strand": "forward",
      "color": "#38a16f",
      "visible": true
    }
  ],
  "baseColorRanges": [],
  "primers": []
}

读取时至少需要 version 和 sequence。其他字段缺失时会走默认值。

Top Level

顶层字段

字段	类型	说明
`version`	string	必须存在，当前写出 `"1.9"`
`id`	string	写出时生成，当前读取不作为主 id 恢复
`type_of_display`	file_name / custom	显示名策略；加载时通常由文件名覆盖
`custom_name`	string	自定义显示名
`description`	string	序列描述，缺失为空字符串
`sequence`	string	必须存在，主 DNA 序列
`length`	number	写出为 `sequence.length`；读取时以实际序列长度为准
`isCircular`	boolean	缺失时为 false
`isDoubleStranded`	boolean	缺失时 canonical 层默认为 true
`accession`	string	GenBank accession
`organism`	string	物种
`date`	string	日期
`moleculeType`	string	如 DNA, ss-DNA, ds-DNA
`division`	string	GenBank division
`gbVersion`	string	映射到内部 `version`
`keywords`	string	GenBank KEYWORDS
`source`	string	GenBank SOURCE
`comments`	string	GenBank COMMENT
`references`	GenBankRef[]	结构化 REFERENCE 信息
`features`	GjsonFeature[]	缺失按空数组处理
`baseColorRanges`	BaseColorRange[]	缺失按空数组处理
`primers`	GjsonPrimer[]	缺失按空数组处理
`alignmentEntries`	GjsonAlignmentEntry[]	缺失按空数组处理

.gjson 不存储（与 .gen 的保真差异）：撤销/编辑历史（undo_entries / edit_history）、附件（attachments）、顶层 chromatogram、alignmentEntries[].chromatogram、Dam/Dcm 甲基化（isDamMethylated / isDcmMethylated）。需要完整保真快照请使用 .gen。

Objects

对象定义

GjsonFeature注释对象

{
  "id": "feature-0",
  "name": "lacZ",
  "type": "CDS",
  "start": 120,
  "end": 980,
  "strand": "forward",
  "color": "#4f7bd9",
  "label": "lacZ",
  "note": "example",
  "frame": 1,
  "visible": true,
  "segments": [
    { "start": 120, "end": 240, "strand": "forward" }
  ],
  "qualifiers": {
    "gene": ["lacZ"],
    "translation": ["M..."]
  }
}

start/end 为 1-based inclusive。segments 仅在段数 > 1 时写出（单段 feature 只用顶层 start/end）；环形跨原点时 start > end。qualifiers 类型为 Record<string, string[]>，保留 GenBank qualifier（如 /translation、/codon_start）。

GjsonPrimer引物对象

{
  "id": "primer-0",
  "name": "Fwd",
  "sequence": "ATGCGTAC",
  "description": "forward primer",
  "visible": true,
  "bindingSites": [
    {
      "start": 10,
      "end": 17,
      "boundStrand": "forward",
      "annealedBases": "ATGCGTAC",
      "meltingTemperature": 52.3,
      "components": [{ "bases": "ATGCGTAC" }],
      "alignment": []
    }
  ]
}

bindingSites[] 字段：start/end 1-based inclusive，boundStrand 为 forward/reverse，meltingTemperature 为 Tm(℃)，components 是 {hybridizedRange?, bases} 数组，alignment 是 AlignmentSegment[]（写出时默认空数组，visible 缺省为 true）。

BaseColorRange碱基颜色

{
  "id": "base-color-0",
  "start": 1,
  "end": 20,
  "strand": "forward",
  "color": "#ffcc00"
}

strand 只接受 forward 或 reverse；非 reverse 会被归一为 forward。

GjsonAlignmentEntry比对条目

{
  "id": "read-1",
  "name": "Sanger read 1",
  "sequence": "ATGC...",
  "visible": true
}

.gjson 中比对条目仅保留 id, name, sequence, visible 四个字段；运行时的 chromatogram 不写入 .gjson。