Every LookML project that survives more than a year acquires a house style: how views are named, where labels and descriptions are mandatory, whether sql_table_name is allowed to point at a raw schema, which fields must be hidden. The problem has never been agreeing on the rules — it has been enforcing them. Code review catches maybe half the drift, and the half it misses is the half that becomes technical debt.
Until recently the usual answer was a third-party linter such as LAMS, wired into GitHub Actions, as we described in our earlier tutorial on CI for LookML. With Looker 26.18, Looker Continuous Integration gained a built-in Style Validator that enforces LookML coding standards, naming conventions, and structural best practices natively, using a default ruleset or a lkmlstyle.yaml file committed to your project repository. For most teams that removes an entire moving part from the pipeline.
This tutorial covers how we roll it out on client projects.
1. Understand what the Style Validator is (and is not)
Looker already ships three validation surfaces, and they do different jobs:
- LookML Validator — is the project syntactically and referentially valid? Does every
type, join, and field reference resolve? - SQL Validator / Content Validator — does the generated SQL run, and does saved content still reference fields that exist?
- Style Validator — is the project written the way your team agreed to write it?
Only the third one is a matter of opinion, which is exactly why it needs to be written down in a config file rather than argued about in pull requests. The Style Validator does not tell you your model is wrong; it tells you your model is inconsistent.
2. Start with the default ruleset in a dev branch
Before writing any configuration, run the validator with the built-in ruleset from the CI suite against a development branch. On a mature project expect a large number of findings — hundreds is normal for a project nobody has linted before. That first run is a survey, not a to-do list.
Triage the output into three buckets:
- Rules you agree with and already mostly follow — turn these on as errors.
- Rules you agree with but violate widely — turn these on as warnings now, errors later.
- Rules that do not fit your project — disable them, and write down why in a comment so the next developer does not re-enable them on instinct.
3. Commit an lkmlstyle.yaml
The configuration file lives in the project repository alongside manifest.lkml, so it is versioned and reviewed like any other LookML artifact. A realistic starting point for a team that is adopting the validator on an existing project looks roughly like this:
# lkmlstyle.yaml — Vistelio starter config
rules:
# Rules we already honour: fail the build.
view-name-snake-case:
severity: error
measure-must-have-description:
severity: error
explore-must-have-label:
severity: error
# Rules we want, but cannot clear today: warn for one quarter,
# then promote to error (owner: analytics platform team).
dimension-must-have-description:
severity: warning
no-raw-sql-table-name:
severity: warning
# Deliberately off: our embedded models use generated view names
# produced by the provisioning job and cannot be renamed.
view-name-prefix:
enabled: false
exclude:
- "views/generated/**"
- "views/legacy_finance/**"
overrides:
- paths: ["views/core/**"]
rules:
dimension-must-have-description:
severity: error
Three mechanics are doing the work here, and they map to the knobs the Style Validator exposes: severity (how hard a violation bites), exclusions (whole paths the validator should ignore), and path overrides (stricter or looser rules for part of the tree). Rule names and the exact key spelling vary by Looker release — confirm them against the Style Validator documentation for the version your instance is running, and let the validator itself tell you when a key is unrecognised.
The override block is the part teams under-use. A governed views/core/ directory that feeds executive dashboards deserves mandatory descriptions; a staging directory that three analysts iterate on daily does not. One global severity for a whole project is almost always either too loose to matter or too strict to survive.
4. Exclude generated and legacy code, deliberately
Two categories of LookML should usually be excluded rather than fixed:
- Generated views — anything produced by dbt's Looker integration, a provisioning script, or
create_view_from_table. Linting generated code means fighting the generator every time it runs. - Quarantined legacy — the finance model nobody has touched since 2023. Exclude the path, open a ticket, and keep the rest of the project clean. A linter that reports 400 violations on every run gets ignored within a week; a linter that reports three gets fixed.
The exclusion list is a debt register. Review it quarterly and shrink it.
5. Add custom rules for the conventions that are actually yours
The default ruleset encodes general Looker community practice. It cannot know that your organisation requires every measure of type sum to carry a value_format_name, or that every view in views/core/ must declare a primary_key dimension, or that label must never be a copy of the field name. Custom rules in lkmlstyle.yaml are where those conventions go.
Our rule of thumb: if a convention has been raised in code review more than twice, it belongs in the config file rather than in a reviewer's head. Each custom rule should carry a human-readable message that says what to do, not just what is wrong — "Add value_format_name to currency measures (see modeling-standards.md)" beats "measure style violation".
6. Wire it into the Git workflow
The Style Validator earns its keep when it runs automatically against the pull request branch, alongside LookML validation, data tests, and SQL validation. Our standard arrangement:
- On every PR: LookML Validator, Style Validator, and LookML data tests. Errors block the merge; warnings post as comments.
- Nightly on the production branch: SQL Validator and Content Validator, which are slower and warehouse-dependent.
- Advanced Deploy Mode on the production branch, so merging and deploying stay separate decisions.
If you are already running LAMS or Spectacles, keep them until the native rules cover your real conventions; there is no prize for removing a working check early. The migration path we use is: run both in parallel for two or three sprints, move rules into lkmlstyle.yaml as they prove equivalent, then retire the external linter and its credentials.
7. Keep Diagnose & Repair in your back pocket
The same Looker release introduced a Diagnose & Repair tool that checks a project repository across a set of diagnostic tests and can repair common Git-side damage — stale lock files, broken permissions, corrupted object indexes — while preserving uncommitted work on a recovery branch. It is unrelated to style, but it solves the other recurring LookML support ticket: "the IDE says my project is broken and I did not change anything." Reach for it before manually re-cloning a project, and before anyone starts deleting branches by hand.
Rollout checklist
- Run the Style Validator with defaults on a dev branch; capture the baseline count.
- Triage findings into error / warning / disabled.
- Commit
lkmlstyle.yamlwith exclusions for generated and legacy paths. - Add path overrides so governed directories are stricter than staging ones.
- Encode your two or three genuinely local conventions as custom rules.
- Make the validator a required check on pull requests.
- Diary a date to promote warnings to errors and shrink the exclusion list.
Style rules are cheap to agree on and expensive to enforce by hand. Moving them into CI is one of the highest-leverage hours of work available to a LookML team — and now it is an hour spent inside Looker rather than on scaffolding around it.
If you want a second pair of eyes on your LookML standards, or help rolling a validated CI workflow out across several projects, our Looker consultants do this work every week. Get in touch.