Variable library definition

Article
2025-04-09

This article provides a breakdown of the definition structure for variable library items.

Definition parts

This table lists the variable library definition parts.

Definition part path	type	Required	Description
`variables.json`	Variables (JSON)	✅	Describes the variables in the item
`settings.json`	VariableLibrarySettings (JSON)	✅	Define user controlled settings
`.platform`	PlatformDetails (JSON)	❌	Describes common details of the item
`valueSets\valueSetName.json`	ValueSet (JSON)	❌	Define the default template to be used when rendering the item

Variables

Describes the variables in a Variable Library item.

Name	Type	Description
variables	Variable[]	The variables collection.

Variable

Describes a variable.

Name	Type	Required	Description
name	String	✅	The name of the variable.
type	String	✅	The variable type.
value	JSON	✅	The default value of the variable.
note	String	❌	A note describing the variable.

Supported variable types

List of supported variable types.

Name	Type	Example
Boolean	BooleanVariable	true, false
DateTime	DateTimeVariable	"2025-01-20T15:30:00Z"
Number	NumberVariable	1.1
Integer	IntegerVariable	1
String	StringVariable	"Some string"
ItemReference	ItemReferenceVariable	{ "workspaceId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb", "itemId": "bbbbbbbb-1111-2222-3333-cccccccccccc" }

Variables.json example

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/variableLibrary/definition/variables/1.0.0/schema.json",
  "variables": [
    {
      "name": "variable1",
      "note": "Some optional note",
      "type": "String",
      "value": "Some string value"
    },
    {
      "name": "variableWithoutNote",
      "type": "boolean",
      "value": true
    }
  ]
}

ValueSet

Describes a value set. File name must be similar to value set name.

Name	Type	Description
name	String	Name of the value set.
description	String	Description of the value set.
variableOverrides	VariableOverride	List of overridden variables.

VariableOverride

Describes a value override.

Name	Type	Description
name	String	Name of the overridden variable.
value	String	The new variable value.

valueSets/valueSet.json example

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/variableLibrary/definition/valueSet/1.0.0/schema.json",
  "name": "valueSetName",
  "variableOverrides": [
    {
      "name": "variable1",
      "value": "Some new value"
    }
  ]
}

VariableLibrarySettings

Describes user defined Variable Library settings.

Name	Type	Description
valueSetsOrder	String[]	Optional list of value set names for ordering.

settings.json example

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/variableLibrary/definition/settings/1.0.0/schema.json",
  "valueSetsOrder": [
    "valueSet1",
    "valueSet0",
    "someOtherValueSet"
  ]
}

Considerations and limitations

ValueSetsOrder list can be empty or partial.
ValueSetsOrder list can't include invalid value set names.
When updating a variable library item with a partial or empty valueSetsOrder list, missing value set names are added to the end of the list in alphabetical order.

Definition example

{
"parts": [
    {
        "path": "variables.json",
        "payload": "<base64 encoded string>",
        "payloadType": "InlineBase64"
    },
    {
        "path": "valueSet/valueSet1.json",
        "payload": "<base64 encoded string>",
        "payloadType": "InlineBase64"
    },
    {
        "path": "valueSet/valueSet2.json",
        "payload": "<base64 encoded string>",
        "payloadType": "InlineBase64"
    },
    {
        "path": "settings.json",
        "payload": "<base64 encoded string>",
        "payloadType": "InlineBase64"
    },
    {
        "path": ".platform",
        "payload": "ZG90UGxhdGZvcm1CYXNlNjRTdHJpbmc=",
        "payloadType": "InlineBase64"
    }
]
}

Share via