moddle Descriptor

The moddle descriptor is a JSON file that describes elements, their properties and relationships.

Package Definition

The root of a descriptor file is a package definition.

{
  "name": "SamplePackage",
  "prefix": "s",
  "types": [],
  "enumerations": []
}

Notes

The prefix uniquely identifies elements in a package if more multiple packages are in place.

The types collection contains all known types.

The enumerations and associations properties are reserved for future use.

Type Definition

A type is a moddle element with a (package-) unique name and a list of properties.

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

Inheritance

Types can inherit from one or more super types by specifying the superClass property.

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

By inheriting from a super type, a type inherits all properties declared in the super type hierarchy.

Inherited properties will appear before own properties based on the order they are declared in the type hierarchy.

Extending existing Types

Some meta-models require it to plug-in new properties that to certain existing model elements. This can be acomplished using the extends field. Consider the following type definition:

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

With this model definition, every instance of Root will automatically have another property BetterRoot#id added. At the same time, instances of root will be instances of BetterRoot, too.

This extension is implicit when compared to inheritance. In the inheritance case one would need to instantiate BetterRoot, to actually get the new property id. Extending allows us to simply instantiate Root with the additional property defined for it.

Property Definition

A property has a name, a type as well as a number of additional qualifiers and is added to a types properties list.

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

The type attribute may reference simple types such as String, Boolean, Integer or Real or any custom defined type.

Qualifiers

Qualifiers can be used to further define a property.

Qualifier	Values	Description
isMany=false	Boolean	collection (i.e. list like) property
isReference=false	Boolean	reference to another object via its id property
default	simple type	the default value to set if non is defined
redefines	String (identifier)	redefines the property inherited from a super type, overriding name, type and qualifiers

Cross Package Referencing

Across packages, elements may be referenced via packagePrefix:packageLocalName.

Example

Given we got two packages, a base package, and a domain package that builds on top of it.

{
  "$schema": "https://unpkg.com/moddle/resources/schema/moddle.json",
  "name": "BasePackage",
  "prefix": "b",
  "types": [
    { "name": "Base" },
    {
      "name": "BaseWithId", 
      "superClass": [ "Base" ],
      "properties": [ { "name": "id", "type": "String" } ]
    }
  ]
}

The domain package may define its own types on top of the base package by referencing properties and types defined in the base package via their name, prefixed with b:.

{
  "$schema": "https://unpkg.com/moddle/resources/schema/moddle.json",
  "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 }
      ]
    }
  ]
}

To instantiate the domain package as part of a moddle instance, the base package must be provided, too.

External Links

Valid locations for externally defined types and properties are

• a types superClass attribute
• a properties type attribute
• a properties redefines attribute (e.g. to redefine a property inherited from an externally defined type)

Serializing to XML

Reading and writing XML from moddle is possible via moddle-xml. It requires additional meta-data to be specified in your moddle descriptor.

Validating the Schema

A JSON schema is available, include it via the $schema attribute in your moddle descriptor and it will be picked up by code editor:

{
  "$schema": "https://unpkg.com/moddle/resources/schema/moddle.json",
  ...
}