Skip to main content
Version: 3.7

JSON 表示规范

1. 介绍​

  • 版本号：1.0
  • 提案人：赵雨森
  • 评审人：NASL 技术委员会全体成员

(1) 背景​

在表示 NASL AST 的定义和内容时，对于一个属性，以下情形经常容易混淆：

  • NASL TS 定义中的可选类型?表示的类型为T | undefined、T | null还是T | null | undefined？
  • JSON 中的字段为null、还是字段不存在？
  • Java 中的字段为null、还是字段不存在？
  • JS 中的字段为null、还是undefined？

而在文档中表示一个节点示例时，如果null字段的情况过多时，则显得过于冗长。

因此，在这里做明确规范。

2. 内容​

为了确保准确性和便捷性，制定两种 JSON 表示规范：存储 JSON 表示和书写 JSON 表示。

(1) 存储 JSON 表示​

要求 NASL 定义与存储无歧义。

即 NASL TS 定义中出现的字段均存在，在存储时用null填充。

即 NASL TS 定义中的可选类型?表示的类型为T | null（虽然 TS 语言本身无这种表示，但可以通过类型体操转换）。

示例​

如下面两个 TS 定义：

class Variable extends BaseNode {
    name: string = '';
    description?: string;
    typeAnnotation: TypeAnnotation;
    defaultValue?: string;
}

class StringLiteral extends LogicItem {
    value: string = '';
}

存储 JSON 表示如下：

{
    "concept": "Variable",
    "name": "total",
    "description": "",
    "typeAnnotation": {
        "concept": "TypeAnnotation",
        "typeKind": "primitive",
        "typeNamespace": "nasl.core",
        "typeName": "Long",
        "inferred": false,
        "ruleMap": {},
        "typeArguments": null,
        "returnType": null,
        "properties": null
    },
    "defaultValue": null
}
{
    "concept": "StringLiteral",
    "value": "这是一段文本",
    "label": null,
    "description": null,
    "folded": null,
    "offsetX": null,
    "offsetY": null
}
info

可以发现，存储 JSON 能够准确表示存储内容和 NASL 节点定义。

但 null的字段过多，作为文档时易读性较差，容易让读者不容易提取到关键信息。因此最好有另一种表示方式。

(2) 文档 JSON 表示​

将存储表示中为null字段统一去掉。

即 NASL TS 定义中的可选类型?表示的类型由T | null通过类型体操转换为T | undefined。undefined字段在 JSON 中不出现。

示例​

书写 JSON 表示如下：

{
    "concept": "Variable",
    "name": "total",
    "description": "",
    "typeAnnotation": {
        "concept": "TypeAnnotation",
        "typeKind": "primitive",
        "typeNamespace": "nasl.core",
        "typeName": "Long",
        "inferred": false,
        "ruleMap": {}
    }
}
{
    "concept": "StringLiteral",
    "value": "这是一段文本"
}
caution

存储 JSON 表示容易直接转换为文档 JSON 表示。

但反之需要结合 NASL TS 定义补齐字段。