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!

[christianliebel]

@dipikabh Thank you for your questions. @benfrancis's answers are correct.

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

Yes, I can confirm this behavior: Web app installation occurs while a particular document (page) is loaded. Upon installation, the manifest file linked in this document is fetched. So the document linking to the manifest and installing the app is one and the same, and so is its URL.

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.

The description of the scope value is correct, except the following sentence, which is a bit tricky:

The start_url must be within the defined scope.

This depends on which scope you are referring to, the author-defined scope value in the manifest, or the effective/processed scope after processing the manifest.

As @benfrancis laid out, the start_url doesn't necessarily have to be within the scope defined by the scope member in the manifest. If the start_url is outside this scope, its value will be ignored, and the "processed scope" will be adjusted to contain the start_url, which you correctly describe later in that section.

Authors should define the scope member in the manifest so that the start_url is within scope, because the value will be ignored otherwise. Maybe you could simply leave this sentence out, as you already correctly describe this behavior later in the section.

Regarding the start_url value:

The start_url must be within the scope of the web app and must be same-origin with the manifest URL.

1. The same applies here regarding start_url. Maybe you could rephrase this: If the scope value is not defined in the manifest or start_url is not within this scope, the scope will be set to the start_url with the filename, query, and fragment removed.
2. The specification does not require the start_url to be same-origin with the manifest URL but with the document URL (see process the start_url member, step 6). This allows serving the manifest from a different origin but restricts installing apps to the origin of the document triggering installation.

I hope this clarifies all of your open questions.

[dipikabh]

@christianliebel thanks for taking the time to answer my questions and providing clarifications. This all makes sense.

I've opened mdn/content#36784 to update the two pages based on your responses. I'll close this issue. Thank you both for your help.