# Instance metadata

For many features of PawPub to work properly, instances must provide **metadata** about themselves. For example, [authentication](auth) and [push](push) use an instance-wide endpoint, which is specified in the instance metadata. It also provides some other information that clients or third-party services may wish to use.

## Schema

The following should be present at the path `/.well-known/pawpub-instance`:

- name: string required
- description: string optional
- icon: uri optional
- softwareName: string required
- softwareDescription: string optional
- softwareVersion: string optional
- softwareHomepage: uri optional
- endpoints: object required
    - auth: uri optional
    - report: uri optional
    - push: uri optional
    - subscribe: uri optional
    - unsubscribe: uri optional [if you have subscribe you also need unsubscribe and vice versa]

## Example

```json
{
    "name": "Example Social",
    "description": "example pawpub instance",
    "softwareName": "Digitigrade",
    "softwareDescription": "An experimental PawPub server",
    "softwareVersion": "v0.1.0",
    "endpoints": {
        "auth": "https://example.social/auth/main",
        "report": "https://example.social/report",
        "push": "https://example.social/push",
        "subscribe": "https://example.social/subscribe",
        "unsubscribe": "https://example.social/unsubscribe"
    }
}
```

## NodeInfo

You can also provide a [NodeInfo](https://nodeinfo.diaspora.software/) document if you want to, but it's not required and isn't really part of the PawPub spec. If you do provide one, you should specify "pawpub" in the supported protocols. You can also include this JSON object in the freeform metadata:

- pawpub: object
    - extensions: array(uri)