Re: [w3c/manifest] Add min_version and fingerprints to application objects (#566)

mgiuca commented on this pull request.

Thanks for writing this up.

> @@ -3141,27 +3151,67 @@ <h3 id="applying">
       </h2>
       <p>
         Each <dfn>application object</dfn> represents an application related to
-        the web application. An application object has three properties: a
-        <code>platform</code> which represents the platform it is associated
-        to, a <code>url</code> which represents the URL where the application
-        can be found and an <code>id</code> which can be used as an information
-        additional to the URL or instead of the URL, depending on the platform.
+        the web application. An application object has five properties:

Can we change this to "has the following properties" so we don't have to remember to keep this number up to date as we add more?

>          A valid <a>application object</a> MUST have <code>platform</code> and
         either an <code>url</code> or an <code>id</code> (or both).
       </p>
       <div class="example">
         <p>
           In the following example, the web application is listing two
           different related applications, one on Google Play Store and the
-          other one on the iTunes Store:
+          other one on the iTunes Store. The one on the Google Play Store has a

"... has an Android package name, a minimum version ..."

> @@ -3244,6 +3294,108 @@ <h3 id="applying">
           </li>
         </ol>
       </section>
+      <section>
+        <h3>
+          <code>min_version</code> member
+        </h3>
+        <p>
+          The <dfn data-lt="application-min-version">min_version</dfn> member
+          of an application object represents the minimum version required for

_"minimum version required"_

"required" is a bit weird here since referring to an application in the manifest does not "require" anything. Perhaps, "the minimum version of the application that is considered related to this web app."

> +        </ol>
+      </section>
+      <section>
+        <h3>
+          <code>fingerprints</code> member
+        </h3>
+        <p>
+          The <dfn data-lt="application-fingerprints">fingerprints</dfn> member
+          of an application object represents a set of cryptographic
+          fingerprints used for verifying the application. It is given as an
+          array of <a data-lt="fingerprint object">fingerprint objects</a>.
+        </p>
+        <p>
+          A <dfn>fingerprint object</dfn> has two properties: <code>type</code>
+          and <code>value</code>. Each of these are strings, but their
+          semantics are platform-defined.

syntax and semantics

> +          <li>Let <var>fingerprints</var> be an empty list.
+          </li>
+          <li>Let <var>unprocessed fingerprints</var> be the result of calling
+          the <a>[[\GetOwnProperty]]</a> internal method of
+          <var>application</var> passing "<code>fingerprints</code>" as the
+          argument.
+          </li>
+          <li>If <var>unprocessed fingerprints</var> is an array, then for each
+          <var>potential fingerprint</var> in <var>unprocessed
+          fingerprints</var>:
+            <ol>
+              <li>Let <var>type</var> be the result of calling the
+              <a>[[\GetOwnProperty]]</a> internal method of <var>potential
+              fingerprint</var> passing "<code>type</code>" as an argument.
+              </li>
+              <li>If Type(<var>type</var>) is not "string", then issue a

Oh no :(

The type/type name clash has already come to bite us.

> +            <ol>
+              <li>Let <var>type</var> be the result of calling the
+              <a>[[\GetOwnProperty]]</a> internal method of <var>potential
+              fingerprint</var> passing "<code>type</code>" as an argument.
+              </li>
+              <li>If Type(<var>type</var>) is not "string", then issue a
+              developer warning that the type is unsupported, and move on to
+              the next item in <var>unprocessed fingerprints</var> (if any are
+              left).
+              </li>
+              <li>Let <var>value</var> be the result of calling the
+              <a>[[\GetOwnProperty]]</a> internal method of <var>potential
+              fingerprint</var> passing "<code>value</code>" as an argument.
+              </li>
+              <li>If Type(<var>value</var>) is not "string", then issue a
+              developer warning that the type is unsupported, and move on to

Same as above.

> +          </li>
+          <li>Let <var>unprocessed fingerprints</var> be the result of calling
+          the <a>[[\GetOwnProperty]]</a> internal method of
+          <var>application</var> passing "<code>fingerprints</code>" as the
+          argument.
+          </li>
+          <li>If <var>unprocessed fingerprints</var> is an array, then for each
+          <var>potential fingerprint</var> in <var>unprocessed
+          fingerprints</var>:
+            <ol>
+              <li>Let <var>type</var> be the result of calling the
+              <a>[[\GetOwnProperty]]</a> internal method of <var>potential
+              fingerprint</var> passing "<code>type</code>" as an argument.
+              </li>
+              <li>If Type(<var>type</var>) is not "string", then issue a
+              developer warning that the type is unsupported, and move on to

"issue a developer warning" should be linked.

I noticed that the other uses of this include the word "optionally" (see id and min_version). However, the definition of "issue a developer warning" clearly says that the UA can decide to do nothing, so the word "optionally" is redundant here. Perhaps remove it from the other usages?

> -                  <li>Otherwise, let <var>application</var> be an object with
-                  properties <code>platform</code>, <code>id</code>,
-                  <code>url</code> respectively set to <var>platform</var>,
-                  <var>id</var> and <var>url</var>.
+                  <li>Let <var>minVersion</var> be the result of running the
+                  <a>steps for processing the <code>min_version</code> member
+                  of an application</a> with <var>potential application</var>.
+                  </li>
+                  <li>Let <var>fingerprints</var> be the result of running the
+                  <a>steps for processing the <code>fingerprints</code> member
+                  of an application</a> with <var>potential application</var>.
+                  </li>
+                  <li>Let <var>application</var> be an object with properties
+                  <code>platform</code>, <code>id</code>, <code>url</code>,
+                  <code>min_version</code>, and <code>fingerprints</code>
+                  respectively set to <var>platform</var>, <var>id</var>, <var>

nit: Wrap so that <var>url</var> is together on one line.

Don't indent these two lines by extra spaces.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/manifest/pull/566#pullrequestreview-32545696