Lakehouse definition

This article provides a breakdown of the definition structure for Lakehouse items using LakehouseDefinitionV1 format. For detailed information, see: How to create a lakehouse with Microsoft Fabric Rest API

Supported formats

Lakehouse items support the LakehouseDefinitionV1 format. If no format is specified, it will default to LakehouseDefinitionV1.

Definition parts

Definition part path	Type	Required	Description
`lakehouse.metadata.json`	LakehouseMetadata (JSON)	true	Describes the lakehouse properties
`shortcuts.metadata.json`	Shortcut[] (JSON)	false	Describes the onelake shortcuts associated with the lakehouse
`data-access-roles.json`	DataAccessRole[] (JSON)	false	Describes the data access roles associated with the lakehouse. This part is only respected if it is enabled through `AlmSettings`. It is disabled by default.
`alm.settings.json`	AlmSettings (JSON)	false	Describes the ALM settings associated with the lakehouse
`.platform`	PlatformDetails (JSON)	false	Describes common details of the item

LakehouseMetadata

Describes lakehouse metadata.

Name	Type	Required	Description
defaultSchema	String	false	Current status of the execution.

Shortcut

Name	Type	Required	Description
name	String	true	Name of the shortcut.
path	String	true	A string representing the fill path where the shortcut is created, including either "Files" or "Tables".
target	Target	true	An object that contains the target datasource, and must specify exactly one of the supported destinations.

Target

An object that contains the target datasource, and must specify exactly one of the supported destinations as described in the table below.

Name	Type	Required	Description
adlsGen2	AdlsGen2	false	An object containing the properties of the target ADLS Gen2 data source.
azureBlobStorage	AzureBlobStorage	false	An object containing the properties of the target Azure Blob Storage data source.
amazonS3	AmazonS3	false	An object containing the properties of the target Amazon S3 data source.
dataverse	Dataverse	false	An object containing the properties of the target Dataverse data source.
oneDriveSharePoint	OneDriveSharePoint	false	An object containing the properties of the target OneDrive for Business and SharePoint Online data source.
googleCloudStorage	GoogleCloudStorage	false	An object containing the properties of the target Google Cloud Storage data source.
oneLake	OneLake	false	An object containing the properties of the target OneLake data source.
s3Compatible	S3Compatible	false	An object containing the properties of the target S3 compatible data source.
type	Type	true	The type object contains properties like target shortcut account type. Additional types may be added over time.

Type (Enum)

The type object contains properties like target shortcut account type. Additional types may be added over time.

Value	Description
OneLake	OneLake
AmazonS3	AmazonS3
AdlsGen2	AdlsGen2
GoogleCloudStorage	GoogleCloudStorage
S3Compatible	S3Compatible
Dataverse	Dataverse
AzureBlobStorage	AzureBlobStorage
OneDriveSharePoint	OneDriveSharePoint

OneLake

An object containing the properties of the target OneLake data source.

Name	Type	Required	Description
itemId	string (uuid)	true	The ID of the target in OneLake. The target can be an item of Lakehouse, KQLDatabase, or Warehouse. For self-references to the current lakehouse being created/updated, use empty GUIDs. Empty GUIDs are mapped to the current lakehouse during creation/updates.
path	string	true	A string representing the full path to the target folder within the Item. This path should be relative to the root of the OneLake directory structure. For example: "Tables/myTablesFolder/someTableSubFolder".
workspaceId	string (uuid)	true	The ID of the target workspace. For referring to the current workspace, use empty GUIDs. Empty GUIDs are mapped to the current workspace during creation/updates.

AdlsGen2

An object containing the properties of the target ADLS Gen2 data source.

Name	Type	Required	Description
connectionId	string (uuid)	true	A string representing the connection that is bound with the shortcut. The connectionId is a unique identifier used to establish a connection between the shortcut and the target datasource. To find this connection ID, first create a cloud connection to be used by the shortcut when connecting to the ADLS data location. Open the cloud connection's Settings view and copy the connection ID; this is a GUID.
location	string (uri)	true	Specifies the location of the target ADLS container. The URI must be in the format https://[account-name].dfs.core.windows.net where [account-name] is the name of the target ADLS account.
subpath	string	true	Specifies the container and subfolder within the ADLS account where the target folder is located. Must be of the format [container]/[subfolder] where [container] is the name of the container that holds the files and folders; [subfolder] is the name of the subfolder within the container (optional). For example: /mycontainer/mysubfolder

AzureBlobStorage

An object containing the properties of the target Azure Blob Storage data source.

Name	Type	Required	Description
connectionId	string (uuid)	true	A string representing the connection that is bound with the shortcut. The `connectionId` is a unique identifier used to establish a connection between the shortcut and the target datasource. To find this connection ID, first create a cloud connection to be used by the shortcut when connecting to the Azure Blob Storage data location. Open the cloud connection's settings view and copy the GUID that is the connection ID.
location	string (uri)	true	Specifies the location of the target Azure Blob Storage container. The URI must be in the format `https://[account-name].blob.core.windows.net` where `[account-name]` is the name of the target Azure Blob Storage account.
subpath	string	true	Specifies the container and subfolder within the Azure Blob Storage account where the target folder is located. Must be in the format `[container]/[subfolder]`. `[container]` is the name of the container that holds the files and folders. `[subfolder]` is optional and is the name of the subfolder within the container. Example: `/mycontainer/mysubfolder`.

AmazonS3

An object containing the properties of the target Amazon S3 data source.

Name	Type	Required	Description
connectionId	string (uuid)	true	A string representing the connection that is bound with the shortcut. The connectionId is a unique identifier used to establish a connection between the shortcut and the target datasource. To find this connection ID, first create a cloud connection to be used by the shortcut when connecting to the Amazon S3 data location. Open the cloud connection's Settings view and copy the connection ID; this is a GUID.
location	string (uri)	true	HTTP URL that points to the target bucket in S3. The URL should be in the format https://[bucket-name].s3.[region-code].amazonaws.com, where "bucket-name" is the name of the S3 bucket you want to point to, and "region-code" is the code for the region where the bucket is located. For example: `https://my-s3-bucket.s3.us-west-2.amazonaws.com`
subpath	string	true	Specifies a target folder or subfolder within the S3 bucket.

Dataverse

An object containing the properties of the target Dataverse data source.

Name	Type	Required	Description
connectionId	string (uuid)	true	A string representing the connection that is bound with the shortcut. The connectionId is a unique identifier used to establish a connection between the shortcut and the target datasource. To find this connection ID, first create a cloud connection to be used by the shortcut when connecting to the Dataverse data location. Open the cloud connection's Settings view and copy the connection ID; this is a GUID.
deltaLakeFolder	string	true	Specifies the DeltaLake folder path where the target data is stored.
environmentDomain	string (uri)	true	URI that indicates the Dataverse target environment's domain name. The URI should be formatted as `https://[orgname].crm[xx].dynamics.com`, where `[orgname]` represents the name of your Dataverse organization.
tableName	string	true	Specifies the name of the target table in Dataverse.

S3Compatible

An object containing the properties of the target S3 compatible data source.

Name	Type	Required	Description
bucket	string	true	Specifies the target bucket within the S3 compatible location.
connectionId	string (uuid)	true	A string representing the connection that is bound with the shortcut. The connectionId is a unique identifier used to establish a connection between the shortcut and the target datasource.
location	string (uri)	true	HTTP URL of the S3 compatible endpoint. This endpoint must be able to receive ListBuckets S3 API calls. The URL must be in the non-bucket specific format; no bucket should be specified here. For example: `https://s3endpoint.contoso.com`
subpath	string	true	Specifies a target folder or subfolder within the S3 compatible bucket. For example: `/folder`

OneDriveSharePoint

An object containing the properties of the target OneDrive for Business or SharePoint Online data source.

Name	Type	Required	Description
connectionId	string (uuid)	true	A string representing the connection that is bound with the shortcut. The `connectionId` is a unique identifier used to establish a connection between the shortcut and the target datasource. To find this connection ID, first create a cloud connection to be used by the shortcut when connecting to the OneDrive SharePoint data location. Open the cloud connection's settings view and copy the GUID that is the connection ID.
location	string (uri)	true	Specifies the location of the target OneDrive SharePoint container. The URI must be in the format `https://microsoft.sharepoint.com` which is the path of the target OneDrive SharePoint account.
subpath	string	true	Specifies the container and subfolder within the OneDrive SharePoint account where the target folder is located. Must be in the format `[container]/[subfolder]`. `[container]` is the name of the container that holds the files and folders. `[subfolder]` is optional and is the name of the subfolder within the container. Example: `/mycontainer/mysubfolder`.
updateFabricItemSensitivity	boolean	false	Specifies whether the user wants the Fabric item sensitivity to be consistent with site-level labels for SharePoint shortcuts. If the user sets it to `true`, and if a SharePoint site has a more restrictive label than the Fabric item, then only the label of the Fabric item will be updated to match the SharePoint site.

DataAccessRole

Name	Type	Description
decisionRules	DecisionRule[]	The array of permission rules that make up the data access role.
id	string (uuid)	The unique id for the data access role.
members	Members	The members object which contains the members of the role as arrays of different member types.
name	string	The name of the data access role.

DecisionRule

Specifies a rule for matching the requested action. Contains effect (Permit) and permission which determine whether a user or entity is authorized to perform a specific action on a resource.

Name	Type	Description
constraints	Constraints	Any constraints such as row or column level security that are applied to tables as part of this role.
effect	Effect	The effect that a role has on access to the data resource. Currently the only supported value is `Permit`.
permission	PermissionScope[]	The `permission` property is an array that specifies the scope and level of access for a requested action. The array must contain exactly two PermissionScope objects: `Path` and `Action`.

PermissionScope

Defines a set of attributes that determine the scope and level of access to a resource.

Name	Type	Description
attributeName	AttributeName	Specifies the name of the attribute that is being evaluated for access permissions (Path or Action).
attributeValueIncludedIn	string[]	Specifies a list of values for the `attributeName` to define the scope and the level of access to a resource.

Constraints

Any constraints such as row or column level security that are applied to tables as part of this role.

Name	Type	Description
columns	ColumnConstraint[]	The array of column constraints applied to one or more tables in the data access role.
rows	RowConstraint[]	The array of row constraints applied to one or more tables in the data access role.

ColumnConstraint

Indicates a constraint that determines the permissions and visibility a user has on columns within a table.

Name	Type	Description
columnAction	ColumnAction[]	The array of actions applied to the columnNames. The allowed value is `Read`.
columnEffect	ColumnEffect	The effect given to the columnNames. The only allowed value is `Permit`.
columnNames	string[]	An array of case sensitive column names. Use `*` to indicate all columns in the table.
tablePath	string	A relative file path specifying which table the column constraint applies to (e.g. `/Tables/{optionalSchema}/{tableName}`).

RowConstraint

Indicates a constraint that determines the rows in a table that users can see. Roles defined with RowConstraints use T-SQL to define a predicate that filters data in a table.

Name	Type	Description
tablePath	string	A relative file path specifying which table the row constraint applies to.
value	string	A T-SQL expression that is used to evaluate which rows the role members can see.

Members

The members object which contains the members of the role as arrays of different member types.

In addition to FabricItemMembers, Onelake security supports adding a list of MicrosoftEntraMembers. This is not supported in lakehouse item definition APIs, and lakehouse CICD and will be ignored if specified.

Name	Type	Description
fabricItemMembers	FabricItemMember[]	A list of members who have a certain permission set in Microsoft Fabric.

FabricItemMember

Name	Type	Description
itemAccess	ItemAccess[]	A list specifying the access permissions for Fabric users to be automatically included in the role members.
sourcePath	string	The path to the Fabric item having the specified item access (format: `{workspaceId}/{itemId}`). This is always referencing the same lakehouse and only supports empty GUIDs (00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000)

Enumerations

AttributeName

Value	Description
Path	Attribute name Path
Action	Attribute name Action

ColumnAction

Value	Description
Read	The ColumnAction value Read

ColumnEffect

Value	Description
Permit	The ColumnEffect type Permit

Effect

Value	Description
Permit	The effect type Permit

ALMSettings

Describes the object type settings for Lakehouse Deployment pipelines and git operations. This can be used to enable or disable git integration for object types.

Name	Type	Required	Description
version	String	true	The ALM settings version (Only supported version is "1.0.1").
objectTypes	Object[]	true	A list of object types controlled by ALM settings. Each entry contains a `name`, `state`, and optional `subObjectTypes`.

ObjectType

Object types that can be tracked for ALM Operations.

Name	Type	Required	Description
name	String	true	The object type name. Currently supported object types are `Shortcuts`, `DataAccessRoles`. `Shortcuts` are enabled by default and `DataAccessRoles` are disabled by default.
state	String	true	The enabled state for the object type (`Enabled` or `Disabled`).
subObjectTypes	Object[]	false	Optional list of sub-object types with their own `name` and `state`. Only supported for `Shortcuts`

SubObjectType

Sub object types that can be tracked for ALM operations. Supported for Shortcuts object type.

Name	Type	Required	Description
name	String	true	The sub-object type name (for example: `Shortcuts.OneLake`). See example for full list of supported values.
state	String	true	The enabled state for the sub-object type (`Enabled` or `Disabled`).

LakehouseMetadata Example

{
  "defaultSchema": "dbo"
}

Shortcuts Example

[
  {
      "name": "TestShortcut",
      "path": "/Tables/dbo",
      "target": {
        "type": "OneLake",
        "oneLake": {
          "path": "Tables/dbo/publicholidays",
          "itemId": "00000000-0000-0000-0000-000000000000",
          "workspaceId": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
]

DataAccessRoles Example

[
    {
        "name": "dimensionrulerename",
        "kind": "Policy",
        "decisionRules": [
          {
            "effect": "Permit",
            "permission": [
              {
                "attributeName": "Path",
                "attributeValueIncludedIn": [
                  "/Tables/dbo/dimension_city",
                  "/Tables/dbo/dimension_customer",
                  "/Tables/dbo/dimension_date",
                  "/Tables/dbo/dimension_employee",
                  "/Tables/dbo/dimension_stock_item",
                  "/Tables/bronze"
                ]
              },
              {
                "attributeName": "Action",
                "attributeValueIncludedIn": [
                  "Read"
                ]
              }
            ],
            "constraints": {}
          }
        ],
        "members": {
          "fabricItemMembers": [],
            "microsoftEntraMembers": [
            {
              "tenantId": "1e85000e-ee35-4112-bd46-2f00b3d94154",
              "objectId": "5f3efd37-a6d2-432f-99fa-6adc2848a40a"
            }
          ]
        }
      },
      {
        "name": "DefaultReader",
        "kind": "Policy",
        "decisionRules": [
          {
            "effect": "Permit",
            "permission": [
              {
                "attributeName": "Action",
                "attributeValueIncludedIn": [
                  "Read"
                ]
              },
              {
                "attributeName": "Path",
                "attributeValueIncludedIn": [
                  "*"
                ]
              }
            ]
          }
        ],
        "members": {
          "fabricItemMembers": [
            {
              "itemAccess": [
                "ReadAll"
              ],
              "sourcePath": "00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000"
            }
          ]
        }
      }
    ]

ALMSettings Example

{
  "version": "1.0.1",
  "objectTypes": [
    {
      "name": "Shortcuts",
      "state": "Enabled",
      "subObjectTypes": [
        {
          "name": "Shortcuts.OneLake",
          "state": "Enabled"
        },
        {
          "name": "Shortcuts.AdlsGen2",
          "state": "Enabled"
        },
        {
          "name": "Shortcuts.Dataverse",
          "state": "Enabled"
        },
        {
          "name": "Shortcuts.AmazonS3",
          "state": "Enabled"
        },
        {
          "name": "Shortcuts.S3Compatible",
          "state": "Enabled"
        },
        {
          "name": "Shortcuts.GoogleCloudStorage",
          "state": "Enabled"
        }
      ]
    },
    {
      "name": "DataAccessRoles",
      "state": "Enabled"
    }
  ]
}

Last updated on 2026-03-30

Share via