export const metadata = {
    title: 'Notes',
    description: 'Definition of the Note entity',
}

# Notes

Notes represent a piece of content on a Versia instance. They can be posted by [Users](/entities/user) and are displayed in a user's feed. Notes can contain text, images, and other media. {{ className: 'lead' }}

<Note>
    Notes are not just limited to microblogging. They can be used for any kind of content, such as forum posts, blog posts, image posts, video posts, audio posts, and even messaging.
</Note>

## Entity Definition

<Row>
    <Col>
        <Properties name="Note">
            <Property name="attachments" type="ContentFormat[]" required={true} typeLink="/structures/content-format">
                Media attachments to the note. May be any format. **Must** be remote.
            </Property>
            <Property name="author" type="Reference" required={true} typeLink="/types#reference">
                [Reference](/types#reference) to the `User` considered the author of the note.
            </Property>
            <Property name="category" type="Category" required={false}>
                Category of the note. Useful for clients to render notes differently depending on their intended purpose.

                ```typescript
                type Category =
                    | "microblog" // Like Twitter, Mastodon
                    | "forum" // Like Reddit
                    | "blog" // Like WordPress, Medium
                    | "image" // Like Instagram
                    | "video" // Like YouTube, PeerTube
                    | "audio" // Like SoundCloud, Spotify
                    | "messaging"; // Like Discord, Element (Matrix), Signal
                ```
            </Property>
            <Property name="content" type="ContentFormat" required={false} typeLink="/structures/content-format">
                The content of the note. Must be text format (`text/html`, `text/markdown`, etc). Must not be remote.
            </Property>
            <Property name="device" type="Device" required={false}>
                Device used to post the note. Useful for functionality such as Twitter's "posted via" feature.

                ```typescript
                type Device = {
                    name: string;
                    version?: string;
                    url?: string;
                }
                ```
            </Property>
            <Property name="group" type="Reference | &quot;public&quot; | &quot;followers&quot;" required={false} typeLink="/types#reference">
                [Reference](/types#reference) to a [Group](/extensions/groups) that the note is only visible in, or one of the following strings:
                - `public`: The note is visible to anyone.
                - `followers`: The note is visible only to the author's followers.

                If not provided, the note is only visible to the author and those mentioned in the note. If missing, the note is only visible to any mentioned users.

                <Note>
                    If the implementation does not support the [Groups Extension](/extensions/groups), any value other than `public` or `followers` should be treated as `null`.
                </Note>
            </Property>
            <Property name="is_sensitive" type="boolean" required={true}>
                Whether the note contains "sensitive content". This can be used with `subject` as a "content warning" feature.
            </Property>
            <Property name="mentions" type="Reference[]" required={true} typeLink="/types#reference">
                [References](/types#reference) to [Users](/entities/user) that should be notified of the note. Similar to Twitter's `@` mentions. The note may also contain mentions in the content, however only the mentions in this field should trigger notifications.
            </Property>
            <Property name="previews" type="LinkPreview[]" required={true}>
                Previews for any links in the publication. This is to avoid the [stampeding mastodon problem](https://github.com/mastodon/mastodon/issues/23662) where a link preview is fetched by every instance that sees the publication, creating an accidental DDOS attack.

                ```typescript
                type LinkPreview = {
                    link: string;
                    title: string;
                    description?: string;
                    image?: string;
                    icon?: string;
                }
                ```

                <Note>
                    Implementations should make sure not to trust the previews, as they could be faked by malicious remote instances. This is not a very good attack vector, but it is still possible to redirect users to malicious links.
                </Note>
            </Property>
            <Property name="quotes" type="Reference" required={false} typeLink="/types#reference">
                [Reference](/types#reference) to the note that this note is quoting, if any. Quoting is similar to replying, but does not notify the author of the quoted note. Inspired by Twitter's "quote tweet" feature.
            </Property>
            <Property name="replies_to" type="Reference" required={false} typeLink="/types#reference">
                [Reference](/types#reference) to the note that this note is a reply to, if any.
            </Property>
            <Property name="subject" type="string" required={false}>
                A subject for the note. Useful for clients to display a "content warning" or "spoiler" feature, such as on Mastodon. Must be a plaintext string (`text/plain`).
            </Property>
        </Properties>
    </Col>
    <Col sticky>

    ```jsonc {{ 'title': 'Example Note' }}
    {
        "id": "01902e09-0f8b-72de-8ee3-9afc0cf5eae1",
        "type": "Note",
        "created_at": "2024-06-19T01:07:44.139Z",
        "attachments": [ // [!code focus:100]
            {
                "image/png": {
                    "content": "https://cdn.versia.social/29e810bf4707fef373d886af322089d5db300fce66e4e073efc26827f10825f6/image.webp",
                    "remote": true,
                    "thumbhash": "1QcSHQRnh493V4dIh4eXh1h4kJUI",
                    "description": null,
                    "fps": null,
                    "duration": null,
                    "height": 960,
                    "size": 221275,
                    "hash": {
                        "sha256": "967b8e86d8708c6283814f450efcbd3be94d3d24ca9a7ab435b2ff8b51dcbc21"
                    },
                    "width": 639
                }
            },
            {
                "text/plain": {
                    "content": "https://cdn.lysand.org/68c02dd11c179ef4d170b05393f6e72133dd0ad733f40d41b42363d8784e8d5d/fire.txt",
                    "remote": true,
                    "description": null,
                    "thumbhash": null,
                    "width": null,
                    "height": null,
                    "fps": null,
                    "duration": null
                    "size": 8,
                    "hash": {
                        "sha256": "68c02dd11c179ef4d170b05393f6e72133dd0ad733f40d41b42363d8784e8d5d"
                    }
                }
            }
        ],
        "author": "018eb863-753f-76ff-83d6-fd590de7740a",
        "category": "microblog",
        "content": {
            "text/html": {
                "content": "<p>In the next versia-fe update: account settings, finally!</p>"
            },
            "text/plain": {
                "content": "In the next versia-fe update: account settings, finally!"
            }
        },
        "device": {
            "name": "Megalodon for Android",
            "version": "1.3.89",
            "url": "https://sk22.github.io/megalodon"
        },
        "extensions": {
            "pub.versia:custom_emojis": {
                "emojis": []
            }
        },
        "group": "public",
        "is_sensitive": false,
        "mentions": [],
        "subject": "Versia development",
        "previews": [],
        "quotes": null,
        "replies_to": null
    }
    ```

    </Col>
</Row>

### Collections

The following [Collections](/structures/collection) are available:

- `replies`: [URI Collection](/structures/collection#uri-collection) of [Note](/entities/note) entities that are replies to this note.
- `quotes`: [URI Collection](/structures/collection#uri-collection) of [Note](/entities/note) entities that quote this note.

These can be fetched using the [Federation API](/api/endpoints#entity-collections)