AASA Validator

Check your apple-app-site-association file for iOS Universal Links. Free, no signup.

Validate AASA File

Check your Apple App Site Association configuration

Note: You must keep your file in /.well-known/apple-app-site-association path

Validation Results

Results will appear here after validation

Enter a domain above to validate your AASA file

What passes and what fails?

The validator marks five checks Pass or Fail. A file passes when it returns a success status, is served as application/json, parses as valid JSON, and has a top-level applinks object whose details array has at least one entry. The result is Validation Successful only when all five pass; otherwise it names the first failing check.

What does the AASA validator check?

The validator requests the file from your browser and runs five checks in this order. The tool is not tied to Smler: enter any domain and it requests that domain's AASA file, whichever provider hosts it.

1. File Availability

Fetches https://yourdomain.com/.well-known/apple-app-site-association and confirms a success status. A fail means the file is missing, blocked or erroring at that address, and the headline shows the HTTP status received. Publish it in /.well-known/ at the domain root with no login or firewall rule in front of it.

2. Content Type

Confirms the Content-Type header contains application/json. Many static hosts default to text/plain for extensionless files, which can silently break Universal Links even when the JSON is perfect. Set an explicit header rule for that exact path, or set the content type in the object metadata on S3 or CloudFront.

3. Valid JSON Format

Parses the response body. A fail means a syntax error, or that there was no file to parse. Trailing commas, single quotes and stray comments are the usual causes; run the file through a JSON linter.

4. Applinks Configuration

Checks for a top-level applinks object, the section Apple reads for Universal Links. Some older examples show a flat appID/paths pair from a deprecated schema that iOS no longer reads.

5. Details Array

Verifies applinks.details is an array with at least one entry. An empty array, or a typo such as detail, leaves no app associated with the domain.

How do I read the AASA validator results?

A run ends in one of three states. There is no warning state. One failure can cause later ones (a missing file cannot be valid JSON), so fix from the top down.

Validation Successful

All five checks passed and the message reads “AASA file is valid and properly configured”. The file is reachable and well formed; next, test on a real device with our guide on how to test deep links on iOS.

Validation Failed

At least one check failed. The headline names the first failing check, and each row shows its own Pass or Fail. Use the fix listed under that check above, deploy, and run the validator again.

Failed to validate AASA file

“Failed to validate AASA file. Please check the URL and try again.” means the request never completed, so no checks ran. Check the domain for typos and that it serves HTTPS with a valid certificate. A server that refuses your browser's cross-origin request gives the same message; if so, open the file's address in a new tab to read the raw response.

If every check passes and links still open in Safari, the cause is outside the file: see the deep link troubleshooting guide.

Where does the apple-app-site-association file live and what does it contain?

The AASA file is a JSON document that links your website to your iOS app. Apple fetches and caches it, then uses it for iOS Universal Links: tapping a link to your domain opens your app instead of Safari when the app is installed. Without a correctly hosted file, every link opens in Safari. Apple looks for it at one address on each domain:

  1. Exact path: https://yourdomain.com/.well-known/apple-app-site-association, with no .json extension.
  2. HTTPS only: Apple will not fetch the file over plain HTTP.
  3. No redirects: HTTP to HTTPS and apex to www hops both break it.
  4. Correct content type: application/json, not text/plain or text/html.
  5. Under 128 KB: Apple rejects larger files.

The part that matters is the applinks object, and that is the part this validator parses. Inside it, details is an array. Each entry pairs appIDs, the apps allowed to open links, with components, the URL patterns those apps handle. An app ID is your application identifier prefix (in most cases your Team ID), a dot, and the bundle identifier. A separate webcredentials section handles shared password AutoFill and is not checked here.

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app"],
        "components": [
          {
            "/": "/products/*",
            "comment": "Open any URL whose path starts with /products/ in the app."
          },
          {
            "/": "/account/*",
            "exclude": true,
            "comment": "Keep URLs under /account/ in the browser."
          }
        ]
      }
    ]
  }
}

In this example the app ABCDE12345.com.example.app opens every URL under /products/, while /account/ stays in the browser because of exclude. The validator confirms that applinks exists and that details has at least one entry; it does not judge the app IDs or patterns, so compare those with your Xcode project by hand. Android uses a different file: check it with the assetlinks.json checker.

Skip hand-rolling AASA and assetlinks files

Smler hosts and serves your apple-app-site-association and assetlinks.json files for you, kept in sync with your app IDs and certificate fingerprints. Deferred deep linking, short links, and analytics come with the same setup, free up to 25,000 attributed installs a month.

Get Started FreeNo credit card required

Frequently asked questions

What is an apple-app-site-association (AASA) file?

It is a JSON file hosted on your domain that proves you own both the website and the iOS app, so Apple will let taps on your links open the app directly (Universal Links) instead of Safari.

Where does the AASA file need to live, and can it redirect?

At https://yourdomain.com/.well-known/apple-app-site-association, served over HTTPS with no file extension. Apple's documentation asks for no redirects, so an HTTP to HTTPS or apex to www hop on that path can cause validation to fail.

Why does content-type matter if the JSON is valid?

Apple's crawler checks the Content-Type header before parsing the body. If your host serves the file as text/plain or text/html (common on static hosts and some CDNs), iOS can treat the association as absent even though the JSON itself is correct.

Is there a file size limit, and does iOS cache the file?

Apple enforces a 128 KB limit on the AASA file. iOS fetches and caches the file when the app is installed or updated, so re-check after any deploy rather than assuming an old install reflects new rules.

My AASA file is valid here but Universal Links still open Safari. Why?

This validator confirms the file is reachable and structurally correct, which is necessary but not sufficient. Also verify: the associated-domains entitlement in Xcode matches exactly (applinks:yourdomain.com), the app ID and Team ID in the JSON match your provisioning profile, and the user has not previously tapped "Open in Safari" for that domain (which suppresses the prompt).

How is this different from validating assetlinks.json?

AASA is Apple's format for iOS Universal Links; assetlinks.json is Google's equivalent for Android App Links. The two files live at different well-known paths and use different schemas, so you need both if you support iOS and Android.