Qt-Bridge Metadata format

Brief Overview of the metadata schema

Qt Design Studio has the capability to generate QML based UI files from a json file. Qt Design Studio expects a .metadata file for the import and the contents define the DOM and the QML item's properties in the json format. 

Qt-Bridge plugins for Photoshop and Sketch generate such .metadata files. The .metadata files can be imported in the Qt Design Studio to generate QML.

Similarly, other design tools can export the user interface in the specified metadata format to generate QML using Qt Design Studio.

The JSON format:

The root object contains three sections, plugininfo, documentinfo and artboards. 

• pluginInfo: This object has information about the plugin used to export the metadata.
• documentInfo: This object has the information about the document.  
• artboards: This section contains the DOM and the layer properties.

See the metadata JSON Schema for details.

Plugin Info:

The properties defined under the "pluginInfo" object provide the information about the plugin used to export the metadata. Some properties can also change the behavior of the Asset Import in Qt Design Studio.

• applicationId *
• applicationName (Available in QDS version 2.1)
• applicationVersion
• extensionVersion *
• metadataVersion *
• assetNameScheme (Available in QDS version 2.1)
• coordinateSystemScheme (Available in QDS version 2.1)

* Required

Application ID

The application Id of the plugin. The value should be "Generic".

"pluginInfo": {
    "applicationId": "Generic"
  }

Application Name

The host application(Photoshop, Sketch, Figma etc) name. This value can be useful for logging and fixing bugs.

"pluginInfo": {
    "applicationName": "UI Maker"
  }

Application Version

The host application(Photoshop, Sketch, Figma etc) version. This value can be useful for logging and fixing bugs.

"pluginInfo": {
    "applicationVersion": "21.1.1"
  }

Extension Version:

The Qt Bridge plugin version. This value can be useful for logging and fixing bugs.

"pluginInfo": {
    "extensionVersion": "1.5.0"
  }

Metadata Version:

The metadata format version. The current version is 1.1. 

"pluginInfo": {
    "metadataVersion": "1.1"
  }

Asset Name Scheme:

This value defines the scheme of the file names generated for assets. The possible values are:

• uuid: The UUID of the corresponding item is used as the asset file name. In this case, the asset importer will clean the file names on import. Since the UUIDs are unique, this is usually used to avoid a name clash of the generated asset files.
• default: No renaming of the asset files is done and the files are imported as-is.

Note: undefined or incorrect value is treated as value "default"

"pluginInfo": {
    "assetNameScheme": "uuid"
  }

Coordinate System Scheme:

This value defines how the coordinated values are interpreted. The possible values are:

• global: The asset importer expects the coordinate values as global values(Scene values).
• parent: The asset importer expects the coordinate values to be in the parent's coordinate system.

Note: undefined or incorrect value is treated as value "parent"

"pluginInfo": {
    "coordinateSystemScheme": "parent"
  }

Document Info:

The "documentInfo" object defines the properties of the host application document used to export the metadata. Following properties defined under the "documentInfo" object:

• name: The document name *

* Required

Artboards:

Each object in the "artboards" json array defines a QML component.

Most of the design applications defines their user interface in layers, other application has a similar concept but sometimes with different nomenclature. 

Each QML component in the "artboards" json array is a JSON object which defines a layer of the UI, thus "artboards" is a json array of layer objects where each layer object can compose child layers. Each property of the layer object is defined in the JSON Schema. 

Note that a layer can either have an assetData or textDetails. A layer with assetData creates a QML object of type Image and a layer with textDetails generates QML object of type Text. A layer without any assetData or textDetails shall create a QML object of type Item. 

Layer hierarchy is maintained in the QML object model.

Most of the properties are self-explanatory. 

Layer object visualisation:

Sample Metadata:

example JSON 1

{
    "pluginInfo": {
        "applicationId": "Generic",
        "applicationVersion": "62",
        "extensionVersion": "1.5.1",
        "metadataVersion": "1.1"
    },
    "documentInfo": {
        "name": "shadow"
    },
    "artboards": [
        {
            "name": "Artboard",
            "x": 348,
            "y": 210,
            "width": 334,
            "height": 573,
            "metadata": {
                "qmlId": "artboard",
                "uuid": "CCF63935-D8DC-4802-B776-CA617F731D27",
                "exportType": "component",
                "qmlVisible": true,
                "opacity": 1,
                "assetData": {
                    "assetPath": "/samples/shadow/CCF63935-D8DC-4802-B776-CA617F731D27.png",
                    "assetBounds": {
                        "x": 0,
                        "y": 0,
                        "width": 334,
                        "height": 573
                    }
                }
            },
            "layerIndex": 0,
            "children": [
                {
                    "name": "rectOut",
                    "x": 82,
                    "y": 122,
                    "width": 81,
                    "height": 71,
                    "metadata": {
                        "qmlId": "rectout",
                        "uuid": "9BFFC9D2-7E85-4658-84F5-A9303C272E26",
                        "exportType": "child",
                        "qmlVisible": true,
                        "opacity": 1,
                        "assetData": {
                            "assetPath": "/samples/shadow/9BFFC9D2-7E85-4658-84F5-A9303C272E26.png",
                            "assetBounds": {
                                "x": 68,
                                "y": 112,
                                "width": 129,
                                "height": 119
                            }
                        }
                    },
                    "layerIndex": 0
                },
                {
                    "name": "text",
                    "x": 55,
                    "y": 81,
                    "width": 30,
                    "height": 21,
                    "metadata": {
                        "qmlId": "text",
                        "uuid": "FA8CF45D-DCCE-4CFD-A831-B92652AB92D9",
                        "exportType": "child",
                        "textDetails": {
                            "fontFamily": "SF Pro Text",
                            "fontSize": 17.6,
                            "kerning": -0.4244706,
                            "textColor": "#007affff",
                            "lineHeight": null,
                            "horizontalAlignment": "left",
                            "verticalAlignment": "top",
                            "fontDisplayName": "SF Pro Text Regular",
                            "contents": "text",
                            "multiline": false
                        },
                        "qmlVisible": true,
                        "opacity": 1,
                        "transformation": {
                            "rotation": 0,
                            "flippedHorizontally": false,
                            "flippedVertically": false
                        }
                    },
                    "layerIndex": 1
                }
            ]
        }
    ]
}

Download metadata JSON Schema

Layer object:

The following properties define a layer object: (* Required)

• name: (String) Layer's name.
• layerIndex: (Integral Number). Decides the stacking order *
• x: (Number) X coordinate value of the generated QML item
• y: (Number) Y coordinate value of the generated QML item
• width: (Number) Width of the generated QML item
• height : (Number) Height of the generated QML item
• metadata: (Object) Layer's metadata. *
• children(Array): Instances of child layer objects. QML items generated from these layer objects are added as the default child of its parent QML item.
• nodeChildren(Object of propName: Layer Object): These are also Instances of child layer objects with a propName. The QML items generated from these layer objects are added as the node abstract property of its parent QML item. The propName is the name of the property. This is useful e.g. to add "delegate" in a ListView or a "gradient" property in a Rectangle item.

Example: Rectangle with a gradient with two stops

{
  "x": 0,
  "y": 0,
  "name": "Background",
  "width": 600,
  "height": 800,
  "metadata": {
    "uuid": "bc7b0c70-7356-5722-bcbc-a9e32975173d",
    "qmlId": "background",
    "exportType": "component",
    "typeName": "Rectangle"
  },
  "layerIndex": 0,
  "nodeChildren": {
    "gradient": {
      "name": "gradient",
      "metadata": {
        "uuid": "ab7b0c50-7356-5722-bcbc-c9e32975175d",
        "qmlId": "lGradient",
        "exportType": "child",
        "typeName": "Gradient"
      },
      "children": [
        {
          "name": "stop1",
          "metadata": {
            "uuid": "fc320c70-7356-5722-bcbc-a9e32975173d",
            "qmlId": "stop1",
            "exportType": "child",
            "typeName": "GradientStop",
            "qmlProperties": [
              "position: 0.33",
              "color: \"yellow\""
            ]
          }
        },
        {
          "name": "stop2",
          "metadata": {
            "uuid": "ec4b0c70-7356-5722-bcbc-a9e32975173d",
            "qmlId": "stop2",
            "exportType": "child",
            "typeName": "GradientStop",
            "qmlProperties": [
              "position: 0.66",
              "color: \"orange\""
            ]
          }
        }
      ]
    }
  }
}

Metadata Object:

This section contains the metadata properties. Some of the properties are very niche and usually used in the advanced usage of the QML generation

Following QML properties can be manipulated:-

• exportType: (String)Export Type *
• qmlId: (String) QML id to be assigned *
• uuid: (String) A unique id. *
• assetData: (Object) Layer's exported asset details
• textDetails: (Object) When layer is a text layer. Contains text details.
• aliases: (Array<String>)To create property aliases
• extraImports: (Array<String>)To add QML imports
• aliasOverrides: To override the component instance's properties
• qmlProperties: (Array<String>) To add QML properties
• internalReference: (String) to create component instance [Deprecated with QDS 2.1. Use typeUuid]
• externalReference: (String) To assign custom QML type to the generated QML Item [Deprecated with QDS 2.1. Use typeName]
• annotation: (String) Contextual information about the layer. Use this to write comments.
• typeName: (String) Explicit QML type.
• typeUuid: (String) The UUID of the component whose instance this item should be.
• anchors: (String) To anchor the item to its parent.

Export type:

The property "exportType" defines how a layer is exported. It can have the following values.

• Component: The layer creates a separate QML file.
• Child: The layer is composed as a child under the parent item containing the layer object.
• Merged: The asset of the layer is merged up to its parent layer. The layer object will not create any QML or asset on its own.
• Skipped: completely skips the selected layer.

Asset Data: 

The "assetData" object contains the details of the associated assets. Following properties can added to the "assetData" object.

• assetPath: (String) path of the exported asset
• assetBounds: (Object) x, y, width, the height of the asset, otherwise the asset is positioned at (0, 0) inside parent
• additionalAssets: (Array<String>) extra assets to be imported for this item. E.g. Hi DPI assets.
• referenceAsset: This asset is not a part of the UI but a reference for the designers/developers. Usually, every child layers are rasterized in this asset.

example

"metadata": { 
    "assetData": {
        "assetPath": "/Users/bob/ex/799863CB-32CD-41F9-8029-68C5D7CC9EE7.png", 
        "assetBounds": { "x": 924, "y": 669, "width": 1014, "height": 969 }, 
        "additionalAssets": [ 
            "/Users/bob/ex/799863CB-32CD-41F9-8029-68C5D7CC9EE7.jpg", 
            "/Users/bob/ex/799863CB-32CD-41F9-8029-68C5D7CC9EE7@2.png", 
            "/Users/bob/ex/799863CB-32CD-41F9-8029-68C5D7CC9EE7@2.jpg" 
        ],
        "referenceAsset" : "/Users/bob/ex/799863CB-32CD-41F9-8029-68C5D7CC9EE7_ref.png"
    }
}

Property aliases:

Add "aliases" property to metadata object. "aliases" property takes an array of the properties of the respective Item for which QML aliases should be made at the component level. Primarily this is used to expose the properties of the child items, which is a requirement if the component is to be reused with the ability to override properties.  For example, add "aliases": ["text"] for the text item and the generated component will have an alias created.

example json and generated QML

example JSON 2

{
  "name": "Button",
  "x": 1774,
  "y": 36,
  "width": 160,
  "height": 70,
  "metadata": {
    "qmlId": "largeButton",
    "uuid": "5BF41D32-9220-4952-A405-A0CF85B76827",
    "exportType": "component",
    "qmlVisible": true,
    "opacity": 1,
    "assetData": {
      "assetPath": "/pop/F66E090D-2544-42CD-9CC7-B6CD46AAC5D5.png"
    }
  },
  "layerIndex": 3,
  "children": [
    {
      "name": "button",
      "x": 10,
      "y": 9,
      "width": 140,
      "height": 49,
      "metadata": {
        "qmlId": "button",
        "uuid": "9466F7DC-61D0-47F4-8CAC-4FB3D09E6386",
        "exportType": "child",
        "textDetails": {
          "fontFamily": "Helvetica Neue",
          "fontSize": 20,
          "textColor": "#000000ff",
          "lineHeight": 23,
          "horizontalAlignment": "center",
          "verticalAlignment": "center",
          "fontDisplayName": "Helvetica Neue Light",
          "contents": "button",
          "multiline": true
        },
        "aliases": [
          "text"
        ]
      },
      "layerIndex": 1
    }
  ]
}

Generated QML

import QtQuick 2.8

Item {
    id: largeButton
    width: 160
    height: 70
    property alias buttonText: button.text

    Image {
        id: largeButtonAsset
        x: 0
        y: 0
        source: "assets/largeButton.png"
    }

    Text {
        id: button
        x: 10
        y: 9
        width: 140
        height: 49
        color: "#ff000000"
        text: "button"
        font.pixelSize: 20
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        lineHeight: 23
        lineHeightMode: Text.FixedHeight
        wrapMode: Text.WordWrap
        font.family: "Helvetica Neue"
        font.styleName: "Light"
    }
}

QML imports:

Add "extraImports" property to metadata object to add QML imports to the component. "extraImports" (Array of strings) property takes an array of the import statements. The import statements are added to the Item are added to the generated QML component.

example:

"metadata": {
    "extraImports": [
    	"import myModule 1.0",
        "import QtQuick.Controls 1.4"
        ]
  }

Overrides: 

"aliasOverrides" metadata property is used to override the properties of the Component instance. Consider the example JSON 2 with the following metadata JSON snippet

example JSON 3

{
  "name": "LoginButton",
  "x": 217,
  "y": 266,
  "width": 212,
  "height": 70,
  "metadata": {
    "qmlId": "loginButton",
    "uuid": "8A9AB24E-18F0-4207-8C7B-3E3442706683",
    "exportType": "child",
    "internalReference": "5BF41D32-9220-4952-A405-A0CF85B76827",
    "qmlVisible": true,
    "opacity": 1,
    "aliasOverrides": [
      {
        "name": "text",
        "value": "\"Login\"",
        "targetId": "9466F7DC-61D0-47F4-8CAC-4FB3D09E6386"
      }
    ]
  },
  "layerIndex": 1
}

 LargeButton {
     id: loginButton
     x: 217
     y: 266
     width: 212
     height: 70
     buttonText: "Login"
 }

QML properties:

QML properties can be added explicitly to an Item. Add "qmlProperties" property to the metadata object to define the properties. "qmlProperties" expects an array of strings. 

example:

"metadata": {
    "qmlProperties": [
    	"color : \"#aa65cc\"",
        "width : variable_y",
        "horizontalAlignment : ENUM(Image.AlignRight)"
        ]
  }

Note: To add property of type Enumeration, wrap the value under the tag "ENUM(value)". See the example above. The color values are expected to be in AARRGGBB format.

With the aforementioned property "qmlProperties", all the QML properties can be assigned but there are some metadata object properties that can be defined to generate few QML properties easily. i.e.

• clip: Set item's clipping.
• createAlias: To add an alias property to this item in the parent component.
• opacity: Add opacity value to the item
• qmlVisible: Set the item visibility.

"metadata": {
    "clip": true,
    "qmlVisible": false,
    "createAlias": true,
    "opacity": 0.4
  }

internalReference: [Deprecated. Use typeUuid]

This property is used to create the instance of a component already defined in the metadata file. Assign the UUID of the component whose instance has to be generated.

example

"metadata": {
    "internalReference": "5BF41D32-9220-4952-A405-A0CF85B76827"
  }

externalReference: [Deprecated. Use typeName]

The type of the QML item generated can be dictated as well. "externalReference" metadata object property to define the type of the generated QML item.

example

"metadata": {
    "externalReference": "Button"
  }

typeName: [Available from QDS 2.1]

The type of the QML item generated can be dictated as well. "typeName" metadata object property to define the type of the generated QML item.

example

"metadata": {
    "typeName": "Button"
  }

typeUuid: [Available from QDS 2.1]

The UUID of a component. Add the UUID of the component whose instance the generated QML should be. The Asset importer tries to find the QML Type of the target component and assigns the type to the generated QML Item.

example

"metadata": {
    "typeUuid": "5BF41D32-9220-4952-A405-A0CF85B76827"
  }

anchors: [Available from QDS 2.2]

The generated QML item can be anchored to its parent Item. The value can be a comma-separated string containing "left", "top", bottom, and "right". The position and dimension values are used to calculate the anchor margins.

Note: The QML properties "x", "y", "width", and "height" might be irrelevant and shall be removed if the respective anchors are defined. e.g. property "x" is removed when the "left" or "right" anchor is defined. 

example

"metadata": {
    "anchors": "left, bottom"
  }