Skip to content

Instantly share code, notes, and snippets.

@marcoscaceres

marcoscaceres/manifest-options.md

Last active December 13, 2022 02:00
Show Gist options
  • Star 9 You must be signed in to star a gist
  • Fork 2 You must be signed in to fork a gist
  • Save marcoscaceres/7783977 to your computer and use it in GitHub Desktop.
Save marcoscaceres/7783977 to your computer and use it in GitHub Desktop.
Download ZIP
In-lining manifests.
Raw
manifest-options.md

Conclusions

updated on 19th of December

Thanks everyone who participated in the discussion! It was tremendously userful

So, what we are going to do initially is only support:

<link rel="manifest" href="...some URL...">

By virtue of this being a URL, if people really want to inline the manifest they can use a data: URL:

<link rel=manifest href="data:application/manifest+json,{ ... }">

Credit to @yoavweiss for proposing the above on the public-webapps mailing list.

If, after some time, we find a lot of people are inlining manifests in the wild, we can return and look at alternatives - like using <script> or <meta>.

Which one do you prefer?

We are trying to create a new manifest format for the Web. It will allow you to define metadata for a web application in one place.

Right now, we are trying to decide how to "inline" the manifest into HTML. Need your feedback.

A - using a meta element and content attribute

<!doctype html>
<html>
<head>
...
<meta name="manifest" content='{
  "name": "Example",
  "url": "/start.html",
  "mode": "standalone",
  "icons": [{
      "src": "icon/lowres",
      "density": "1",
      "width": "64",
      "type": "image/webp"
    }, {
      "src": "icon/hd",
      "density": "2",
      "width": "64"
  }]
}'>
...

B - using a script tag

<!doctype html>
<html>
<head>
...
<script type="application/manifest+json">
{
  "name": "Example",
  "url": "/start.html",
  "mode": "standalone",
  "icons": [{
      "src": "icon/lowres",
      "density": "1",
      "width": "64",
      "type": "image/webp"
    }, {
      "src": "icon/hd",
      "density": "2",
      "width": "64"
  }]
}
</script>

External linking

<link rel="manifest" href="app.json">`

OR

  <script src="app.json" type="application/manifest+json"></script>

Got a better idea?

Please share it in the comments!

@mathiasbynens
Copy link

AFAICT @TimPietrusky's suggestion of folding this into <html manifest="…"> would break backwards compatibility and is therefore not an option.

I agree that these manifests don’t need to be inlinable, though. My vote: just support external linking through <link rel=manifest src=lolwat.json>.

If you decide not to inline, my vote goes to the <script> option with a non-JS type.

@nwtn
Copy link

nwtn commented Dec 4, 2013

Definitely prefer B, especially w/ the external option, for all the reasons given above. (I don't actually hate the idea of using meta, I just hate the idea of having JSON in an attribute.)

Having the option for both inline and external is nice, IMO. Inline is great for single-page apps to cut out the extra HTTP request, external is great for caching and maintenance on multi-page sites.

@antonydevanchi
Copy link

TimPietrusky +1

@distobj
Copy link

distobj commented Dec 4, 2013

I like the meta and link options. "script" is confusing, as the contained content certainly doesn't contain any imperative statements (like MANIFEST = { ... }) and you wouldn't want to optimize it like you would actual scripts (priority preloading etc..), so I don't see that being a viable option.

@pusewicz
Copy link

pusewicz commented Dec 4, 2013

I think rel is great.

@jah2488
Copy link

jah2488 commented Dec 4, 2013

For me using meta and content makes most sense, avoid overloading <script> whenever possible, and I fully support the <link rel="manifest" href="app.json"> style of including external configuration.

@0b10011
Copy link

0b10011 commented Dec 4, 2013

I agree with @mathiasbynens. <link rel="manifest" href="app.json"> would be ideal.

If you had to support inlining, from a developer standpoint, <script type="application/manifest+json">{...}</script> would be easier as there is already extensive highlighting/indentation/etc support for json in editors. From a picky standpoint, I would prefer <meta name="manifest" content='{...}'> simply due to it providing meta information, but lack of highlighting/indentation support, quoting issues, etc would be rather annoying. Alternatively, you could go with a new tag (eg, <manifest>{...}</manifest> or something less restricting with a similar meaning to <meta>), which would make adding highlighting/indentation support rather easy (mode-switching often happens inside of tags).

But, my vote goes to <link rel="manifest" href="app.json">.

@gyndav
Copy link

gyndav commented Dec 4, 2013

External linking is great with "rel" would be a good idea.

@aardrian
Copy link

aardrian commented Dec 4, 2013

For inline: B (using a script element).

For external linking: using a link element.

Reasons are pretty well captured in above comments, but I readily latch on to the concern that stuffing this into a meta tag will probably cause more problems (quotes in particular) than explaining why it's a script block when inline versus a link tag when external. Also, I think a script block will result in less cognitive dissonance than a meta tag when looking at the JSON structure, but that is completely speculation.

@abalam666
Copy link

External link is better...

@nkt
Copy link

nkt commented Dec 4, 2013

B + external link. Like js or css right now

@ianakelly
Copy link

Meta is much more descriptive as to the purpose of the content in the context, and ` wins in my mind.

@bjankord
Copy link

bjankord commented Dec 4, 2013

I like the external link approach <link rel="manifest" href="app.json">

@larsgk
Copy link

larsgk commented Dec 4, 2013

I'd go for a solution, where the manifest info is in a separate file - but with a fixed name.

The separate file makes it very easy to e.g. make simple scripts to manage several apps, as they just have to know about this particular JSON file and not go through HTML parsing first (in principle) to figure out where to inject/extract info.

The reason why I would like to have a fixed name (e.g. app.json or the like - exactly like index.html has become a standard) is that browsers that can handle the manifest file would then first look for app.json, then index.html when presented with a fresh URL ending in a directory path (~ not a file).

Additionally (if not obvious) - if the JSON manifest file has a fixed name (allowing the browser to go for that file first), browses know a lot about the application prior to loading and parsing ANY other file (= speed, permissions/security, caching, icons, ...). This would also make it VERY efficient for e.g. a browser listing a bundle of applications (including reflecting updates, etc.)

@kornelski
Copy link

None of them. We already have <meta>/<link> for most of the manifest:

    {
      "name": "My App",
      "url": "/start.html",
      "mode": "standalone",
      "icons": [{
          "src": "icon/lowres",
          "width": "64",
          "type": "image/webp"
        }, {
          "src": "icon/hd",
          "width": "128"
      }]
    }

Can be written today, without reinventing the wheel, in a backwards-compatible way:

    <meta name="application-name" name="My App">
    <link rel=start href="/start.html">
    <meta name="mobile-web-app-capable" content="yes">
    <link rel=icon sizes="64x64" type="image/webp" href="icon/lowres">
    <link rel=icon sizes="128x128" href="icon/hd">

And unlike JSON, it supports comments, internationalization and doesn't invalidate entire file because of a single trailing comma :)

    <meta name="application-name" name="My App" lang="en">
    <meta name="application-name" name="Moja Apka" lang="pl">
    <!-- I can comment things without breaking syntax, wow such amaze -->
    <link rel=icon href="es.png" hreflang=es><!-- text in the icon? No problemo! -->

@msemenistyi
Copy link

I would prefer B for inline and

<link rel="manifest" href="app.json">

for external ones.

Copy link

ghost commented Dec 4, 2013

I second @pornel's comments. HTML already has a mechanism for describing data in <meta> tags. Just use what already exists instead of inventing a new thing.

@mildmojo
Copy link

mildmojo commented Dec 4, 2013

@pornel's suggestion to just put the info in meta tags makes sense to me. Of the provided choices, <script> for inline and <link> for external seems like the least surprising combo.

IMHO, it's important to have an inline format available for apps in single files, apps in data URIs, or apps served from cache or storage where the external resource may no longer be available.

@aadsm
Copy link

aadsm commented Dec 4, 2013

I would go for @msemenistyi's suggestion.

@grorg
Copy link

grorg commented Dec 4, 2013

I vote for script and link rel="manifest".

@ylafon
Copy link

ylafon commented Dec 5, 2013

link rel-manifest is good, and keep it always external.

@cranca
Copy link

cranca commented Dec 5, 2013

I also agree with the link solution. It's cleanest and doesn't add more noise to HTML docs... But if I had to choose a inline way I like manifest proposal because it's more semantical than script.

@andreasbovens
Copy link

I'm with @pornel. It would be nice to (re)use <meta> and <link> elements as much as possible.

@tobie
Copy link

tobie commented Dec 5, 2013

Using a meta element and JSON in the content attribute is a terrible idea. Here's why.

  1. It forces using single quotes to wrap the content attribute, special-casing this attribute in the process. So while you can easily wrap an onclick attribute with double or single quotes, e.g.:

    <a href="#" onclick="alert('clicked!');">Click me!</a>
<a href='#' onclick='alert("clicked!");'>Click me!</a>

    that wouldn't work for our manifest. The following works:

    <meta name='manifest' content='{ "name": "Example" }'>

    But this would not (the content isn't valid JSON):

    <!--- THIS WON'T WORK -->
<meta name="manifest" content="{ 'name': 'Example' }">

    This would be very inconsistent with the rest of the platform.

  2. What happens when you have apostrophes within your content? When inlined using the meta element it would have to be escaped, e.g.:

    <meta name='manifest' content='{ "name": "Here\'s an example" }'>

    But that wouldn't be necessary when linking manifests. So copy/pasting from manifests originally written to be linked might end up wrecking havoc when used inline. (This is a situation analogous to closing script tags within inlined JavaScript which is a source of countless bugs).

Using meta elements for each property, e.g.:

<meta name="app-title" content="Example">
<meta name="app-mode" content="standalone">

won't work well for nested or enumerated content (try describing the icons mentioned above, it's hard), and it won't translate easily to a linked format.

Of course, the best option would be to create a manifest element, but that's not possible for legacy reasons (afaik, parsers switch to body content as soon as they find a tag which isn't blessed as that of a child of the head element).

In conclusion, the only reasonable option is to use a script tag for inline content. For linked manifest, using the link element is appealing, but is inconsistent with using the script tag when inline, so I'd probably suggest using script tags for both.

@dret
Copy link

dret commented Dec 5, 2013

regarding "We are trying to create a new manifest format for the Web" in the intro: isn't HTML5 defining just that in http://www.w3.org/TR/html5/browsers.html#offline ?
my guess this is more about the mechanics about how to to make it available? but isn't that also specified in HTML5 already? could somebody please briefly point out how this gist relates to what's specified in HTML5? thanks!

@dret
Copy link

dret commented Dec 5, 2013

if this is only about where to make the manifest available and how, then linking definitely should be the way to go. this way all the REST mechanics can apply: potentially multiple media types (if somebody ever comes up with a different manifest format), and maybe even PATCH formats for manifests if there are huge manifests, and there should be a way how diffs can be communicated. use web architecture as much as possible, and in this case, any solution other than linking seems vastly inferior. define and register a link relation type, and make sure that the linking mechanism does not hardcode the manifest media type to it.

@kevburnsjr
Copy link

Require <link> and allow developers to reference inline manifests using fragment identifiers.

<link rel="manifest" href="#inline-manifest">
<script id="inline-manifest" type="application/manifest+json">
{
  "name": "Example",
  "url": "/start.html",
  "mode": "standalone",
  "icons": [{
      "src": "icon/lowres",
      "density": "1",
      "width": "64",
      "type": "image/webp"
    }, {
      "src": "icon/hd",
      "density": "2",
      "width": "64"
  }]
}
</script>

@CodyErekson
Copy link

I like option B, using <script> tags. Mainly for portability reasons. Being able to easily pull this data into other code with little effort will probably be of enormous value.

@DavidCarcamo
Copy link

external link to a JSON file, please no inline script tag, or JSON in meta tag.

@triblondon
Copy link

I agree with @tobie. We should have options for both external linking and inline embedding of the manifest data, and the only existing tag which gives us that ability in a <head> context is <script>. But, I would be concerned about shifting data for which there are already defined meta tags (as @pornel points out) into the manifest, as developers will then inevitably have to use both.

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