Earthstar application formats
Application formats are ways of representing certain kinds of organised data (e.g. profile info, chat messages, server settings) as Earthstar documents.
For example, a user's display name should be kept on a document with the path
/about/1.0/displayName, or their avatar at
Having coordinated standards for how to store and retrieve documents means users' data can be reused across many different applications (e.g. the same avatar across many apps).
It also makes it easier to build different clients acting on the same kinds of data — e.g. chatrooms, calendars, or lists — which will hopefully counteract centralisation around slow-moving, hard-to-modify monolithic clients.
- About. Personal information associated with author keypairs.
- Server settings. Configure which shares an Earthstar server should host.
Contributing a format
Each application format must have a separate namespace, e.g.
This namespace must be used as the first path segment of any paths related to the application format:
Each application format's second path segment must be a version number, made up
must be positive integers.
Valid version numbers:
Invalid version numbers:
A separate file should be used for each version of the application format in
this repo, e.g.
/application formats/my_application format/1.0.ts
Determining minor or major version updates
If a application format is updated in such a way where all documents created by
previous versions of the application format are still included in the new
application format, the new version is a minor update (e.g.
If a application format is updated in such a way where documents created or read
by the previous version of the application format are no longer included in the
new application format, the new version is a major update (e.g.
with breaking changes.
Application format specification
Because implementations can contain bugs and applications' needs vary, a written specification is required.
The written specification must be a markdown file with a title with with the
The specification MUST detail the application format's namespace and version.
The specification MUST describe the purpose of the application format and how documents following its application format should be interpreted.
The specification MUST describe how to author documents conformant with its
application format, e.g. how paths should be formatted, valid values for fields
An application format MAY provide a module of functions which assist in the reading and writing of application format-conformant documents.
A pull request with a valid specification should be made to the application-formats repository.