diff --git a/README.md b/README.md index e990ff9..fad0328 100644 --- a/README.md +++ b/README.md @@ -166,6 +166,78 @@ And the equivalent HTML: ``` +And the equivalent Siren-style JSON: + +```json +{ + "class": ["albums"], + "title": "Albums", + "properties": [ + { + "name": "description", + "value": "A list of albums you should listen to." + }, + { + "name": "entityCount", + "value": 3 + } + ], + "entities": [ + { + "class": ["entity", "album"], + "rel": ["item"], + "href": "/albums/a65x0qxr", + "properties": [ + { + "name": "name", + "value": "Dark Side of the Moon" + }, + { + "name": "artist", + "value": "Pink Floyd" + } + ] + }, + { + "class": ["entity", "album"], + "rel": ["item"], + "href": "/albums/a7ff1qxw", + "properties": [ + { + "name": "name", + "value": "Random Access Memories" + }, + { + "name": "artist", + "value": "Daft Punk" + } + ] + } + ], + "links": [ + { + "rel": ["next"], + "href": "/albums?offset=2&limit=1", + "title": "Next" + }, + { + "rel": ["self", "canonical"], + "href": "http://albums.com/albums" + } + ] +} +``` + +### Token Usage Comparison + +The same information represented in different formats: + +* **Jiron (pug)**: 918 characters +* **JSON**: 1,065 characters (16% more than Jiron) +* **HTML**: 1,434 characters (56% more than Jiron) + +As you can see, Jiron's pug-based syntax is significantly more token-efficient than both JSON and HTML, while still maintaining the rich hypermedia semantics of Siren. The JSON representation requires expanding simple values into objects with explicit "name" and "value" properties, which adds overhead compared to Jiron's terse syntax where properties can be expressed inline. + Here's a translation of the example from the Siren README: ```pug diff --git a/examples/albums.json b/examples/albums.json new file mode 100644 index 0000000..58cde3d --- /dev/null +++ b/examples/albums.json @@ -0,0 +1,57 @@ +{ + "class": ["albums"], + "title": "Albums", + "properties": [ + { + "name": "description", + "value": "A list of albums you should listen to." + }, + { + "name": "entityCount", + "value": 3 + } + ], + "entities": [ + { + "class": ["entity", "album"], + "rel": ["item"], + "href": "/albums/a65x0qxr", + "properties": [ + { + "name": "name", + "value": "Dark Side of the Moon" + }, + { + "name": "artist", + "value": "Pink Floyd" + } + ] + }, + { + "class": ["entity", "album"], + "rel": ["item"], + "href": "/albums/a7ff1qxw", + "properties": [ + { + "name": "name", + "value": "Random Access Memories" + }, + { + "name": "artist", + "value": "Daft Punk" + } + ] + } + ], + "links": [ + { + "rel": ["next"], + "href": "/albums?offset=2&limit=1", + "title": "Next" + }, + { + "rel": ["self", "canonical"], + "href": "http://albums.com/albums" + } + ] +}