Publish one trustworthy route to your Mac app updates

Publisher setup

Serve the document as JSON over HTTPS from the vendor origin at this exact path:

https://vendor.example/.well-known/floodtide-app-updates

The origin must come from an explicit developer declaration or a curated mapping. Clients must not reverse or derive a domain from the app's bundle identifier. A reverse-DNS identifier describes an application identity, not an authorised web host.

Start from the version 1 example and validate the finished document against the JSON Schema. Version 1 accepts one to 500 applications and rejects unknown properties so a typo cannot quietly change the meaning of update metadata.

JSON Schema covers the document shape and field syntax. Publishers must also run the Floodtide validator: it enforces semantic rules JSON Schema cannot express here, including case-insensitive uniqueness of bundle identifiers. Both reject blank values, credential-bearing URLs, and timestamps that are not RFC 3339. Only the validator rejects a well-formed date that never happened, such as 31 February, because a regular expression cannot count the days in a month and format is an annotation rather than an assertion in the 2020-12 dialect.

Application entries

Every entry declares:

• bundleIdentifier: the app's exact reverse-DNS bundle ID.
• name: its display name.
• status: active, maintenance, or discontinued.
• homepage: the developer's HTTPS homepage.
• repository: an optional HTTPS source repository.
• update: required unless the app is discontinued.

A discontinued entry omits update. This lets a publisher say the app is no longer maintained without leaving clients to interpret a dead URL as a temporary outage.

Choose exactly one update mechanism

Sparkle

"update": { "sparkle": "https://vendor.example/appcast.xml" }

Use the app's HTTPS Sparkle appcast. Its existing signatures remain authoritative.

GitHub Releases

"update": { "github": "https://github.com/vendor/application" }

Name the HTTPS GitHub repository that publishes releases. A profile, organisation, or bare github.com URL is not a repository and is rejected.

Inline release

"update": {
  "release": {
    "version": "2.1.0",
    "downloadURL": "https://downloads.vendor.example/App-2.1.0.dmg",
    "architectures": ["universal"],
    "sha256": "<64 lowercase hexadecimal characters>"
  }
}

An inline release may also carry a build number, release-notes URL, publication time, minimum macOS version, and supported architectures. Cross-origin downloads are allowed for CDNs, but the application identity still has to match exactly.

Discovery is not install permission

A valid manifest only says where update information can be found. Clients must retain their normal code-signature and Gatekeeper checks, reject downgrades, enforce macOS and architecture requirements, and stop for signing-identity changes. A checksum detects a changed download; it does not authorise a different developer to replace an app.

Clients must ignore entries whose bundle identifier does not exactly match the installed app. They must also stop on an unknown schemaVersion instead of guessing what new fields mean. Every manifest and metadata URL must use HTTPS.

Validate locally

From the Floodtide website source tree, run:

npm run validate:update-manifest -- ./floodtide-app-updates.json

The validator has no runtime dependencies and reports each invalid field without a stack trace. Passing it proves conformance to this draft, not IANA registration or automatic support in Floodtide.

Why a project-specific name?

RFC 8615 defines the well-known URI mechanism and its registration process. The project-specific name avoids claiming a generic namespace before the draft has implementation experience. If the format proves useful beyond Floodtide, registration can follow the RFC process with a stable specification and reviewed interoperability and security requirements.