Skip to content

well-known: add /.well-known/ard.json (ARD v0.91 canonical path) - #204

Open
flober81 wants to merge 1 commit into
HTTPArchive:mainfrom
flober81:ard-json-well-known
Open

flober81 wants to merge 1 commit into
HTTPArchive:mainfrom
flober81:ard-json-well-known

Conversation

@flober81

Copy link
Copy Markdown
Contributor

Adds /.well-known/ard.json next to /.well-known/ai-catalog.json (#201).

Why: ARD spec v0.91 (ards-project/ard-spec, 2026-08-26, "promote the draft, single well-known path") makes /.well-known/ard.json the canonical location: "A consumer resolving a domain's entries MUST fetch /.well-known/ard.json, and MUST honour a rel="ard" link." ai-catalog.json and rel="ai-catalog" are now the predecessor. Lighthouse 13.5's ARD gatherer still resolves the predecessor path (GoogleChrome/lighthouse#17251 tracks updating it to v0.91), so the #201 entry stays as it is; recording the new path separately is what lets HTTP Archive see whether publishers move.

What is recorded: entries_count and entry_types (capped at 20), keyed by /.well-known/ard.json. The v0.91 manifest only requires entries ("any other top-level members are transport-defined and ignored"), so spec_version and has_host are not recorded for the new path. A <link rel="ard"> pointing elsewhere wins and is recorded as catalog_url, mirroring #201; not found is just {"found": false}. Entry parsing is shared with the ai-catalog block through a small helper; the ai-catalog output is unchanged (checked old vs. new over nine cases). Invalid JSON or an HTML catch-all page yields the default values, no error.


Test websites:

@github-actions

Copy link
Copy Markdown
https://almanac.httparchive.org/en/2022/

WPT result details

Changed custom metrics values:

{
  "_well-known": {
    "/.well-known/assetlinks.json": {
      "found": false
    },
    "/.well-known/apple-app-site-association": {
      "found": false
    },
    "/.well-known/related-website-set.json": {
      "found": false
    },
    "/.well-known/privacy-sandbox-attestations.json": {
      "found": false
    },
    "/.well-known/gpc.json": {
      "found": false
    },
    "/.well-known/web-identity": {
      "found": false
    },
    "/.well-known/passkey-endpoints": {
      "found": false
    },
    "/.well-known/webauthn": {
      "found": false
    },
    "/.well-known/ucp": {
      "found": false
    },
    "/.well-known/email-verification": {
      "found": false
    },
    "/robots.txt": {
      "found": true,
      "data": {
        "matched_disallows": {}
      }
    },
    "/.well-known/ai-catalog.json": {
      "found": false
    },
    "/.well-known/ard.json": {
      "found": false
    },
    "/.well-known/security.txt": {
      "found": false,
      "data": {
        "status": 404,
        "redirected": true,
        "url": "https://almanac.httparchive.org/.well-known/security.txt/",
        "content_type": "text/html; charset=utf-8"
      }
    },
    "/.well-known/change-password": {
      "found": false,
      "data": {
        "status": 404,
        "redirected": true,
        "url": "https://almanac.httparchive.org/.well-known/change-password/"
      }
    },
    "/.well-known/resource-that-should-not-exist-whose-status-code-should-not-be-200/": {
      "found": false,
      "data": {
        "status": 404,
        "redirected": false,
        "url": "https://almanac.httparchive.org/.well-known/resource-that-should-not-exist-whose-status-code-should-not-be-200/"
      }
    }
  }
}
https://btlabs.dev

WPT result details

Changed custom metrics values:

{
  "_well-known": {
    "/.well-known/assetlinks.json": {
      "found": false
    },
    "/.well-known/apple-app-site-association": {
      "found": false
    },
    "/.well-known/related-website-set.json": {
      "found": false
    },
    "/.well-known/privacy-sandbox-attestations.json": {
      "error": "signal is aborted without reason"
    },
    "/.well-known/gpc.json": {
      "found": true,
      "data": {
        "gpc": true
      }
    },
    "/.well-known/web-identity": {
      "error": "signal is aborted without reason"
    },
    "/.well-known/passkey-endpoints": {
      "error": "signal is aborted without reason"
    },
    "/.well-known/webauthn": {
      "error": "signal is aborted without reason"
    },
    "/.well-known/ucp": {
      "found": false
    },
    "/.well-known/email-verification": {
      "error": "signal is aborted without reason"
    },
    "/robots.txt": {
      "found": true,
      "data": {
        "matched_disallows": {
          "*": [
            "/admin"
          ]
        }
      }
    },
    "/.well-known/ai-catalog.json": {
      "found": true,
      "data": {
        "spec_version": "1.0",
        "has_host": true,
        "entries_count": 3,
        "entry_types": [
          "application/openapi+yaml",
          "application/mcp-server-card+json"
        ]
      }
    },
    "/.well-known/ard.json": {
      "found": true,
      "data": {
        "entries_count": 3,
        "entry_types": [
          "application/openapi+yaml",
          "application/mcp-server-card+json"
        ]
      }
    },
    "/.well-known/security.txt": {
      "error": "signal is aborted without reason"
    },
    "/.well-known/change-password": {
      "error": "signal is aborted without reason"
    },
    "/.well-known/resource-that-should-not-exist-whose-status-code-should-not-be-200/": {
      "error": "signal is aborted without reason"
    }
  }
}
https://example.com

WPT result details

Changed custom metrics values:

{
  "_well-known": {
    "/.well-known/assetlinks.json": {
      "found": false
    },
    "/.well-known/apple-app-site-association": {
      "found": false
    },
    "/.well-known/related-website-set.json": {
      "found": false
    },
    "/.well-known/privacy-sandbox-attestations.json": {
      "found": false
    },
    "/.well-known/gpc.json": {
      "found": false
    },
    "/.well-known/web-identity": {
      "found": false
    },
    "/.well-known/passkey-endpoints": {
      "found": false
    },
    "/.well-known/webauthn": {
      "found": false
    },
    "/.well-known/ucp": {
      "found": false
    },
    "/.well-known/email-verification": {
      "found": false
    },
    "/robots.txt": {
      "found": false
    },
    "/.well-known/ai-catalog.json": {
      "found": false
    },
    "/.well-known/ard.json": {
      "found": false
    },
    "/.well-known/security.txt": {
      "found": false,
      "data": {
        "status": 404,
        "redirected": false,
        "url": "https://example.com/.well-known/security.txt",
        "content_type": "text/html"
      }
    },
    "/.well-known/change-password": {
      "found": false,
      "data": {
        "status": 404,
        "redirected": false,
        "url": "https://example.com/.well-known/change-password"
      }
    },
    "/.well-known/resource-that-should-not-exist-whose-status-code-should-not-be-200/": {
      "found": false,
      "data": {
        "status": 404,
        "redirected": false,
        "url": "https://example.com/.well-known/resource-that-should-not-exist-whose-status-code-should-not-be-200/"
      }
    }
  }
}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant