====== Instance metadata ======

For many features of PawPub to work properly, [[instances]] must provide **metadata** about themselves. For example, [[authentication]] and [[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 [requires auth]
    * push: uri optional [requires auth]
    * simplePush: uri optional
    * subscribe: uri optional [requires auth and unsubscribe]
    * unsubscribe: uri optional [requires auth and subscribe]
  * extensions: object optional default={}
    * (uri): any many


===== Example =====

<code javascript>
{
    "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",
        "pushUri": "https://example.social/push/simple",
        "subscribe": "https://example.social/subscribe",
        "unsubscribe": "https://example.social/unsubscribe"
    },
    "extensions": {
        "https://example.org/extension/some-custom-endpoint": "https://example.social/custom-endpoint"
    }
}
</code>


===== NodeInfo =====

You can also provide a [[https://nodeinfo.diaspora.software/|NodeInfo]] 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 free-form metadata:
  * pawpub: object
    * extensions: array(uri)