What the Apple App Site Association Validator does
This validator checks an apple-app-site-association (AASA) file for iOS Universal Links, shared web credentials and App Clips. It validates the JSON structure, app IDs, components and legacy paths, flags rules that can never be reached, tests URLs against the rules to show which open your app, and, given a domain, fetches the file to check its status, content type, redirects and size.
Apple's own tooling tells you little when Universal Links fail: the link just opens Safari. The usual causes are a wrong Team ID prefix, an exclusion placed after a rule that already matched, and a redirect or error on the file's URL - all of which show up here.
How to use it
- Enter a domain and choose Fetch to read https://domain/.well-known/apple-app-site-association through a2z.tools' public fetcher, or paste the file.
- Add the URLs you expect to open the app, and some that should not, one per line.
- Choose Validate. Problems come first, then warnings and notes.
- Read the URL table: for each URL, whether it opens the app, which app IDs claim it, and which rule decided.
Reading the results
Problems are things that stop links working: invalid JSON, an app ID without a valid 10-character Team ID prefix, a non-boolean exclude, a component with no rules, a redirect, or a file over Apple's 128 KB limit.
"Unreachable exclusion" means an exclude component sits after a catch-all rule. Apple checks components in order and stops at the first match, so the exclusion never applies.
The URL tester follows Apple's documented matching: * for any run of characters, ? for exactly one, case-sensitive and percent-encoded by default, with applinks.defaults honoured. It is a faithful model, not the device itself; confirm on a device before release.
Worked example: a file with three classic mistakes
The "common mistakes" example has applinks.apps set to ["com.example.shop"], an app ID written in lower case as abcde12345.com.example.shop, and components that include "*" before excluding /account/* with exclude written as the string "true".
The validator reports the app ID as invalid - Team IDs are upper-case letters and digits - flags exclude as needing a real boolean, flags the exclusion as unreachable behind the catch-all, and warns that applinks.apps must be an empty array when it is present at all.
Testing https://example.com/account/orders against that file shows it opening the app through the first component, which is exactly the behaviour the author was trying to prevent.
Limitations: what the result does not prove
- It checks one fetch from a2z.tools' server. Devices actually download the file through Apple's CDN, which caches it, so a fixed file can take time to reach devices.
- The fetcher reads only text content types. If the server sends application/octet-stream, the page says so and you can paste the file to check the contents.
- It cannot check the other half - the Associated Domains entitlement in your signed app. Inspect it with the IPA Property List Viewer or in Xcode.
Privacy: where your data goes
The analysis runs in your browser. If you choose to load a public URL instead of pasting, a2z.tools fetches that address read-only and returns the text to your tab; private and internal addresses are refused and nothing is stored. Session recording and tag-manager scripts are switched off on this page.
Standards and sources
- Apple Developer - Supporting associated domains - checked 19 Sep 2026
- Apple Developer - applinks
- Apple Developer - Allowing apps and websites to link to your content
Frequently asked questions
Why do my Universal Links open Safari instead of the app?
Common causes are a wrong Team ID in the app ID, the file not being at /.well-known/apple-app-site-association, a redirect or non-200 response, no rule matching the path, an exclusion that matched first, or the entitlement missing the domain. Apple's CDN cache can also delay a fix.
Does the AASA file need the .json extension?
No, it must not have one. The file is named apple-app-site-association with no extension and served from the /.well-known/ directory over HTTPS, without redirects.
What content type should the AASA file use?
Apple documents application/json. Many servers default to application/octet-stream for a file without an extension, so set the type explicitly for that path.
What is the size limit for apple-app-site-association?
Apple's documentation gives 128 KB uncompressed. Large files usually mean many individual paths; replace them with patterns and a few exclusions.
Is the applinks.apps key still needed?
Only for iOS 12 and earlier, and it must be an empty array. Modern files can leave it out; a non-empty value is a mistake the validator warns about.
How does the URL tester decide?
It applies each details entry's components in order: the path pattern, the query pattern or dictionary, and the fragment. The first component that matches decides, and exclude keeps the link in the browser. Legacy paths with NOT prefixes are handled the same way.
Last reviewed by the A2Z.Tools team against the sources listed above.
