Add jsonschema formula (Linux + macOS) and deprecate cask by cavanaug · Pull Request #5 · sourcemeta/homebrew-apps

cavanaug · 2026-03-12T17:45:51Z

Summary

This PR adds a Homebrew formula for jsonschema that works on both Linux and macOS, and deprecates the existing macOS-only cask in favour of it.

Note: This PR was authored by an AI agent (Claude, via OpenCode) acting on behalf of @cavanaug.

Motivation

The existing Casks/jsonschema.rb only works on macOS. Linux users attempting brew install sourcemeta/apps/jsonschema get a cask-not-supported error with no fallback. Issue: sourcemeta/jsonschema#683

Changes

`Formula/jsonschema.rb` (new)

Covers all four platform/arch combinations: darwin-arm64, darwin-x86_64, linux-arm64, linux-x86_64
Installs binary, bash completion, and zsh completion
Includes a post_install block that detects a lingering Caskroom installation and prints explicit migration commands
Passes brew install, brew test, brew audit --strict, brew style, and a functional smoke test on Linux

`Casks/jsonschema.rb` (updated)

Adds deprecate! stanza so existing cask users see an actionable warning at brew upgrade time:

Warning: Cask jsonschema is deprecated because it moved to a formula;
uninstall with: brew uninstall --cask jsonschema

Fixes pre-existing style violations (stanza order, stanza grouping, article in desc, trailing whitespace) caught by brew style

Migration path for existing cask users

Touchpoint	What the user sees
`brew upgrade`	Deprecation warning with explicit uninstall command
`brew install sourcemeta/apps/jsonschema` (while cask present)	`post_install` warning with full two-step migration instructions
Fresh install (no cask)	Works as normal, formula resolves automatically

Testing

Tested on Linux x86_64:

brew install cavanaug/apps/jsonschema   ✅
brew test cavanaug/apps/jsonschema      ✅
brew audit --strict cavanaug/apps/jsonschema  ✅
brew style cavanaug/apps/jsonschema     ✅ (0 offenses)
jsonschema validate <valid>             ✅ exit 0
jsonschema validate <invalid>           ✅ exit 2 with correct error

Adds a Formula for the jsonschema CLI to replace the existing macOS-only Cask. The Cask uses arm:/intel: sha256 keys which resolve to nil on Linux, causing an immediate install failure. The new Formula uses on_macos/on_linux + on_arm/on_intel blocks (all four combinations) so the install works correctly on both platforms. Closes sourcemeta/jsonschema#683

Homebrew automatically chdirs into the single top-level subdirectory of a zip archive before running the install block. The initial version incorrectly used full subdirectory prefixes (e.g. jsonschema-14.14.2-linux-x86_64/bin/jsonschema) which don't exist relative to that chdir'd location. Also consolidate the four identical install blocks into one shared method at the formula level. Tested: brew install + brew test pass on Linux x86_64.

- Add deprecate! stanza to Casks/jsonschema.rb so existing cask users see a deprecation warning at brew upgrade time (:moved_to_formula) - Add post_install block to Formula/jsonschema.rb that detects a lingering Caskroom/jsonschema installation and prints explicit remediation commands to guide users through the migration - Fix style: strip leading article from desc in both files (brew style) - Fix style: correct stanza ordering and grouping in cask (brew style)

…ation The deprecate! reason now includes an explicit uninstall command so the warning shown at brew upgrade time is immediately actionable. The --formula flag is unnecessary since brew install prefers formulae over casks when both exist in the same tap.

cavanaug · 2026-03-12T17:47:30Z

Upgrade behavior for existing macOS cask users

For users who currently have the cask installed, here is the exact sequence of events after this PR is merged:

`brew upgrade`

Homebrew processes the deprecated cask and prints:

Warning: Cask jsonschema is deprecated because it moved to a formula;
uninstall with: brew uninstall --cask jsonschema

The cask still upgrades normally — deprecate! is a warning, not a blocker. The binary continues to work. The user is now informed and has an explicit command to run.

After the user runs `brew uninstall --cask jsonschema`

The cask is removed. A plain brew install sourcemeta/apps/jsonschema will now resolve to the formula automatically — no --formula flag needed, because Homebrew prefers formulae over casks when both exist in the same tap.

If the user runs `brew install sourcemeta/apps/jsonschema` while the cask is still present

The formula installs successfully alongside the cask (they use different prefixes), and the post_install block fires:

Warning: A Cask installation of jsonschema was detected at /opt/homebrew/Caskroom/jsonschema.
The cask has been superseded by this formula. To complete migration, run:
  brew uninstall --cask sourcemeta/apps/jsonschema
  brew install sourcemeta/apps/jsonschema

Fresh install (no cask ever installed)

brew install sourcemeta/apps/jsonschema resolves to the formula, installs the correct binary for the platform/arch, and exits cleanly. No warnings.

Note: conflicts_with cask: in a formula DSL is purely cosmetic — it is consumed by brew audit only and does not raise an error at install time. The deprecate! stanza on the cask side and the post_install block on the formula side are the only mechanisms that actually fire for users.

Copilot

Pull request overview

This PR introduces a cross-platform Homebrew formula for jsonschema (Linux + macOS) and deprecates the existing macOS-only cask to provide a clearer migration path for users.

Changes:

Added Formula/jsonschema.rb with platform/arch-specific release artifacts plus completion installs.
Deprecated Casks/jsonschema.rb to guide existing cask users toward the new formula.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
`Formula/jsonschema.rb`	New formula installing the `jsonschema` binary and shell completions across macOS/Linux and architectures, with migration guidance.
`Casks/jsonschema.rb`	Deprecates the existing cask and adjusts metadata/style to support migration messaging.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Formula/jsonschema.rb

Casks/jsonschema.rb

- Fix conflicts_with cask: token to use short name 'jsonschema' (not tap-qualified) since the cask lives in the same tap - Update comment above conflicts_with to clarify it is cosmetic-only at runtime; post_install is the actual warning mechanism - Fix post_install message: remove redundant 'brew install' line since the formula is already installed when post_install runs - Fix deprecate! message: use tap-qualified 'sourcemeta/apps/jsonschema' for consistency with the formula messaging, rephrase to fit 118 chars

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

jviotti · 2026-03-13T11:34:13Z

Casks/jsonschema.rb

+  desc "CLI for working with JSON Schema"
  homepage "https://github.com/sourcemeta/jsonschema"
+
+  deprecate! date: "2026-03-11", because: "now a formula; run: brew uninstall --cask sourcemeta/apps/jsonschema"


Seems like this is the only real relevant change. The rest of changes in this file are just noise?

Its trying to provide some comments about what is happening and to hopefully lead the user to the right next step if they encounter a problem.

Yes, I mean the rest of the edits in this file are blank lines getting added, the version field getting re-ordered, etc?

jviotti · 2026-03-13T11:39:58Z

Casks/jsonschema.rb

  zsh_completion "jsonschema-#{version}-darwin-#{arch}/share/zsh/site-functions/_jsonschema"
+
  postflight do
    system_command "xattr", args: ["-c", "#{staged_path}/jsonschema-#{version}-darwin-#{arch}/bin/jsonschema"]


You need this on the formula on macOS, otherwise the systen complains the binary is not code signed

Im definitely mac clueless.

jviotti · 2026-03-13T11:40:17Z

Formula/jsonschema.rb

@@ -0,0 +1,58 @@
+class Jsonschema < Formula
+  desc "CLI for working with JSON Schema"


Suggested change

desc "CLI for working with JSON Schema"

desc "The CLI for working with JSON Schema"

Just to match the old one?

Random consistency edit...

Consistency with what? Is this a Homebrew convention?

jviotti · 2026-03-13T11:40:52Z

Formula/jsonschema.rb

+    end
+  end
+
+  # jsonschema was previously distributed as a cask. Note: conflicts_with cask:


I think the conflicts_with line is obvious enough that we can remove this whole comment?

The comment was to highlight this distinction between brew documentation and reality. You would think conflicts_with would have an impact during upgrade/etc, but its been my observation that it is only relevant for brew audit.

I think let's remove the comment. The conflicts_with line, even for a casual reader, is readable enough?

jviotti · 2026-03-13T11:41:15Z

Formula/jsonschema.rb

+  conflicts_with cask: "jsonschema", because: "both install a `jsonschema` binary"
+
+  def install
+    # Homebrew auto-chdirs into the single top-level directory of the zip,


I think this comment can go away too

jviotti · 2026-03-13T11:41:56Z

Formula/jsonschema.rb

+      sha256 "cb8fd293ead5bb68be931d23b81c8d2278d047defb91b27e2d2892704211c198"
+    end
+
+    on_intel do


BTW note that we offer a musl x86 binary. Is there a way to correctly use it on musl systems? Not a blocker, as its more of a bonus thing, but I wonder if it is possible

Im honestly not sure how you specify a musl variant in brew. Brew itself would have to have dependencies on musl libraries being available I think, either that or the OS itself needs to ensure they are there.

jviotti · 2026-03-13T11:43:24Z

Casks/jsonschema.rb

-    
+
    puts ""
    puts "Tip: Try the Sourcemeta Studio VS Code extension for an enhanced experience!"


Can we also keep this little note?

jviotti · 2026-03-13T11:43:52Z

TODO to self: after this PR is merged, might be worth configuring GitHub Actions here so we test the formula builds across Linux and macOS

cavanaug · 2026-03-13T18:44:22Z

So admittedly one the problems I had with this is that I dont have a mac to test it on. Also some of the brew documentation regarding things like conflicts_with doesnt actually match the behavior observed. I tried to simulate the actual experience of going from Cask to Formula by creating a synthetic Linux cask and then switching to formula. But Im honestly not positive that was a faithful representation of reality.

I was trying to coerce brew to tell an existing cask based user effectively what needs to be done if they get a messages about conflicts etc. I didnt want to leave the user in a state where things are conflicted and we didnt tell them exactly how to fix it. Any situation where it looks like things are broken/conflicted and the user has to go google how to fix it, is not the desired experience.

If someone has a mac and can test this directly that would be immensely helpful.

jviotti · 2026-03-17T15:11:35Z

Formula/jsonschema.rb

+    zsh_completion.install "share/zsh/site-functions/_jsonschema"
+  end
+
+  def post_install


Can we add the xattr -c for macOS in this part?

cavanaug added 4 commits March 11, 2026 13:29

Copilot AI review requested due to automatic review settings March 12, 2026 17:45

Copilot started reviewing on behalf of cavanaug March 12, 2026 17:46 View session

Copilot AI reviewed Mar 12, 2026

View reviewed changes

Formula/jsonschema.rb Outdated Show resolved Hide resolved

Formula/jsonschema.rb Show resolved Hide resolved

Casks/jsonschema.rb Outdated Show resolved Hide resolved

cavanaug requested a review from Copilot March 12, 2026 20:17

Copilot started reviewing on behalf of cavanaug March 12, 2026 20:18 View session

Copilot AI reviewed Mar 12, 2026

View reviewed changes

jviotti reviewed Mar 13, 2026

View reviewed changes

jviotti reviewed Mar 17, 2026

View reviewed changes

		@@ -0,0 +1,58 @@
		class Jsonschema < Formula
		desc "CLI for working with JSON Schema"

	desc "CLI for working with JSON Schema"
	desc "The CLI for working with JSON Schema"



		puts ""
		puts "Tip: Try the Sourcemeta Studio VS Code extension for an enhanced experience!"

Conversation

cavanaug commented Mar 12, 2026

Summary

Motivation

Changes

Formula/jsonschema.rb (new)

Casks/jsonschema.rb (updated)

Migration path for existing cask users

Testing

Uh oh!

cavanaug commented Mar 12, 2026

Upgrade behavior for existing macOS cask users

brew upgrade

After the user runs brew uninstall --cask jsonschema

If the user runs brew install sourcemeta/apps/jsonschema while the cask is still present

Fresh install (no cask ever installed)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jviotti commented Mar 13, 2026

Uh oh!

cavanaug commented Mar 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

`Formula/jsonschema.rb` (new)

`Casks/jsonschema.rb` (updated)

`brew upgrade`

After the user runs `brew uninstall --cask jsonschema`

If the user runs `brew install sourcemeta/apps/jsonschema` while the cask is still present