[DBX-6933] Feat: Support custom metadata element

.github/PULL_REQUEST_TEMPLATE.md

@@ -17,6 +17,7 @@
 Please check directly on the box once each of these are done
 
 - [ ] Documentation (if necessary)
+- [ ] Updated `dbml-homepage/static/llms.txt` (if docs/features changed)
 - [ ] Lint Checks Passed
 - [ ] Unit Tests Passed
 - [ ] Coverage Tests Passed

.github/workflows/lint.yml

@@ -14,12 +14,20 @@ jobs:
         node-version: [22.x]
     steps:
     - uses: actions/checkout@v3
+      with:
+        # We need to fetch all history to include the master branch, which is used to run git diff
+        # https://github.com/actions/checkout?tab=readme-ov-file#fetch-all-history-for-all-tags-and-branches
+        fetch-depth: 0
     - name: Use Node.js ${{ matrix.node-version }}
       uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
         cache: 'yarn'
     - name: Install dependencies
       run: yarn install --frozen-lockfile
+    - name: Set up master ref for git diff
+      # The per-package lint scripts run `git diff ... master`, but the checkout only
+      # provides the remote-tracking ref origin/master, not a local `master` branch.
+      run: git branch --force master origin/master
     - name: Lint
       run: yarn lint

dbml-homepage/docs/docs.md

@@ -78,6 +78,8 @@ Table schema_name.table_name {
 - `column_name` can be stated in just plain text, or wrapped in a `double quote as "column name"`
 - `note: 'string to add notes'`: add a metadata note to this table *(enrichment & visualization only — see [Table Notes](./syntax/enrichment-visualization.md#table-notes))*
 
+We also support free-form custom metadata, e.g. `Table users [owner: "data-team"]`. See [Inline Metadata](./syntax/enrichment-visualization.md#inline-metadata).
+
 :::tip
 Use [TablePartial](#tablepartial) to reuse common fields, settings and indexes across multiple tables. Inject partials into a table using the `~partial_name` syntax.
 :::
@@ -118,6 +120,8 @@ The list of column settings you can use:
 - ``check: `check expression`‎``: add a check expression to this column using a backtick expression. Multiple checks can be defined on a column. For checks involving multiple columns, refer to the [Check Definition](#check-definition) section
 - `note: 'string to add notes'`: add a metadata note to this column *(enrichment & visualization only — see [Column Notes](./syntax/enrichment-visualization.md#column-notes))*
 
+We also support free-form custom metadata, e.g. `email varchar [classification: "confidential"]`. See [Inline Metadata](./syntax/enrichment-visualization.md#inline-metadata).
+
 **Note:** You can use a workaround for un-supported settings by adding the setting name into the column type name, such as `id "bigint unsigned" [pk]`
 
 ### Default Value

dbml-homepage/docs/syntax/enrichment-visualization.md

@@ -12,6 +12,10 @@ This part covers features specific to diagram & wiki tools like [dbdiagram.io](h
   - [Column Notes](#column-notes)
   - [Index Notes](#index-notes)
   - [TableGroup Notes](#tablegroup-notes)
+- [Custom Metadata](#custom-metadata)
+  - [Inline Metadata](#inline-metadata)
+  - [Metadata Block](#metadata-block)
+  - [Metadata Precedence](#metadata-precedence)
 - [Sticky Notes](#sticky-notes)
 - [TableGroup](#tablegroup)
   - [TableGroup Notes](#tablegroup-notes-1)
@@ -109,6 +113,104 @@ TableGroup e_commerce [note: 'Contains tables that are related to e-commerce sys
 }
 ```
 
+## Custom Metadata
+
+Custom metadata lets you attach arbitrary, free-form key-value annotations to DBML elements - things like a data-classification tag, an SLA, or any other attribute.
+
+Custom metadata is currently supported on [Table](../docs.md#table-definition), [Column](../docs.md#column-definition), [TableGroup](#tablegroup), and [Sticky Notes](#sticky-notes) (as well as columns inside a [TablePartial](../docs.md#tablepartial) using inline syntax).
+
+There are two ways to declare custom metadata: **inline** in the element's settings list, or in a separate **Metadata block**.
+
+Currently, a metadata value can be a **string literal** (e.g. `owner: "data-team"`) or a **color literal** (e.g. `brand_color: #3498DB`).
+
+### Inline Metadata
+
+Add custom key-value pairs directly to an element's `[...]` settings list.
+
+```text
+Table users [owner: "data-team", sla_hours: "24", pii: "true"] {
+  id int [pk, masking: "partial"]
+  email varchar [classification: "confidential"]
+}
+
+TableGroup e_commerce [team: "growth"] {
+  merchants
+  countries
+}
+
+Note reminder [author: "docs"] {
+  'Remember to review this schema'
+}
+```
+
+:::note
+A key with no value (`[owner]`) or a duplicate key (`[owner: "a", owner: "b"]`) will raise an error.
+:::
+
+### Metadata Block
+
+You can also declare metadata separately from the element definition using a `Metadata` block. This is useful for keeping annotations in a dedicated section, or for adding metadata to elements defined elsewhere (including across files).
+
+The block targets an element by kind and name:
+
+```text
+Table users {
+  id int [pk]
+  name varchar
+}
+
+TableGroup g1 {
+  users
+}
+
+Metadata Table users {
+  owner: 'scott'
+  note: 'scott is the owner'
+}
+
+Metadata Column users.id {
+  pii: 'true'
+  masking: 'partial'
+}
+```
+
+### Metadata Precedence
+
+An element can get metadata from its **inline settings** and from one or more **Metadata blocks**. When the same key is set in more than one place, the higher-priority source wins.
+
+Priority, lowest to highest:
+
+1. Inline settings
+2. Metadata blocks in imported files
+    - Files imported later have higher priority
+3. Metadata blocks in the current file
+    - Blocks defined later have higher priority
+
+When two imported files set the same key, the one imported **later** wins.
+
+**Example**
+
+Two files set `owner` on the same table, and `main.dbml` imports both:
+
+```text
+// schema.dbml
+Table users [owner: 'jane'] {   // inline setting
+  id int [pk]
+}
+Metadata Table users {          // beats inline -> 'david'
+  owner: 'david'
+}
+
+// team.dbml
+use * from 'schema'
+Metadata Table users {          // beats imported block -> 'alice'
+  owner: 'alice'
+}
+
+// main.dbml
+use * from 'team'
+```
+
 ## Sticky Notes
 
 You can add sticky notes to the diagram canvas to serve as a quick reminder or to elaborate on a complex idea.
@@ -132,6 +234,8 @@ Note multiple_lines_note {
 }
 ```
 
+We also support free-form custom metadata, e.g. `Note reminder [author: "docs"] { 'text' }`. See [Inline Metadata](#inline-metadata).
+
 ## TableGroup
 
 `TableGroup` allows users to group the related or associated tables together.
@@ -172,6 +276,8 @@ The list of table group settings you can use:
 - `note: 'string to add notes'`: add a note to this table group.
 - `color: <color_code>`: change the table group color. See [Colors](#colors) for accepted color formats.
 
+We also support free-form custom metadata, e.g. `TableGroup e_commerce [team: "growth"]`. See [Inline Metadata](#inline-metadata).
+
 ## DiagramView
 
 `DiagramView` allows users to define multiple views of a database diagram, each focusing on different tables, notes, table groups, or schemas.

dbml-homepage/static/llms.txt

@@ -8,7 +8,7 @@ For the dbdiagram.io web app (diagrams, collaboration, API), see [dbdiagram docs
 
 - [Home](https://dbml.dbdiagram.io/home): Overview, ecosystem, and links to tools.
 - [Core database markup](https://dbml.dbdiagram.io/docs): Tables, columns, relationships (including optional refs and inactive refs), indexes, enums, records (sample data), and other core syntax.
-- [Enrichment and visualization](https://dbml.dbdiagram.io/syntax/enrichment-visualization): Notes, labels, colors, sticky notes, and display-oriented syntax like table groups, diagram views.
+- [Enrichment and visualization](https://dbml.dbdiagram.io/syntax/enrichment-visualization): Notes, custom metadata (inline settings and `Metadata` blocks), labels, colors, and display-oriented syntax like table groups, diagram views.
 - [Language basics](https://dbml.dbdiagram.io/syntax/language-basics): Core language constructs (strings, comments, and syntax conventions).
 - [Module system](https://dbml.dbdiagram.io/syntax/module-system): Multi-file projects, use declarations, and import/export.
 

dbml-playground/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dbml/playground",
-  "version": "9.0.0",
+  "version": "9.1.0-alpha.0",
   "description": "Interactive playground for debugging and visualizing the DBML parser pipeline",
   "author": "Holistics <dev@holistics.io>",
   "license": "Apache-2.0",
@@ -20,13 +20,14 @@
     "build": "vue-tsc --noEmit && vite build",
     "preview": "vite preview",
     "type-check": "vue-tsc --noEmit",
-    "lint": "eslint .",
+    "lint": "eslint $(git diff --relative --name-only --diff-filter=ACMRTUXB master -- . | grep -E '\\.(js|ts|vue)$')",
+    "lint:all": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write src/"
   },
   "dependencies": {
-    "@dbml/core": "^9.0.0",
-    "@dbml/parse": "^9.0.0",
+    "@dbml/core": "^9.1.0-alpha.0",
+    "@dbml/parse": "^9.1.0-alpha.0",
     "@phosphor-icons/vue": "^2.2.0",
     "floating-vue": "^5.2.2",
     "lodash-es": "^4.17.21",