npmnjs学习笔记-moddle description编写规则

moddle description

模块描述文件是一个JSON文件，它描述元素，以及元素属性和关系。

包的定义

模块描述文件的根是包定义。包定义的扩展允许您配置命名空间和元素序列化。

{
  "name": "SamplePackage",
  "prefix": "s",
  "url": "http://www.sample.com",
  "xml": {
     "tagAlias": "lowerCase"
  }
  "types": [],
  "enumerations": []
}

注：

prefix：唯一标识包中的元素，如果更多的多个包到位。

url：在包定义中指定字段以定义关联的XML名称空间url。

xml: 定义xml序列化的参数，比如上面参考代码中的 "tagAlias": "lowerCase" 表示将element的名字变为小写。

types：集合类型用于描述定义包中所含所有已知类型。

enumerations和associations：属性留作将来使用。

示例：

包定义：

{
  "prefix": "s",
  "url": "http://sample"
}

序列化的结果：

<s:Root xmlns:s="http://sample" />

类型的定义（type）

类型是在一个命名空间（package-）包中具有唯一名称和属性列表的模块元素。

{
  "name": "Base",
  "properties": [
    { "name": "id", "type": "Number" },
    ...
  ]
}

遗传特征（Inheritance）

通过指定superClass属性，类型可以从一个或多个超级类型继承属性。

{
  "name": "Root",
  "superClass": [ "Base" ]
}

通过从超类型继承，类型将继承在超类型层次结构中声明的所有属性。

根据在类型层次结构中声明的顺序，继承的属性将出现在自己的属性之前。

扩展已存在类型（Extending existing Types）

一些元模型要求它为某些现有模型元素插入新属性。可以使用该extends字段来完成。参考以下类型定义：

{
  "name": "BetterRoot",
  "extends": [ "Root" ], 
  "properties": [
    { "name": "id", "type": "Number" }
  ]
}

使用此模型定义，每个Root类型的实现都会自动添加一个属性BetterRoot#id。同时，Root类型的实现也将成为BetterRoot类型的实现。

与遗传特征扩展方式相比，此扩展是隐式的。在遗传特征扩展方式下，需要实例化BetterRootid才能真正获得新属性。扩展的方式允许我们简单地实现为Root的实例添加属性。

定义属性（Property Definition）

属性具有名称，类型以及许多其他限定符，并被添加到类型的properties列表中。

{
  "name": "stringProperty",
  "type": "String"
}

type：属性可以参考，如String，Boolean，Integer或Real或任何自定义的类型。

限定符（Qualifiers）

限定符可用于进一步定义属性。

限定符	类型	描述
isMany=false	Boolean	集合（如列表）属性
isReference=false	Boolean	通过其id属性引用另一个对象
default	*	在定义为non时要设置的默认值
redefines	String （标识符）	重新定义从超类继承的属性，覆盖name，type和其他限定符
isAttr=false	Boolean	序列化为属性
isBody=false	Boolean	序列化为元素的主题标签
serialize	String	添加附加的序列化标记。支持的值有：xsi：type 序列化为数据类型而不是元素。

交叉使用（Cross Package Referencing）

在一个需要使用其他包定义的元素时可以通过packagePrefix:packageLocalName方式引用。

示例

假定我们有两个软件包，一个BasePackage，以及一个在其之上构建的DomainPackage。

{
  "name": "BasePackage",
  "prefix": "b",
  "types": [
    { "name": "Base" },
    {
      "name": "BaseWithId", 
      "superClass": [ "Base" ],
      "properties": [ { "name": "id", "type": "String" } ]
    }
  ]
}

DomainPackage可以通过在BasePackage中的b:typeName方式引用属性和类型来定义自己的类型。

{
  "name": "DomainPackage",
  "prefix": "d",
  "types": [
    {
      "name": "Base",
      "superClass": [ "b:BaseWithId" ],
      "properties": [
        {
          "name": "id",
          "type": "Integer",
          "redefines": "b:BaseWithId#id"
        }
      ]
    },
    {
      "name": "Root", 
      "properties": [
        { "name": "elements", "type": "b:Base", "isMany": true }
      ]
    }
  ]
}

要将DomainPackage实例化为模块实例的一部分，还必须提供BasePackage。

外部引用

引用外部定义的类型和属性的有效使用位置是

• 类型的superClass属性
• 类型属性的type属性
• 类型属性的redefines属性

序列化为XML

可以通过moddle-xml项目提供的方法从moddle中 读写XML。它要求在模块描述文件中指定附加的元素标签和属性。