Commit dbe09af1 authored by jaywink's avatar jaywink

Rewrite as NodeInfo2

parent f330a27e
# NodeInfo protocol 1.0
# NodeInfo2 protocol 1.0
## Status
......@@ -6,83 +6,36 @@ 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 "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 "client" in this document refers to software wishing to retrieve metadata about a host.
The term "NodeInfo schema" refers to a schema definition provided in the
schemas subdirectory.
The term "schema" refers to a schema definition provided in the schemas subdirectory.
## Discovery
Servers must provide the well-known path `/.well-known/nodeinfo` and
provide a JRD document referencing the supported documents via Link
elements.
Currently the following relations are known:
* `http://nodeinfo.diaspora.software/ns/schema/1.0`. Referencing a JSON document
following the NodeInfo schema 1.0.
A client should first try the HTTPS protocol and fall back to HTTP on
connection errors or if it can't validate the presented certificate.
A client should follow redirections by the HTTP protocol.
A client should abandon the discovery on a HTTP response status code of
404 or 400 and may mark the host as not supporting the NodeInfo protocol.
A client should retry discovery on server errors as indicated by the
HTTP response status code 500.
A client should follow the link matching the highest schema version it
supports.
Discovery for media types other than `application/json` is left
unspecified.
### Example
The server at `https://example.org` supporting NodeInfo schema up to version
1.0 should provide `https://example.org/.well-known/nodeinfo` with the following
contents:
```json
{
"links": [
{
"rel": "http://nodeinfo.diaspora.software/ns/schema/1.0",
"href": "https://example.org/nodeinfo/1.0"
}
]
}
```
## Retrieval
A server must provide the metadata document at the endpoint `/.well-known/x-nodeinfo2`.
## Retrieval
When accessing the metadata document, a client should set the Accept header to the `application/json` media type.
When accessing the referenced schema 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`.
A server must provide the data at least in this media type. A server should
set a Content-Type of
`application/json; profile=http://nodeinfo.diaspora.software/ns/schema/1.0#`,
where the value of profile matches the resolution scope of the NodeInfo
schema version that's being returned.
## Structure
A sever may provide additional representations.
Due to the versioning of NodeInfo2, which is 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 contents
Known data element values. Using these will ensure interoperatibility between other nodes using NodeInfo. Please provide additional items that are common in your implementation to these lists via PR's.
Known data element values. Using these will ensure interoperatibility between other nodes using NodeInfo2. Please provide additional items that are common in your implementation to these lists via PR's.
### `software.name`
* `diaspora`
* `friendica`
* `hubzilla`
* `redmatrix`
* `socialhome`
* `social-relay`
### `protocols.inbound.items`
......@@ -93,7 +46,7 @@ Known data element values. Using these will ensure interoperatibility between ot
* `libertree`
* `mediagoblin`
* `pumpio`
* `redmatrix`
* `zot`
* `smtp`
* `tent`
......
# NodeInfo
NodeInfo is an effort to create a standardized way of exposing metadata
about a server running one of the distributed social networks. The two key
goals are being able to get better insights into the user base of distributed
social networking and the ability to built tools that allow users to choose
the best fitting software and server for their needs.
# NodeInfo2
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.
## Protocol
Please see the [protocol definition](PROTOCOL.md).
## Versioning
Current version is 1.0. Version upgrade shall happen only in backwards incompatible major changes. Forward changes, ie adding keys will not cause a version upgrading. This means implementors can be guaranteed a stable basic implementation that will not have to be changed all the time.
## Support
So far plans for integration of this standard exist for the following softwares:
No major support at this point. Plans for integration of this standard exist for the following server stacks:
* [diaspora*](https://diasporafoundation.org)
* [The Federation.info](https://the-federation.info)
* [Social-Relay](https://github.com/jaywink/social-relay)
* [Socialhome](https://github.com/jaywink/socialhome)
Library support is planned for the following:
* [Social-Federation](https://github.com/jaywink/social-federation) (Python)
## License
......@@ -23,17 +28,12 @@ All content in this repository is under [CC0](http://creativecommons.org/publicd
## Contributing
Please open issues and pull requests if you want to suggest a change.
If you open a pull request you agree for your work to be released under
CC0.
Please open issues and pull requests if you want to suggest a change. If you open a pull request you agree for your work to be released under CC0.
## History
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.
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.
{
"version": "1.0",
"software": {
"name": "diaspora",
"server": {
"name": "Example diaspora* server",
"software": "diaspora",
"version": "0.5.0"
},
"protocols": {
......@@ -21,8 +22,5 @@
},
"localPosts": 500,
"localComments": 1000
},
"metadata": {
"chat_enabled": true
}
}
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "http://nodeinfo.diaspora.software/ns/schema/1.0#",
"description": "NodeInfo schema version 1.0.",
"id": "http://the-federation.info/nodeinfo2#",
"description": "NodeInfo2 schema version 1.0.",
"type": "object",
"additionalProperties": false,
"required": [
"version",
"software",
"protocols",
"services",
"openRegistrations",
"usage",
"metadata"
"server",
"openRegistrations"
],
"properties": {
"version": {
......@@ -20,16 +15,20 @@
"1.0"
]
},
"software": {
"description": "Metadata about server software in use.",
"server": {
"description": "Metadata about server in use.",
"type": "object",
"additionalProperties": false,
"required": [
"name",
"software",
"version"
],
"properties": {
"name": {
"description": "The name of the server.",
"type": "string"
},
"software": {
"description": "The canonical name of this server software.",
"type": "string"
},
......@@ -39,19 +38,26 @@
}
}
},
"organization": {
"description": "Metadata about the owner of this server.",
"type": "object",
"name": {
"description": "The name of the organization or person.",
"type": "string"
},
"contact": {
"description": "Contact information for the organization or person.",
"type": "string"
}
},
"protocols": {
"description": "The protocols supported on this server.",
"type": "object",
"additionalProperties": false,
"required": [
"inbound",
"outbound"
],
"properties": {
"inbound": {
"description": "The protocols this server can receive traffic for.",
"type": "array",
"minItems": 1,
"minItems": 0,
"items": {
"type": "string"
}
......@@ -59,7 +65,7 @@
"outbound": {
"description": "The protocols this server can generate traffic for.",
"type": "array",
"minItems": 1,
"minItems": 0,
"items": {
"type": "string"
}
......@@ -69,11 +75,6 @@
"services": {
"description": "The third party sites this server can connect to via their application API.",
"type": "object",
"additionalProperties": false,
"required": [
"inbound",
"outbound"
],
"properties": {
"inbound": {
"description": "The third party sites this server can retrieve messages from for combined display with regular traffic.",
......@@ -100,15 +101,10 @@
"usage": {
"description": "Usage statistics for this server.",
"type": "object",
"additionalProperties": false,
"required": [
"users"
],
"properties": {
"users": {
"description": "statistics about the users of this server.",
"type": "object",
"additionalProperties": false,
"properties": {
"total": {
"description": "The total amount of on this server registered users.",
......@@ -139,11 +135,23 @@
}
}
},
"metadata": {
"description": "Free form key value pairs for software specific values. Clients should not rely on any specific key present.",
"type": "object",
"minProperties": 0,
"additionalProperties": true
"otherFeatures": {
"description": "Other features of the server.",
"type": "array",
"minItems": 0,
"items": {
"type": "object",
"properties": {
"name": {
"description": "The name of the feature",
"type": "string"
},
"version": {
"description": "The version of the feature.",
"type": "string"
}
}
}
}
}
}
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