Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
In-lining manifests.

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!

@iandevlin

This comment has been minimized.

Copy link

commented Dec 4, 2013

It might it be a bit neater to include such data in a separate included file, although this does of course add another HTTP request.

@AurelioDeRosa

This comment has been minimized.

Copy link

commented Dec 4, 2013

What about something external like humans.txt?

@marcoscaceres

This comment has been minimized.

Copy link
Owner Author

commented Dec 4, 2013

@iandevlin, for external, the choices are:

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

OR

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

This comment has been minimized.

Copy link

commented Dec 4, 2013

I agree, the option for it to be an external file would be nice. Out of these options I prefer using the meta tag, it makes sense to use.

@iandevlin

This comment has been minimized.

Copy link

commented Dec 4, 2013

Ah so it can be either, good.
I prefer the meta example as the data contained within it is information that the browsers/device would use rather than an actual script of instructions to run.

@SaraSoueidan

This comment has been minimized.

Copy link

commented Dec 4, 2013

I'd go with <link rel="manifest" href="app.json">, like @rprieto pointed out, it has nicer semantics.

Out of the inline options I'd go with the meta tag, although I very much prefer the external file.

@ShaneHudson

This comment has been minimized.

Copy link

commented Dec 4, 2013

I don't think using an external file would be much of a problem. It will always be a tiny file.

@espadrine

This comment has been minimized.

Copy link

commented Dec 4, 2013

Scripts everywhere, for consistency.

(If the only thing you could do was link it externally, I would go for <link>, though.)

@rprieto

This comment has been minimized.

Copy link

commented Dec 4, 2013

For the external one, I think <link rel="manifest" href="app.json"> has nicer semantics.

However, for the inline version, inlined JSON inside a meta tag might not play well with syntax highlighters. Do we really need inline support? (I imagine external rel is the preferred approach?)

@brianleroux

This comment has been minimized.

Copy link

commented Dec 4, 2013

<link> feels the most sane to me

@rodneyrehm

This comment has been minimized.

Copy link

commented Dec 4, 2013

I would reference the manifest via <link rel="manifest"> as that is how "meta" resources (stylesheets, icons, html5-import) work. The <script> suggestion has no (immediately apparent) advantage in this case.

I don't see why one would inline the manifest, as that means transferring that added data to the client all the time. But if you must, please go with the <script type="application/manifest+json">. The reason is simple: JSON in an attribute is an ugly thing, especially with multi-line values.

@yoavweiss

This comment has been minimized.

Copy link

commented Dec 4, 2013

I think B is better for the following reasons:

  • Easier to author (I suspect double-quotes in the meta alternative would be a typical foot-gun)
  • CSP can protect against XSS modifying the manifest
  • Can be easily exported to an external resource (which as @iandevlin said, can be convenient, and may not hurt much if the script is async)

OTOH, it might be good to define such scripts as async even if they're inline, since there's no reason they should block the HTML parser.

@sarbbottam

This comment has been minimized.

Copy link

commented Dec 4, 2013

<link rel="manifest" href="app.json"> would be better.

@gchp

This comment has been minimized.

Copy link

commented Dec 4, 2013

I think <link rel="manifest"> makes most sense to me

@Joe8Bit

This comment has been minimized.

Copy link

commented Dec 4, 2013

I think giving people the choice of external via a <script> tag or on page within a <script> tag makes a lot of sense. Shoehorning an object into a metatag feels very strange, especially with the " vs ' issues raises it's head.

@yoavweiss already mentioned some very good points about CSP and XSS, and scripts not blocking parsing. Both of which I completely concur with.

@davidcmoulton

This comment has been minimized.

Copy link

commented Dec 4, 2013

My preference would be for <link rel="manifest" href="..."> as it stops the manifest info from cluttering the html and also provides some sematics.

@jhermsmeier

This comment has been minimized.

Copy link

commented Dec 4, 2013

The inline <meta name="manifest" content='...' /> tag looks like a pretty ugly thing to me, and a <script> doesn't make any sense to me either, since it's not code that's actually run - it's still just meta information. So I'd go with the external <link rel="manifest" href="...">

@kvendrik

This comment has been minimized.

Copy link

commented Dec 4, 2013

Looks nice! I wouldn't prefer the whole javascript object idea though. How about something a bit closer to what is already out there?

<meta name="manifest" content='name=Example, url= /start.html, etc etc...'>
@flurin

This comment has been minimized.

Copy link

commented Dec 4, 2013

Putting complex data into an attribute makes authoring kind of hard and it feels kind of clunky to me. The script approach also doesn't sit right either: why would you want to have all the metadata inline? With the external <link rel=""> variant you'd get:

  • Caching
  • Clearly separated metadata (instead of entangled within your HTML and sent with every page within your app)

Of course it has the drawback of an extra request but I'm not sure that it should be that big of a deal, it could be loaded asynchronously if needed.

@PDMackinnon

This comment has been minimized.

Copy link

commented Dec 4, 2013

Both seem OK. Option A appears semantically better as it is literally metadata being expressed. However, I could see Option B as acceptable and potentially reasonable practice of embedding JSON as script - even though it is not executable - I have seen script tags used for templates in places. So as long as you do not have an objection to scripts being non-executables it is fine. At the moment as far as I know the only script types that are executable are javascript. Type "manifest+json" is a clear semantic direction of the type of script so I have no problem with that.
Also, the question of this being actually seen as metadata - is that misleading ? The purpose of the manifest is defining things like icons, caching etc, and not so much for search engine or app store listing purposes. In that case, maybe it is not exactly metadata so much as it is part of the functionality of the app itself.

@GreLI

This comment has been minimized.

Copy link

commented Dec 4, 2013

<link rel="…"> is the nicest, of course. For perfomance reasons it can be doubled by http-header, I think.

@iamstarkov

This comment has been minimized.

Copy link

commented Dec 4, 2013

A with Extarnal linking are good variants

@GreLI

This comment has been minimized.

Copy link

commented Dec 4, 2013

Script looks ok, but I don't like the type — it looks ugly. Thinking of HTML 5-ish, what about <manifest> tag?

@antoniopuero

This comment has been minimized.

Copy link

commented Dec 4, 2013

I prefer to use <link rel="manifest" href="app.json"> like a meta information in head of the document. It makes more sense than other variants

@AurelioDeRosa

This comment has been minimized.

Copy link

commented Dec 4, 2013

I like the first possibility of the external link. If we can choose for two alternatives, I'd go to add A.

@remybach

This comment has been minimized.

Copy link

commented Dec 4, 2013

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

@chaals

This comment has been minimized.

Copy link

commented Dec 4, 2013

For external I strongly prefer to use link. But for inlining, having a real element makes much more sense, so I'd go with script.

I would expect some authors to try using link for external, and others to use script. Although describing the interplay between the two adds at least a minimal amount of implementation complexity, I think it might be worth anticipating the problem and doing it now, although it isn't something I feel strongly about.

@GreLI the issue is that HTML5 parsing means a new element closes the head element, and the content is rendered in the body. So we can't ever have new elements with content again :( (This isn't new to HTML5, it's how the world worked. HTML5 just wrote it down).

I'd indeed like to be able to use HTML headers, e.g. to make my animated Gif into an app. Or an SVG (which is a pretty useful format for certain kinds of single-page apps), until it gets the necessary syntax. But I'm not sure how important a use case that is in the real world.

@viki53

This comment has been minimized.

Copy link

commented Dec 4, 2013

<script> tag seems logical. External file or inline content doesn't really matter (up to the developer to optimize or not).

@serbanghita

This comment has been minimized.

Copy link

commented Dec 4, 2013

I would prefer something using meta tag because it's in the right context.

<meta name="manifest" content="app.json">

But since that was not an option (mainly because content usually contains a static content, here is what I prefer.

<link rel="manifest" href="app.json">
  1. Doesn't pollute the code.
  2. The validation can be done by external parsers just by fetching app.json, no additional parsing required.
  3. Prevents HTML code conflicts.
  4. Future updates might save bandwidth to external parsers, just fetch app.json (if 404 reparse the main page).
@brucelawson

This comment has been minimized.

Copy link

commented Dec 4, 2013

Personally, I think meta tag is better - it's metadata rather then executable. It looks ugly, but meta is so overloaded and ugly anyway, that ship has sailed.

@sideshowbarker

This comment has been minimized.

Copy link

commented Dec 4, 2013

don’t inline manifests

@lmedini

This comment has been minimized.

Copy link

commented Dec 4, 2013

If there is nothing in the spec that prevents two different documents from being part of the same installable webapp, I suggest the external option.

@TimPietrusky

This comment has been minimized.

Copy link

commented Dec 4, 2013

Why don't we merge this manifest idea with the draft for Offline Web applications and their HTML manifest attribute? They use something like this

<html manifest="clock.appcache">

I think it would be easier for developers to use just one manifest and not different types of manifests with the exact same name, but inside different attributes / tags.

So I suggest

<html manifest="myapp">

or

<html manifest="myapp.json">

Which contains both the cache manifest, this manifest and maybe others to come:

{
  "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"
  }],
  "cache": [
    "my/file.css",
    "my/file.js"
  ]
}
@tiagoboldt

This comment has been minimized.

Copy link

commented Dec 4, 2013

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

it is either small, and easier to maintain as is it kept in an isolated file.

@AidanThreadgold

This comment has been minimized.

Copy link

commented Dec 4, 2013

link is nicer and less clunky than meta. It's cleaner to have the manifest in a separate file than having it inline I feel

@qvit

This comment has been minimized.

Copy link

commented Dec 4, 2013

<script> for inline and <link> for external

@mubaidr

This comment has been minimized.

Copy link

commented Dec 4, 2013

Much better to keep it external link i.e.

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

Another good option by @TimPietrusky, sems more reasonable.

<html manifest="myapp.json">
@jordangray

This comment has been minimized.

Copy link

commented Dec 4, 2013

My favourite: only external manifests are permitted using <link rel="manifest">.

  • In my mind at least, manifests are comparable to other document resources such as rel="search" and rel="stylesheet".

Less favourite: both external and inline manifests are permitted using <script type="application/manifest+json">.

  • A number of templating libraries set precedents for using script for non-executable content. The spec says that it may be used for "data blocks"—which isn't exactly what I'd say a manifest is, but one could liberally interpret it as such.

Using meta is my least favourite option.

  • I agree that a manifest can be considered metadata, but that's a somewhat ambiguous concept; other classifications are equally justifiable.
  • Microsyntaxes in attributes are, in my opinion, best used as a measure of last resort. In this particular case, it isn't easy on the eye, the nested quotes are awkward and—until dev tools catch up—you will need to copy and paste it from another file anyway if you want syntax checking and highlighting. In particular, this makes mistakes harder to spot and easier to make if someone has to edit an existing manifest.

Edited to add: I really like Tim Pietrusky's suggestion of folding this into <html manifest="…">.

@mathiasbynens

This comment has been minimized.

Copy link

commented Dec 4, 2013

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

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

commented Dec 4, 2013

TimPietrusky +1

@distobj

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

commented Dec 4, 2013

I think rel is great.

@jah2488

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

commented Dec 4, 2013

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

@aardrian

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

commented Dec 4, 2013

External link is better...

@nkt

This comment has been minimized.

Copy link

commented Dec 4, 2013

B + external link. Like js or css right now

@ianakelly

This comment has been minimized.

Copy link

commented Dec 4, 2013

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

@bjankord

This comment has been minimized.

Copy link

commented Dec 4, 2013

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

@larsgk

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

commented Dec 4, 2013

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

This comment has been minimized.

Copy link

commented Dec 4, 2013

I would prefer B for inline and

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

for external ones.

@substack

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

commented Dec 4, 2013

I would go for @msemenistyi's suggestion.

@grorg

This comment has been minimized.

Copy link

commented Dec 4, 2013

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

@ylafon

This comment has been minimized.

Copy link

commented Dec 5, 2013

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

@cranca

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

commented Dec 5, 2013

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

@tobie

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

commented Dec 5, 2013

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

This comment has been minimized.

Copy link

commented Dec 6, 2013

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

This comment has been minimized.

Copy link

commented Dec 7, 2013

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

@triblondon

This comment has been minimized.

Copy link

commented Dec 11, 2013

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
You can’t perform that action at this time.