diff --git a/54.md b/54.md index 1f4526b2..d536120b 100644 --- a/54.md +++ b/54.md @@ -8,13 +8,13 @@ Inline Resource Metadata Inline resource metadata is additional information associated with urls in notes that clients can optionally use to enhance resource loading. -It uses [URI Fragment](https://en.wikipedia.org/wiki/URI_fragment) that agents (such as web browsers) never send to the server. +It uses [URI Fragment](https://en.wikipedia.org/wiki/URI_fragment) that agents (such as web browsers) never send to the server. Because of this, the url is fetched **without** the fragment parameters, unlike using query parameters. -The URI fragment follows [media fragments structure](https://www.w3.org/TR/media-frags/#general-structure). For example, one could use `t=number_of_seconds` to start playing a video at the specified position along with an extra [percent-encoded](https://www.ietf.org/rfc/rfc3986.txt) name-value pair separated by `&` char like `https://xyz.com/a-video.mp4#t=24&a%20name=a%20value`. +The URI fragment follows [media fragments structure](https://www.w3.org/TR/media-frags/#general-structure). For example, one could use `t=number_of_seconds` to start playing a video at the specified position along with an extra [percent-encoded](https://www.ietf.org/rfc/rfc3986.txt) name-value pair separated by `&` char like `https://xyz.com/a-video.mp4#t=24&a%20name=a%20value`. **Notice the usage of `#` instead of `?`.** The metadata can be appended to any url, like this [NIP-21](21.md) one: `nostr:nevent1qq...pm#a-metadata-name=a-metadata-value`. -It is suggested to also add `imeta` tags to events to aid in loading resource placeholders. +One may also add `resource` tags to events to aid in loading resource placeholders on clients that postpone or don't do event `.content` parsing. ## NIP-94 File Fragments @@ -22,40 +22,48 @@ Besides available w3c and proprietary URI fragment usage, nostr uses existing [N - `https://nostr.build/i/863321bb1ae68830ebcf9a343ca0a5e0ce2323d0a55b7fbe86f7a886cf61db8d.jpg` - `#` +- `m=image%2Fjpeg` +- `&` - `dim=3024x4032` - `&` - `alt=A%20scenic%20photo%20overlooking%20the%20coast%20of%20Costa%20Rica` - `&` - `blurhash=eVF%24%5EOI%3A%24%7BM%7Bo%23*0-nNFxakD-%3FxVM%7DWEWB%25iNKxvR-oetmo%23R-aen%24` -Multiple array values use repeated names and are positioned in the same order of ocurrence in the tag array. For instance, `["aes-256-gcm", 'i-am-a-key', 'i-am-an-iv']` becomes `aes-256-gcm=i-am-a-key&aes-256-gcm=i-am-an-iv` +Multiple array values use repeated names and are positioned in the same order of ocurrence in the tag array. For instance, `["aes-256-gcm", 'i-am-a-key', 'i-am-an-iv']` becomes `aes-256-gcm=i-am-a-key&aes-256-gcm=i-am-an-iv`. -## imeta tag +## Tag Usage Metadata fragments are great for sharing urls with extra embedded metadata. They are also good for copying and pasting a resource's url from one note to a new one without losing its metadata. But some clients can prepare image and video placeholders faster if specific fields are present outside of `.content`. -For these resources, it is suggested to also add `dim`, `alt` and `blurhash` (e.g. of a specific video frame), if available, to `imeta` tags. +For these resources, it is suggested to also add `dim`, `alt` and `blurhash`, if available, to media urls inside `resource` tags. -### Complete example: +### Event Example: ```js { "kind": 1, - "content": "What a great place! https://xyz.com/example.jpg#dim=3024x4032&alt=A%20scenic%20photo%20overlooking%20the%20coast%20of%20Costa%20Rica&blurhash=eVF%24%5EOI%3A%24%7BM%7Bo%23*0-nNFxakD-%3FxVM%7DWEWB%25iNKxvR-oetmo%23R-aen%24`", + "content": "What a great place! https://xyz.com/example.jpg#m=image%2Fjpeg&dim=3024x4032&alt=A%20scenic%20photo%20overlooking%20the%20coast%20of%20Costa%20Rica&blurhash=eVF%24%5EOI%3A%24%7BM%7Bo%23*0-nNFxakD-%3FxVM%7DWEWB%25iNKxvR-oetmo%23R-aen%24`", "tags": [ [ - "imeta", - "url https://xyz.com/example.jpg", - "dim 3024x4032", - "alt A scenic photo overlooking the coast of Costa Rica", - "blurhash eVF$^OI:${M{o#*0-nNFxakD-?xVM}WEWB%iNKxvR-oetmo#R-aen$" + "resource", "https://xyz.com/example.jpg#dim=3024x4032&alt=A%20scenic%20photo%20overlooking%20the%20coast%20of%20Costa%20Rica&blurhash=eVF%24%5EOI%3A%24%7BM%7Bo%23*0-nNFxakD-%3FxVM%7DWEWB%25iNKxvR-oetmo%23R-aen%24" ] ] // ... other event fields } ``` +Also, some event kinds other than kind 1 and kind 30023 may have been designed with urls inside tags instead of in `.content`. For these cases, use `resource` tags (or `r` tags if it needs to be indexed by relays – in this case, metadata fragment keys and query parameter keys SHOULD be arranged in ascending order). + +### Tag Examples: + +A kind 30023 event JSON file (with `nostr/30023` MIME type): +`["resource", "https://xyz.com/example.json#m=nostr%2F30023"]` + +A PDF file without extension with added MIME type information: +`["r", "https://xyz.com/article02#m=application%2Fpdf"]` + ## Recommended client behavior When uploading images during a new post, clients can collect metadata diff --git a/README.md b/README.md index d5677a08..2f886c36 100644 --- a/README.md +++ b/README.md @@ -195,6 +195,7 @@ Please update these lists when proposing NIPs introducing new event kinds. | `published_at` | unix timestamp (string) | -- | [23](23.md) | | `relay` | relay url | -- | [42](42.md) | | `relays` | relay list | -- | [57](57.md) | +| `resource | URL | -- | [54](54.md) | | `subject` | subject | -- | [14](14.md) | | `summary` | article summary | -- | [23](23.md) | | `thumb` | badge thumbnail | dimensions in pixels | [58](58.md) |