About @render for JSON

1. What does @render look like?

In a text editor, it looks like an @render attribute annotating your JSON. This references your desired loader to bootstrap the UI builder (or "hydration" logic) for working with the JSON data. For example:

    {
      "@render": "<script src='https://cdn.example/watchlib.js'>",
      "name": "Alice's watchlist",
      "url": "https://alice.example.net/movies",
      "already_watched": [
        {
          "title": "The Iron Giant", "id": "[wikidata:Q867283]",
          "score": ":thumbsup:"
        },
        {
          "title": "Under the Skin", "id": "[wikidata:Q4366287]",
          "score": ":thumbsdown:"
        },
        /* ... */
    

In a browser, it looks however you want it to look—subject to what your @render loader chooses to build and put on the screen.

Here's a live example of Alice's watchlist data, showing how the post-render data looks in the browser:

(You can also follow a direct link to the JSON payload to see it outside the iframe shown here.)

2. How does it work?

To a JSON parser, @render is just an ordinary property whose value is a string (albeit one that we know happens to look like HTML).

To an HTML parser, your JSON just looks like a bunch of text surrounding a bit of markup describing a lone script element near the beginning of the file (in the body rather than the head, but that's no big deal).

The trick is to convince browsers to treat the JSON as HTML, whether by sending an HTML media type from the server, or by using an HTML file extension (instead of .json) for local files opened from your computer.

In an HTML parsing context, the browser sees the markup for your loader script and then loads and executes the script source. The script, if self-aware enough, can read out the JSON data and then attach purpose-built, in-browser controls for viewing, editing, and otherwise working with the specific type of data contained within the JSON payload (or other data that it references, or anything else that you want to put on the screen).

3. Why would you want this?

JSON is an acceptable format for authoring and data exchange, but sometimes big blobs of JSON can get unwieldy. Not all user agents have perfect (or your preferred) JSON viewing tools, and even browsers that have tools for dealing with JSON can't have application-specific affordances for all the different shapes of JSON they might be absked to show.

The @render trick lets you put your data on the screen in the way that you prefer to show it while remaining valid JSON.

And of course, the latitude that this gives you means you can use @render to make the actual editing experience for JSON-based formats nicer, too.

4. Shouldn't the apps we're building already provide those editing affordances?

Maybe. Using @render can be useful for providing a lower-level interface to the data encoded in the file that ordinary users might not be interested in (or ever even see).

5. What else?

There are some caveats.

In addition to getting it to load in a parsing context that's expecting markup, you'll need to make sure to properly escape your JSON content for HTML. Doing this successfully isn't super-complicated. It's enough to escape all occurrences of U+0026 AMPERSAND and U+003C LESS-THAN SIGN using the Unicode escape sequence notation for string literals in JSON, i.e., \u0026 and \u003c, respectively.

There are additional authoring notes and tips relevant to @render collected on a separate page.