Skip to content

GitLab

ServiceInfo
ServiceInfo
Commit 8a8f2135 authored by jaywink's avatar jaywink
Browse files
Options

Merge branch 'respec' into 'master' 

Rewrite NodeInfo2 as ServerInfo

See merge request feneas/serverinfo!1
parents 9857beb2 9d60273c
Hide whitespace changes
Inline Side-by-side
Showing with 201 additions and 181 deletions
PROTOCOL.md deleted 100644 → 0
View file @ 9857beb2
# NodeInfo2 protocol 1.0
## Status
This document is still in early draft status.
## Definitions
The term "server" in this document refers to software providing metadata about itself on a host.
The term "client" in this document refers to software wishing to retrieve metadata about a host.
The term "schema" refers to a schema definition provided in the schemas subdirectory.
## Document location
Where possible a server should provide a NodeInfo2 document at the endpoint `/.well-known/x-nodeinfo2`.
For [ActivityPub](https://www.w3.org/TR/activitypub/) implementers, an URI to a NodeInfo2 document should be provided in the Actor object as property `nodeInfo2Url`.
## Retrieval
When accessing the metadata document, a client should set the Accept header to the `application/json` media type.
A server must provide the data at least in this media type. A server should set a Content-Type of `application/json`.
When accessing NodeInfo2 documents through an ActivityPub Actor, fetching client should not assume that each document will correspond to a different server. The key `server.baseUrl` should be compared against when collecting statistics of a server. If two NodeInfo2 documents fetched via two different Actor objects have the same `server.baseUrl`, any statistics should be treated as one instead of counting them together.
### baseUrl validation
Consumers should not blindly trust `server.baseUrl` and should always verify it is under the host that was initially called. For example, if a document fetched at host `foobar.local` contains a `server.baseUrl` of `barfoo.local`, it should be rejected.
## Schema
The [schema](https://github.com/jaywink/nodeinfo2/blob/master/schemas/1.0/schema.json) lists required and documented known optional keys.
Due to the versioning of NodeInfo2, which has no version change in forward changes, only major backwards incompatible changes, implementors should be prepared tho deal with situations where a key that has recently been added to the specification doesn't yet exist in all the NodeInfo2 documents created by servers implementing NodeInfo2.
### Data values
Below are some example key values. Using these will ensure interoperability between other nodes using NodeInfo2. Please provide additional items that are common in your implementation to these lists via PR's.
### `server.name`
* `diaspora`
* `friendica`
* `gnusocial`
* `hubzilla`
* `mastodon`
* `mediagoblin`
* `nextcloud`
* `pumpio`
* `redmatrix`
* `socialhome`
* `social-relay`
* `ganggo`
* `wordpress`
### `protocols`
* `activitypub`
* `diaspora`
* `dfrn`
* `libertree`
* `mediagoblin`
* `ostatus`
* `pumpio`
* `webmention`
* `zot`
README.md
View file @ 8a8f2135
# NodeInfo2
# ServerInfo
NodeInfo2 is an effort to create a standardized way of exposing metadata about a server. This might be necessary to expose ownership and organization details, usage statistics and protocol capabilities.
Serverinfo is an effort to create a standardized way of exposing metadata about a server. This might be necessary to expose ownership and organization details, usage statistics and protocol capabilities.
## Protocol
## Specification
Please see the [protocol definition](PROTOCOL.md).
Please see the [specification](SPECIFICATION.md).
## Versioning
......@@ -14,15 +14,11 @@ Current version is 1.0. Version upgrade shall happen only in backwards incompati
Implemented in the following platforms:
* [The Federation.info](https://the-federation.info)
* [Socialhome](https://socialhome.network)
* [Prismo](https://gitlab.com/mbajur/prismo)
* [Juick](https://juick.com/)
* TBD
Library support is available for the following:
* [Federation](https://github.com/jaywink/federation) (Python)
* [WordPress Plugin](https://wordpress.org/plugins/nodeinfo/) (PHP)
* TBD
Have a server or library you have added support to? Send a PR!
......@@ -36,6 +32,4 @@ Please open issues and pull requests if you want to suggest a change. If you ope
## History
NodeInfo2 is a fork of [NodeInfo](https://github.com/jhass/nodeinfo) which was seen as too complex for the problem it is solving. NodeInfo2 is interested in controlling *structure* of the document, not content. Additionally, discovery and strict versioning has been dropped for simpler implementation.
NodeInfo emerged from it's predecessor `/statistics.json` that was added to the diaspora* software to be able to built a statistics collection and aggregation service, it was quickly supported by Friendica and RedMatrix. As more and more metadata was added and modifications occurred that would break backward compatibility, we felt the need to make this a more coordinated effort.
ServerInfo is a fork of [NodeInfo2](https://git.feneas.org/jaywink/nodeinfo2) which itself is a fork of [NodeInfo](https://nodeinfo.diaspora.software/) which was the successor of `statistics.json` in Diaspora.
SPECIFICATION.md 0 → 100644
View file @ 8a8f2135
# ServerInfo specification 1.0
## Status
This document is still in early draft status.
## Definitions
The term "server" in this document refers to software providing metadata about itself on a host.
The term "client" in this document refers to software wishing to retrieve metadata about a host.
The term "schema" refers to a schema definition provided in the schemas subdirectory.
## Document location
A server SHOULD provide a ServerInfo document at the endpoint `/.well-known/x-serverinfo`.
### ActivityPub
Actor's in ActivityPub MAY have an additional `endpoint` called `serverinfo`, pointing to the location of the serverinfo document.
## Retrieval
When accessing the metadata document, a client SHOULD set the Accept header to the `application/json` media type.
A server SHOULD set a Content-Type of `application/json`.
## Schema
See the latest [schema](/schemas/1.0/schema.json).
Clients SHOULD verify the serverinfo document against the schema.
schemas/1.0/example.json
View file @ 8a8f2135
{
"version": "1.0",
"server": {
"baseUrl": "https://example.com",
"name": "Example diaspora* server",
"software": "diaspora",
"id": "https://example.com/.well-known/x-serverinfo",
"name": "Example server",
"software": "example",
"version": "0.5.0"
},
"protocols": ["diaspora", "zot"],
"services": {
"inbound": ["gnusocial"],
"outbound": ["facebook", "twitter"]
"organization": {
"name": "Example Inc",
"contact": "info@example.com",
"account": "https://example.com/user/example"
},
"openRegistrations": true,
"usage": {
"users": {
"total": 123,
"activeHalfyear": 42,
"activeMonth": 23
"protocols": [
{
"name": "activitypub",
"capabilities": [
{
"extensions": [
"http://joinmastodon.org/ns#",
"https://forgefed.example.com"
]
}
]
},
"localPosts": 500,
"localComments": 1000
{
"name": "diaspora",
"version": "0.2.6"
},
{
"name": "matrix",
"capabilities": [
{
"presence": false
}
],
"version": "0.1.2"
}
],
"externalServices": {
"inbound": ["twitter", "freenode"],
"outbound": ["tumbrl", "twitter", "freenode"]
},
"publicRegistrations": true,
"metrics": [
{
"periodLength": 604800,
"type": "activeUsers",
"value": 1234,
"startTime": "2007-04-05T14:30Z"
},
{
"periodLength": 604800,
"type": "localMessages",
"value": 9876,
"startTime": "2007-04-05T14:30Z"
}
],
"features": {
"catPicturesVersion": "1.23",
"chat": true,
"codeOfConduct": "https://example.com/coc"
}
}
schemas/1.0/schema.json
View file @ 8a8f2135
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "http://the-federation.info/nodeinfo2#",
"description": "NodeInfo2 schema version 1.0.",
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"id": "https://feneas.org/specs/serverinfo",
"title": "ServerInfo schema version 1.0.",
"type": "object",
"required": [
"version",
"server",
"openRegistrations"
"publicRegistrations"
],
"properties": {
"version": {
"description": "The schema version, must be 1.0.",
"title": "The schema version, must be 1.0.",
"enum": [
"1.0"
]
},
"server": {
"description": "Metadata about server in use.",
"title": "Metadata about server in use.",
"type": "object",
"required": [
"baseUrl",
"id",
"name",
"software",
"version"
],
"properties": {
"baseUrl": {
"description": "Base URL of the server.",
"type": "string",
"id": {
"title": "URI ID of the server.",
"type": "string"
},
"name": {
"description": "The display name of the server or service.",
"title": "The display name of the server or service.",
"type": "string"
},
"software": {
"description": "The name of the server software.",
"title": "The name of the server software.",
"type": "string"
},
"version": {
"description": "The version of this server software.",
"title": "The version of this server software.",
"type": "string"
}
}
},
"organization": {
"description": "Metadata about the owner of this server.",
"title": "Metadata about the owner of this server.",
"type": "object",
"name": {
"description": "The name of the organization or person.",
"title": "The name of the organization or person.",
"type": "string"
},
"contact": {
"description": "Contact information for the organization or person.",
"title": "Contact information for the organization or person.",
"type": "string"
},
"account": {
"description": "URL of admin or info account on this server.",
"title": "URL of admin or info account on this server.",
"type": "string"
}
},
"protocols": {
"description": "The protocols supported on this server.",
"title": "The protocols supported on this server.",
"type": "array",
"minItems": 0,
"items": {
"type": "string"
"title": "Information about the protocol",
"type": "object",
"required": [
"name"
],
"name": {
"title": "Name of the protocol",
"type": "string",
"examples": [
"activitypub",
"diaspora",
"dfrn",
"libertree",
"matrix",
"ostatus",
"pumpio",
"webmention",
"zot"
]
},
"capabilities": {
"title": "List of capabilities offered by this server",
"type": "array",
"minItems": 0,
"items": {
"title": "Information about the capability",
"type": "object"
}
},
"version": {
"title": "Version of the protocol implemented",
"type": "string"
}
}
},
"services": {
"description": "The third party sites this server can connect to via their application API.",
"externalServices": {
"title": "The third party sites this server can connect to via their application API.",
"type": "object",
"properties": {
"inbound": {
"description": "The third party sites this server can retrieve messages from for combined display with regular traffic.",
"title": "The third party sites this server can retrieve messages from on behalf of a user.",
"type": "array",
"minItems": 0,
"items": {
......@@ -80,7 +113,7 @@
}
},
"outbound": {
"description": "The third party sites this server can publish messages to on the behalf of a user.",
"title": "The third party sites this server can publish messages to on the behalf of a user.",
"type": "array",
"minItems": 0,
"items": {
......@@ -89,77 +122,66 @@
}
}
},
"openRegistrations": {
"description": "Whether this server allows open self-registration.",
"publicRegistrations": {
"title": "Whether this server has public registrations.",
"type": "boolean"
},
"usage": {
"description": "Usage statistics for this server.",
"type": "object",
"properties": {
"users": {
"description": "statistics about the users of this server.",
"type": "object",
"properties": {
"total": {
"description": "The total amount of on this server registered users.",
"type": "integer",
"minimum": 0
},
"activeHalfyear": {
"description": "The amount of users that signed in at least once in the last 180 days.",
"type": "integer",
"minimum": 0
},
"activeMonth": {
"description": "The amount of users that signed in at least once in the last 30 days.",
"type": "integer",
"minimum": 0
},
"activeWeek": {
"description": "The amount of users that signed in at least once in the last 7 days.",
"type": "integer",
"minimum": 0
}
}
},
"localPosts": {
"description": "The amount of posts that were made by users that are registered on this server.",
"type": "integer",
"minimum": 0
},
"localComments": {
"description": "The amount of comments that were made by users that are registered on this server.",
"type": "integer",
"minimum": 0
}
}
},
"relay": {
"description": "State of relay integration, see https://github.com/jaywink/social-relay/blob/master/docs/relays.md",
"enum": [
"",
"all",
"tags"
]
},
"otherFeatures": {
"description": "Other features of the server.",
"metrics": {
"title": "Metrics for this server.",
"type": "array",
"minItems": 0,
"items": {
"title": "Information about the metric.",
"type": "object",
"required": [
"periodLength",
"type",
"value"
],
"properties": {
"name": {
"description": "The name of the feature",
"type": "string"
"periodLength": {
"title": "Period length for the metric in seconds.",
"description": "Common good values are for example a day (86400), a week (604800) or a month (2592000).",
"type": "integer",
"examples": [
60,
3600,
86400,
604800,
2592000
]
},
"version": {
"description": "The version of the feature.",
"type": "string"
"type": {
"title": "Type of metric.",
"type": "string",
"examples": [
"activeUsers",
"totalUsers",
"localMessages"
]
},
"value": {
"title": "Value for the metric.",
"type": "integer",
"default": 0
},
"startTime": {
"title": "Start time of the period ISO-8601 UTC time",
"type": "string",
"examples": [
"2007-04-05T14:30Z"
]
}
}
}
},
"features": {
"title": "Other features of the server.",
"description": "Free form object for describing other features of the server which might only be relevant within the same software stack.",
"type": "array",
"minItems": 0,
"items": {
"type": "object"
}
}
}
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment