nips/54.md

66 lines
3.3 KiB
Markdown
Raw Normal View History

2023-05-12 14:18:42 -04:00
NIP-54
======
Inline Resource Metadata
------------------------
2023-05-17 10:20:23 -04:00
`draft` `optional` `author:arthurfranca` `author:Giszmo` `author:jb55` `author:vitorpamplona`
2023-05-12 14:18:42 -04:00
Inline resource metadata is additional information associated with urls in notes that clients can optionally use to enhance resource loading.
2023-08-31 09:55:42 -04:00
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.
2023-05-12 14:18:42 -04:00
2023-08-31 09:55:42 -04:00
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 `?`.**
2023-05-12 14:18:42 -04:00
2023-05-17 11:40:00 -04:00
The metadata can be appended to any url, like this [NIP-21](21.md) one: `nostr:nevent1qq...pm#a-metadata-name=a-metadata-value`.
2023-05-12 14:18:42 -04:00
## NIP-94 File Fragments
2023-05-17 10:20:23 -04:00
Besides available w3c and proprietary URI fragment usage, nostr uses existing [NIP-94](94.md) tags as file fragment name-value pairs. NIP-94 event `.content` is equivalent to `alt` fragment field. For example, one could join the following strings to form an image url with inline metadata:
2023-05-12 14:18:42 -04:00
- `https://nostr.build/i/863321bb1ae68830ebcf9a343ca0a5e0ce2323d0a55b7fbe86f7a886cf61db8d.jpg`
- `#`
2023-08-31 09:55:42 -04:00
- `m=image%2Fjpeg`
- `&`
2023-05-12 14:18:42 -04:00
- `dim=3024x4032`
- `&`
2023-05-17 11:40:00 -04:00
- `alt=A%20scenic%20photo%20overlooking%20the%20coast%20of%20Costa%20Rica`
2023-05-12 14:18:42 -04:00
- `&`
2023-05-17 11:40:00 -04:00
- `blurhash=eVF%24%5EOI%3A%24%7BM%7Bo%23*0-nNFxakD-%3FxVM%7DWEWB%25iNKxvR-oetmo%23R-aen%24`
2023-05-12 14:18:42 -04:00
2023-08-31 09:55:42 -04:00
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`.
2023-05-12 14:18:42 -04:00
2023-08-31 09:55:42 -04:00
### Event Example:
2023-05-17 11:40:00 -04:00
```js
{
"kind": 1,
2023-08-31 09:55:42 -04:00
"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`",
2023-05-17 11:40:00 -04:00
// ... other event fields
}
```
## Tag Usage
When publishing events of kinds designed with urls inside tags instead of in `.content`, use `media` tags specifically for image, audio and video
or else pick another tag such as `r`. One may also add `media` tags to events to aid in loading media placeholders on clients that postpone or don't do event `.content` parsing.
2023-08-31 09:55:42 -04:00
### Tag Examples:
2023-10-31 18:08:46 -04:00
An image with MIME type, dimensions and blurhash:
`["media", "https://xyz.com/image001.png#m=image%2Fpng&dim=1342x704&blurhash=MnR3f%2C%25M%252%25MjZ~Wj%40j%5Bt7Rjs%3Aayfkj%5BWB%5C"]`
2023-08-31 09:55:42 -04:00
A kind 30023 event JSON file (with `nostr/30023` MIME type):
`["r", "https://xyz.com/example.json#m=nostr%2F30023"]`
2023-08-31 09:55:42 -04:00
2023-05-12 14:18:42 -04:00
## Recommended client behavior
When uploading images during a new post, clients can collect metadata
after the image is uploaded and then include the url with inline metadata in the post.
When pasting urls during post composition, the client could download the image
and add some metadata before the post is sent.
2023-05-17 11:40:00 -04:00
Clients can use `alt` value to add accessible text for people who prefer not to
2023-05-12 14:18:42 -04:00
load images, visibility-impaired users, or text clients.