MS RFC 123:mapfile json模式¶

日期: 2018／03
作者: 塞思吉尔文
联系: sethg@geographika.co.uk
状态: 提出
版本: MAPServer 7.4

1.简介和背景¶

编写映射文件通常是手工完成的，只有当从映射文件生成地图时，错误才会变得明显。此提议建议为完整的mapfile语法定义一个JSON模式，以允许对mapfile进行验证。根据模式验证映射文件具有以下优点：

关键字错误警告
结构无效警告
更全面和一致的文档
不推荐使用的关键字的警告
mapfile语言的可解析定义，允许为ace编辑器、pygments、vim等创建与mapfile相关的语法。

此外，还建议为每个属性添加元数据，记录mapserver的哪个版本引入了关键字，如果已弃用，则最后一个版本是有效的。

2009年提出了一个类似的提议，为mapfiles引入一个XML模式——参见RFC51。

以机器可解析的格式存储完整的mapfile语法可以打开其他可能性，例如自动生成mapfile语法文档。

mappyfile嵌套字典结构。独立于此。任何语言都可以用来创建一个mapfile json对象进行验证。还需要创建打印功能来将结构转换回映射文件-但是此步骤比最初解析映射文件和转换为字典结构容易得多。与mappyfile中的python示例一起，漂亮打印机类的javascript端口应该是相当直接的。

语言独立

映射文件。Web和JavaScript。JavaScript示例。

已经尝试对每个MapServer类的JSON模式定义进行第一次传递，可以在添加时看到。在添加到MapServer存储库之前，需要对这些进行粗略的检查。

用户界面来去匆匆，但是 Mapfile 还保留着！

2.实施细节¶

JSON4架构.

新的属性和对象定义将只添加到架构中，但是不会删除任何属性，只标记为不推荐使用，以允许验证不同版本的MapServer。

这种方法还意味着不需要对模式本身进行版本控制，这是正确的吗？元数据不推荐使用的属性将需要自定义检查。

2.1 模式文件¶

每个mapfile类-即在 TYPE...END 块中定义的结构，将有自己的JSON模式文件。例如， LAYER 对象存储在 layer.json 文件中。

对于在映射文件中不同位置使用的某些属性，这些属性将被拆分为各自的模式，以便于重用，例如。 EXTENT 值， ON 和 OFF 设置，以及 COLOR 属性。

可以提供一个python脚本，并作为文档构建的预发布步骤运行，该文档构建将执行以下操作：

将长格式文档和JSON模式合并到单个文档页面中
将所有单独的JSON模式文件合并到一个单独的文件中，以便通过添加到MapServer文档中的指向该文件的链接更容易地分发。此合并文件也可由最新的mappyfile分发使用。

2.2映射文件类¶

每个mapfile类将以标准JSON模式属性开始：

{
    "type": "object",
    "required": [ "type" ],
    "additionalProperties": false,
    "properties": {
    }
}

如果MapServer需要设置任何属性，则这些属性将列在 required 对象的属性。例如，没有 LAYER ，缺少一个 TYPE 属性将在MapServer中引发错误。

这个 additionalProperties 属性定义对象是否可以具有架构中未列出的属性。在大多数情况下，这将被设置为 false ，因为架构中未列出的任何关键字都将无效。

在可以设置任意关键字的情况下，例如 METADATA 和 VALIDATION 对象 additionalProperties 将被设置为 true . 当允许任何值时，json模式定义将保持如下打开状态：

{
  "type": "object",
  "properties": {
  },
  "additionalProperties": true
}

如果有一组已知的值，将列出这些值，并可选择任意添加更多值，例如 CONFIG 设置:

{
    "config": {
      "type": "object",
      "properties": {
        "CGI_CONTEXT_URL": { "type": "string" },
        "MS_ENCRYPTION_KEY": { "type": "string" },
        "ON_MISSING_DATA": {
          "type": "string",
          "enum": [ "FAIL", "LOG", "IGNORE" ]
        },
      },
      "additionalProperties": true
     }
 }

如果类中的任何属性本身是类，则将使用指向相关.json文件的 $ref 属性进行引用。例如， LAYER 可以包含一个 METADATA 对象。此架构引用如下：

{
    "metadata": {
      "$ref": "metadata.json"
    }
}

TODO添加“include”： "string"
不能在层中包含“required”：[“type”]，因为这可能在包括中
"__position__"

2.3映射文件类数组¶

几个mapfile类可以在其父类中重复，例如 LAYER 可以有很多 CLASS 对象，或多个 FEATURE 对象。在这些情况下，属性名将被设置为复数，并且类型为 array ：

{
    "features": {
      "type": "array",
      "items": {
        "$ref": "feature.json"
      }
    }
}

在大多数情况下，只需添加一个“S”，例如功能、层。在属性已经以“s”结尾，则将使用“e s”，例如类（ES）。

2.4属性定义¶

大多数属性定义都是不言而喻的，例如 MAP 可以有一个 ANGLE 属性和 LEGEND 可以有 STATUS 属性。它们分别是 numeric ， string 和 enumeration 。

{
    "angle": {
      "type": "number"
    },
    "imagetype": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [ "on", "off", "embed" ]
    }
}

其他属性更复杂。例如 COLOR 属性用于映射文件中的多个位置。这可以接受rgba值或HTML颜色代码。

{
  "oneOf": [
    {
      "type": "array",
      "items": {
        "type": "number",
        "minimum": 0,
        "maximum": 255
      },
      "minItems": 3,
      "maxItems": 3
    },
    {
      "pattern": "^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$",
      "example": "#aa33cc",
      "type": "string"
    }
  ]
}

2.5属性元数据¶

在JSON模式中存储元数据的推荐方法是在 metadata 属性TODO ADD LINK中。将只为已弃用或最近引入到mapfile语法中的属性添加元数据。最近在这里被定义为好像它仍然在文档中提到。

例如 LAYER 对象上的 LABELMAXSCALE 属性在MapServer 5.0版中已弃用（根据文档）。在不深入了解源代码历史的情况下，引入的属性的版本是未知的。在这种情况下， minVersion 将设置为0。

{
    "labelmaxscale": {
      "type": "number",
      "metadata": {
        "deprecated": true,
        "minVersion": 0,
        "maxVersion": 5.0
      }
    }
}

另一个将在模式中偶尔使用的标准JSON模式属性是 example 属性Todo添加链接。这主要用于记录要在MapServer文档中列出的有效值的示例。例如，一个有效值 COLOR 属性是HTML颜色代码。属性定义中列出了一个示例值。

{
    "pattern": "^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$",
    "example": "#aa33cc",
    "type": "string"
}

3.文件变更¶

目前，mapserver mapfile语法记录在重构文本（rst）中。

这个 jsonschema2rst 项目将JSON模式转换为RST。

建议修改当前文档的结构，使其更容易与现有的长格式文档结合JSON模式细节组合在一起，并删除两者之间的任何重复。

很重要的一点是，可以轻松编辑长格式文本并添加示例，因此这种方法旨在增强手写文档，而不是替换它。

这样可以避免诸如https://github.com/mapserver/mapserver/issues/5748等问题

4.在线验证器¶

基于javascript的验证器？选择版本。默认为最新（7.2）。

5.实施细节¶

5.1受影响的文件¶

没有代码文件需要修改
可以逐步重新构造 /mapfile 文件夹中的所有文档，以允许从JSON模式插入属性定义