--- title: "QBL definition, structure, and syntax" slug: "qbl-definition-structure-and-syntax" updated: 2025-08-19T14:49:55Z published: 2025-08-19T14:49:55Z canonical: "help.quickbase.com/qbl-definition-structure-and-syntax" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.quickbase.com/llms.txt > Use this file to discover all available pages before exploring further. # QBL definition, structure, and syntax ## QBL definition Quickbase language (QBL) is a schema extending YAML that allows you to create textual descriptions of Quickbase apps. QBL is human-readable, text-based, and portable. Note: QBL support for pipelines is expected to be available later this year. The simple, intuitive syntax makes it easy to read and review changes to Quickbase apps. Use your text-based descriptions in SCM tools, just like more traditional software projects. To make the QBL descriptions portable, we’ve conceptualized object identifiers, [logical IDs](/v1/docs/logical-ids). Because Quickbase uses logical IDs, it does not need to include app, table, and other globally unique identifiers in the format. QBL syntax indicates references via logical IDs. This allows relationships and dependencies to be tracked inside of QBL descriptions. When creating or updating apps using QBL, the Quickbase platform translates references and logical IDs into the correct identifiers. ## QBL Structure The [Solutions API](https://developer.quickbase.com/operation/exportSolution) defines solutions in YAML format with the following schema: ```plaintext Version: 0.2 Resources:  $App_Project_Management_App:         ``` - **Version**—This numerical value represents the schema version of the QBL contained in the document. Learn more about [QBL versions](/v1/docs/about-qbl-versions) and [Quickbase's versioning logic](https://semver.org/). - **Resources**—A YAML map. The key is logical IDs. The values are QBL descriptions of applications. ## Syntax QBL is a tree structure where each node has the following syntax: ```plaintext Type: Properties:   ``` Each node is a value in a map, where the key is that node’s logical ID. Here’s an example of an application node: ```plaintext Resources:    $App_Project_Management_App:    Type: QB::Application    Properties:      Name: Project Management App Copy      Tables:             ``` And to extend further with a table: ```plaintext Resources:    TodoApp:        Type: Qb::Application      Properties:            Name: "My Todo List"        Tables:            $Table_Projects:        Type: QB::Table        Properties:          Name: Projects        $Table_Tasks:        Type: QB::Table        Properties:          Name: Tasks ``` The example output shows two tables in the application. In this document, any relationships the Projects table might have with Tasks would be mediated via the logical ID **$Table_Projects**. ### References A `!Ref` tag is used to reference properties in other objects. For example, this tag can be used in table-to-table relationships to reference objects in different tables. The `!Ref` tag specifies the type of object it is referencing and the logical ID: ```plaintext SourceField: !Ref     Field: $Field_My_Field_logical_id  ``` The`!Ref` tag might also specify the scope of the object a property belongs to so that it can identify the correct field. For example, to reference a field in a different app, the QBL also specifies the app and the table that the field belongs to: ```plaintext Properties:    DataField: !Ref      App: $App_MyApp      Table: $Table_MyTable      Field: $Field_My_Field_logical_id  ``` The `!BadRef` tag is exported in QBL in place of a `!Ref` tag when a reference cannot be resolved to a real resource. For example, form rules can reference fields and roles. If those fields or roles are deleted from the table within an app, the form rule definitions are not updated in the table schema. This means in the exported YAML, the form rules will attempt to reference fields and roles that may not exist anymore. `!BadRef` is the way to represent that in the exported YAML and keep the solution valid. When a reference resolves to a valid resource, it is exported as: ```plaintext Value: !Ref Field: $Field_MyField ``` If the reference cannot be resolved, it is exported as: ```plaintext Value: !BadRef "Referenced resource does not exist." ``` ### Formulas and custom data rules Formulas and custom data rules are observed as strings in QBL. For example, a formula URL field may look like: ```plaintext $Field_Add_Task:  Type: QB::Field::URL::Formula  Id: 34  Properties:    Formula: |-    URLRoot() & "db/" & [_DBID_TASKS] & "?act=API_GenAddRecordForm&_fid_48=" & [Record ID#] &"&_fid_8=" & [Est Start Date] &"&z=" & Rurl() ``` QBL does not recognize references to fields and tables as logical IDs. When you update a solution using QBL, make sure there are no differences between the field and table IDs in the origin solution where you exported the QBL and the destination solution that you will use the QBL to update. If there are differences, make the IDs match the IDs in the destination solution. ## Examples: Quickbase UI and QBL representation *Example 1—Quickbase UI* ![quickbase-ui-app-name-and-settings.png](https://cdn.document360.io/dd260e4e-10bb-4b66-8fb3-5504c272b904/Images/Documentation/25114406601876.png) *Example 1—QBL representation* ```plaintext Resources:  $App_Project_Management_App:    Type: QB::Application    Properties:      Name: Project Management App Copy      Description: Start your project management journey with this easy to use starter app!      Manager: rstoycheva@quickbase.com      CurrencySymbol: $ ``` *Example 2—Quickbase UI* ![quickbase-ui-app-access-permissions-tab.png](https://cdn.document360.io/dd260e4e-10bb-4b66-8fb3-5504c272b904/Images/Documentation/25037856279828.png) *Example 2—QBL representation* ```plaintext Resources:    $App_Project_Management_App:    Type: QB::Application    Properties:      Name: Project Management App Copy      Description: Start your project management journey with this easy to use starter app!    Roles:            $Role_Team_Member:        Type: QB::Application::Role        Properties:          Name: Team Member          Description:          Default: true          ManageUsers: true          EditApp: false          DisableAccess: false          AppUI:            HideSettings: false            HideUsers: false            HideFavorites: false            HideSearch: false            HideHelp: false            HideTestAs: false          TableUI:            Global:              HideInBar: false              HideNewRecord: false              HideGridEdit: false              HideEmail: false              HidePrint: false              HideImportExport: false              HideSaveSpreadsheet: false              HideCreateCustomizeReport: false              HidePersonalSettings: false            $Table_Projects:              HideInBar: false              HideNewRecord: false              HideGridEdit: false              HideEmail: false              HidePrint: false              HideImportExport: false              HideSaveSpreadsheet: false            $Table_Tasks:              HideInBar: false              HideNewRecord: false              HideGridEdit: false              HideEmail: false              HidePrint: false              HideImportExport: false              HideSaveSpreadsheet: false ```