Clarification needed for document URL

[dipikabh]

I am updating the manifest member documentation on MDN.

For start_url, the page currently states:

A valid start_url needs to be same-origin with the document that references the manifest. If start_url is unspecified or invalid in any way (such as not a string, not a valid URL, or not a same-origin with the document), the document URL is used.

(change source)

However, while updating the page in this PR (you can preview the changes), I am not clear about how to expand/replace/clarify "document URL":

• Is it the URL of the page that links to the manifest file? or
• Is it the URL of the page from which the app is installed (perhaps this was the case in the past? (Updating is under/incorrectly specified #384).

There is not much detail in the specification and I'm trying to gather bits and pieces from old issues in this repo.

Context

Emphasis is mine:

• https://w3c.github.io/manifest/#understanding-scope

  If the scope member is missing from the manifest, then the path of the start_url member is used as a fallback. And if the start_url member is also missing, then the document URL from which the web application is installed gets used as the scope.

• start_url should not default to document URL #669, from the description:

  the current default for start_url is the document URL (the page that referred the user agent to this manifest)

Questions

Are these statements correct:

• If start_url is not defined or invalid, then there is no default.
  But would it be correct to assume that the page from which the app is installed is used, though it is not set as the default starting point. What page would open when users click on the app icon?
• If the URL is relative, it is resolved against the manifest file's URL.
• The URL must be same-origin with the page that links to the manifest file.
• The URL must be within the defined scope.

/cc @marcoscaceres @mgiuca : I'd appreciate your insights, thanks

[benfrancis]

Hi, I'm not an editor and they should be able to provide a definitive answer, but from my experience implementing the specification...

@dipikabh wrote:

I am not clear about how to expand/replace/clarify "document URL":

• Is it the URL of the page that links to the manifest file? or
• Is it the URL of the page from which the app is installed (perhaps this was the case in the past? Updating is under/incorrectly specified #384).

It is usually both. A user agent follows a manifest link relation in a page to fetch the manifest, and offers the user the option to install the web app from that page (which is then the "document URL"). It's not technically possible to install a web app from a web page outside the application (e.g. an app store) whilst conforming to the specification (although I believe Microsoft do do that, see #668).

Are these statements correct:

• If start_url is not defined or invalid, then there is no default.
  But would it be correct to assume that the page from which the app is installed is used, though it is not set as the default starting point. What page would open when users click on the app icon?

As I understand it if no start_url is specified in the manifest then the document URL (the document from which the manifest was linked to) is used as the default start URL. See the algorithm in section 1.10.

• If the URL is relative, it is resolved against the manifest file's URL

Yes, I think that's correct.

• The URL must be same-origin with the page that links to the manifest file.

Yes, otherwise the default (document URL) is used.

• The URL must be within the defined scope.

Although effectively true, it actually works the other way around. If the start URL is not within scope of the scope member provided in the manifest, then the start URL (with filename, query and fragment removed) is used as the scope instead, rather than the value that was provided in the manifest.

/cc @marcoscaceres @mgiuca : I'd appreciate your insights, thanks

I'd be interested to know whether my understanding differs!

[dipikabh]

Thanks @benfrancis. Appreciate you taking the time to share your experience as an implementer.

It is usually both. A user agent follows a manifest link relation in a page to fetch the manifest, and offers the user the option to install the web app from that page (which is then the "document URL").

I'd be interested to add this information to our reference page once the editors confirm this behavior.

The start_url updates have landed but I can see the need to clarify what happens when start_url is not within scope. I've mentioned it on the scope page but it needs a mention on the start_url page as well. I should also update the "same-origin with the page that links to the manifest file" requirement.

I'll wait to hear from the editors to confirm these behaviors. Thanks again!