AASA validator — find out why your Universal Links won't open the app

paste your domain. find out why your Universal Links won't open the app.

what this tool does

Takes a domain, fetches https://{domain}/.well-known/apple-app-site-association (and the legacy https://{domain}/apple-app-site-association), and validates the file against Apple's specification. Reports: HTTP status, Content-Type header, file size, presence of redirects (Apple's CDN does not follow them), JSON parse status, top-level structure (applinks, webcredentials, appclips), per-app-ID structure, path-matcher syntax, and the specific Apple-platform-version compatibility quirks (the iOS 13+ vs pre-13 path-pattern divergence, the iOS 14+ defaults change for appIDs array, the iOS 16+ exclusion-pattern parsing change). Outputs a pass/fail with annotated errors next to the lines that produced them.

Validation runs against the canonical Apple spec and against the live behavior of Apple's CDN — which does not always match the spec.

why this matters

Apple's Universal Links are the only iOS mechanism that opens your app from a tap on a regular https:// URL without first showing the user a confirmation dialog or a Safari intermediate page. They are the difference between a one-tap user experience and a three-tap drop-off. They depend entirely on Apple's CDN successfully fetching and parsing your apple-app-site-association file. When that fails — and it fails silently — your Universal Links degrade to plain web URLs. Your app never opens. Nobody tells you. The only signal is conversion dropping.

The failure modes are mostly stupid. The file is served with Content-Type: text/html instead of application/json (Apache's default for files without an extension, and AASA files have no extension by design). The file is behind a redirect (Apple does not follow them; it sees a 301 and gives up). The JSON has a trailing comma (valid in many JSON parsers, invalid in Apple's). The path patterns use /foo* when iOS 13+ expects /foo/* and pre-13 expects the older format. The app's Associated Domains entitlement claims the wrong domain. The file is correct on www.example.com but the entitlement claims example.com. Etc.

Each of these is a one-line fix once you know which one is broken. The hard part is figuring out which one. Apple's diagnostic surface is approximately zero — the Console.app logs on a paired iPhone show some, but not all, of these failures, and most are buried under irrelevant noise.

The validator exists to surface the failure in one second. Paste domain. Read the failed assertion. Fix the file. Move on.

For the deeper context — what AASA actually is, how Universal Links resolve, what the iOS version differences mean — see /guides/aasa-file-explained and /guides/ios-universal-links-setup.

what you'll see

1. Domain input. Enter a domain (without https://). Single field, single Validate button.

2. Fetch result. First block of output: did the file fetch successfully? Status code. Final URL after any redirects. Content-Type. File size. Time to first byte.

3. File contents pane. Left side. The AASA file's JSON rendered with syntax highlighting and line numbers.

4. Validation pane. Right side. A list of checks, each marked PASS or FAIL or WARN, with the failing checks annotated against specific line numbers in the file pane.

   Sample output rows:

   • PASS: HTTPS scheme
   • PASS: HTTP 200 response
   • FAIL: Content-Type is text/html; expected application/json (line: HTTP headers)
   • PASS: JSON parses
   • WARN: trailing whitespace in applinks.details[0].paths[2]
   • FAIL: path pattern /profile* is invalid in iOS 13+; use /profile/* (line 14)
   • PASS: appID format matches TEAMID.bundle.identifier

5. Fix suggestions. Next to each FAIL, a short remediation: "Configure your web server to send Content-Type: application/json for /.well-known/apple-app-site-association. For nginx: location = /.well-known/apple-app-site-association { default_type application/json; }."

6. Apple CDN cache check. Apple's CDN aggressively caches AASA files. The validator includes a one-click "see what Apple's CDN currently has cached for your domain" lookup, separate from your origin server, so you can tell whether your fix has propagated.

7. Copy result as report button. Generates a shareable URL with the validation result, useful for handing off to a teammate or attaching to a Jira ticket.

who this is for

iOS developers debugging a Universal Link that won't open the app, where the entitlements look correct and the link works in some contexts but not others.

DevOps and SREs setting up the AASA file for the first time, who need a sanity check before announcing the deploy.

QA engineers verifying that a release didn't break the existing Universal Link configuration.

Migration teams moving off Firebase Dynamic Links (deprecated 2025) onto direct Universal Links and needing to verify the replacement AASA setup matches what FDL was managing.

currently in development

We're building this. The validation rules are codified; the work is the Apple-CDN-cache surface and the iOS version-specific behavior matrix.

Notify me when this validator launches — built by engineers, for engineers.

Get notified →

in the meantime

If you need to validate today:

• Apple's documentation is the canonical reference: developer.apple.com/documentation/xcode/supporting-associated-domains{rel="nofollow"}. Skim the "Edit the associated domain file" and "Allow apps and websites to link to your content" sections.
• swcutil on macOS is the underground tool. From a terminal on a Mac with Xcode installed, run swcutil verify -d yourdomain.com — this hits Apple's CDN with the same query an iPhone would, surfaces the cache state, and reports parse failures. It's the closest thing to a first-party validator that exists.
• Branch's AASA validator (branch.io has a public one at branch.io/resources/aasa-validator/) covers the common errors and is currently the most-used third-party tool. Open Branch's validator{rel="nofollow"} — third-party, not affiliated with linkboo.
• Manual: curl -I https://yourdomain.com/.well-known/apple-app-site-association confirms the Content-Type and the absence of redirects. curl https://yourdomain.com/.well-known/apple-app-site-association | jq . confirms valid JSON.

related

Continue reading:

• AASA file explained
• iOS Universal Links setup
• Universal Links vs deep links
• Firebase Dynamic Links replacement

Sister tool:

• Assetlinks validator — Android equivalent

Related tools:

• Deeplink tester — once your AASA is valid, test the end-to-end behavior
• User-agent checker

Developer reference:

• /api — linkboo's deeplink API
• /docs — integration documentation