Tent v0.3-WIP Documentation

Note well: There is no guarantee of API stability until Tent v1.0.

Please contribute by making Pull Requests and Issues on the GitHub repository.

Post Types

Data is stored in Tent as posts. Posts, like files, are typed. There are a small number of post types specified by the protocol that Tent servers use. Developers are free to create new post types for content/data storage. The list of content post types on this page contains some common types.

Protocol Posts

Meta

https://tent.io/types/meta/v0

Every entity has a meta post, it is retrieved during discovery by apps and servers. Some of the servers[].urls members are Level 1 URI Templates as defined in RFC 6570.

When selecting a server to contact, sort the servers by servers[].preference, preferring lower numbers over higher. If multiple servers have the same preference, make a random selection. If server errors are encountered and there is more than one server listed, another should be selected.

Changing the entity field triggers a change of the entity identifier that the server represents. The previous entity must be added to the previous_entities list in the same request.

All entities notified of this change must rewrite their posts with the updated entity and add an original_entity parameter where applicable. This applies to the post entity as well as entities used in mentions, version parents, groups and permissions.

Modified meta posts are sent to all relationships and apps regardless of subscriptions.

Property Required Type Description
entity Required String The URI of the entity that the meta post describes.
previous_entities Optional Array of Strings Previous URIs used to identify the entity.
profile Optional Object Public information about the entity.
profile.name Optional String The entity’s name or pseudonym.
profile.bio Optional String Biography/self-description of entity.
profile.website Optional String The entity’s primary website.
profile.location Optional String The entity’s physical location.
servers Required Array of Objects The servers that represent the entity.
servers[].version Required String The Tent version that the server supports.
servers[].preference Required Integer Indicates the preference to be used when choosing a server to contact. 0 is the most preferred.
servers[].urls Optional Object The URLs for this server’s Tent API endpoints.
servers[].urls.oauth_auth Required String The endpoint for the OAuth 2.0 Authorization Request.
servers[].urls.oauth_token Required String The endpoint for the OAuth 2.0 Token Request.
servers[].urls.posts_feed Required String The endpoint that serves lists of posts.
servers[].urls.new_post Required String The endpoint used to create new posts that don’t have an identifier assigned.
servers[].urls.post Required String The endpoint used to retrieve and update a single post. The {entity} and {post} variables must be replaced with the URL parameter encoded entity URL and post identifier respectively.
servers[].urls.post_attachment Required String The endpoint that redirects to an attachment URL, used to download an attachment when the digest is unspecified. The {entity}, {post}, and {name} variables must be replaced with the URL-encoded publishing entity URL, post identifier, and attachment name respectively.
servers[].urls.attachment Required String The endpoint used to retrieve an attachment given a hex-encoded digest. The {entity} and {digest} variables must be replaced with the URL-encoded publishing entity URL and attachment digest respectively.
servers[].urls.batch Required String The endpoint used to make batch requests to the server.
servers[].urls.server_info Required String The endpoint where metadata specific to the server is available.
servers[].urls.discover Required String The endpoint that performs discovery on any given entity. The {entity} varible must be replaced with the URL-encoded entity to perform discovery on.

Credentials

https://tent.io/types/credentials/v0

Property Required Type Description
hawk_key Required String Hawk key identifier.
hawk_algorithm Required String Hawk algorithm.

Relationship

https://tent.io/types/relationship/v0

Subscription

https://tent.io/types/subscription/v0

Property Required Type Description
type Required String Subscribed type.

Delivery Failure

https://tent.io/types/delivery-failure/v0

Property Required Type Description
entity Required String Entity uri of recipient
status Required String Intent of delivering server to retry or not. Must be set to permanent or temporary.
reason Optional String Reason for failure. Must be set to one of unreachable, discovery_failed, relationship_failed, or delivery_failed.

Delivery failure posts indicate delivery to a mentioned recipient was not successful. The post for which delivery failed must be in the refs and mentions arrays of the delivery failure post (entity, post, type, and version) and it’s type (excluding fragment) must be the fragment of the delivery failure post.

Delete

https://tent.io/types/delete/v0

Delete posts indicate posts that were deleted via one or more refs of posts or versions published by the same entity.

App

https://tent.io/types/app/v0

Property Required Type Description
name Required String The name of the app.
description Optional String The description of the app.
url Required String The URL for the website of the app.
redirect_uri Required String The URL that will be used as OAuth redirect_uri.
notification_url Optional String The URL where post notifications will be delivered.
notification_types Optional Array of Strings The list of type URIs that the app wants to receive notifications about.
types Optional Object The list of type URIs that the app wants access to.
types.read Optional Array of Strings The list of type URIs that the app wants to read.
types.write Optional Array of Strings The list of type URIs that the app wants to read and modify.
scopes Optional Array of Strings The list of requested scopes.

App Authorization

https://tent.io/types/app-auth/v0

Property Required Type Description
types Required Object List of authorized type uris.
types.read Required Array of Strings List of type URIs authorized for reading.
types.write Required Array of Strings List of type URIs authorized for reading and writing.
scopes Required Array of Strings List of authorized scopes.

Content Posts

Only the protocol post types above are required by Tent. The post types below are used by some developers in their apps. Developers are not required to use existing content post types and can create new post types at any time. However, please note that for apps to be compatible, they must use the same content post types.

Status

https://tent.io/types/status/v0

Status is Tent’s take on microblogging. Messages contain up to 256 characters of text and optionally have a location.

Reply fragment

Status posts that are replies to another status post (mentioning one or more posts) should set the fragment to reply: https://tent.io/types/status/v0#reply and ref the mentioned post(s).

Markdown

Status posts support a limited variant of Markdown, known as “Tent-flavored Markdown”, in the text.

Inline Mention

^[name](0) is the syntax used to reference an entity. name is the display text and 0 is the index of the mention in the mentions array.

{
  // ...
  "mentions": [
    {
      "entity": "https://jesse.tent.is"
    },
    {
      "entity": "https://daniel.tent.is"
    }
  ],
  "content": {
    "text": "Hey ^[Jesse](0) and ^[Daniel](1)!"
  }
}
Span Elements

A limited set of the Markdown-style span element syntax is supported:

  • link [link](https://example.com)
  • italic _italic_
  • bold *bold*
  • code `code`
  • strikethrough ~strikethrough~

Backslash is used to escape literals (\*foobar).

Line breaks are treated literally:

Some text\n\nSome more text becomes

Some text

Some more text

(rendered with the empty line.)

Some text\nSome more text becomes

Some text
Some more text

Counting Characters

The maximum length of the text is 256 Unicode characters (also known as code points). Applications may want to normalize the text using Unicode Normalization Form C to avoid surprising users (for example café is 5 characters, while café is 4).

Schema

Property Required Type Description
text Required String The status text.
location Optional Object The Latitude/Longitude Point from which the instance originated. Number format: [ "-" ] 1*DIGIT [ "." 1*DIGIT ]
location.latitude Required String The stringified floating point latitude.
location.longitude Required String The stringified floating point longitude.
location.altitude Optional String The stringified floating point number of meters above sea level.

Repost

https://tent.io/types/repost/v0

A repost is a post that points to a post published by another entity.

The post must include a mention and a single ref of the original post. The type fragment must be set to the type of the original post.

Photo

https://tent.io/types/photo/v0

A photo post contains a single photo and metadata about it.

Property Required Type Description
location Optional Object The Latitude/Longitude Point from which the instance originated. Number format: [ "-" ] 1*DIGIT [ "." 1*DIGIT ]
location.latitude Required String The stringified floating point latitude.
location.longitude Required String The stringified floating point longitude.
location.altitude Optional String The stringified floating point number of meters above sea level.
caption Optional String A caption that describes the photo.
artist Optional Object The artist who created the image.
artist.name Optional String The name of the artist.
artist.entity Optional String The entity URL of the artist.
filename Optional String The name of the original file.
film_speed Optional String The exposure index of digital photos or the ASA rating of film speed.
focal_length Optional String The focal length of the system in millimeters as a stringified floating point number.
exposure Optional Object Details about the photo exposure.
exposure.bias Optional String The exposure bias in APEX units as a stringified floating point number.
exposure.mode Optional String The exposure mode. One of auto, manual, bracket.
exposure.time Optional String The number of seconds the shutter was open for as a stringified floating point number.
exposure.program Optional String The class of program used to set the exposure. One of manual, program, aperture, shutter, creative, action, portrait, landscape, bulb.
aperture Optional String The f-number (ratio of focal length to effective aperture diameter) as a stringified floating point number.
flash Optional Object The flash firing details.
flash.fired Optional Boolean Indicates whether the flash fired.
flash.mode Optional String The flash mode. One of firing, suppression, auto.
white_balance Optional Boolean Indicates the white balance mode. true is auto, false is manual.
metering_mode Optional String The metering mode. One of Average, CenterWeightedAverage, Spot, MultiSpot, Pattern, Partial, other.
camera Optional Object Camera details.
camera.make Optional String The manufacturer of the camera.
camera.model Optional String The model identifier of the camera.
lens Optional Object Lens details.
lens.make Optional String The manufacturer of the lens.
lens.model Optional String The model identifier of the lens.
lens.focal_length Optional Object The focal range.
lens.focal_length.min Optional String The minimum focal length in millimeters as a stringified floating point number.
lens.focal_length.max Optional String The maximum focal length in millimeters as a stringified floating point number.
lens.aperture Optional Object The aperture range.
lens.aperture.min Optional String The minimum f-number as a stringified floating point number.
lens.aperture.max Optional String The maximum f-number as a stringified floating point number.
resolution Optional Object The resolution of the photo.
resolution.width Required Integer The width resolution in dots per inch.
resolution.height Required Integer The height resolution in dots per inch.
dimensions Optional Object The dimensions of the photo.
dimensions.width Required Integer The width in pixels.
dimensions.height Required Integer The height in pixels.
timestamp Optional Integer The date/time when the image was taken in milliseconds since the Unix epoch.
orientation Optional String The orientation of the photo. One of horizontal, mirror_horizontal, mirror_vertical, 90, 180, 270, mirror+90, mirror+270

Album

https://tent.io/types/album/v0

An album groups photo posts, and has one ref for each included photo.

Property Required Type Description
title Required String The title of the album.
description Optional String The description of the album.
cover Optional Object The cover photo of the album, this post must also be included in the refs array.
cover.entity Optional String The publishing entity of the cover photo post.
cover.post Required String The unique identfier of the cover photo post.
cover.version Optional String The version identifier of the cover photo post.

Essay

https://tent.io/types/essay/v0

An Essay is a piece of writing.

Property Required Type Description
title Optional String The title of the post.
excerpt Optional String An excerpt of the post in HTML format to be displayed when the whole post is not available.
body Required String The body of the post in HTML format. Renderers may sanitize some HTML.

Cursor

https://tent.io/types/cursor/v0

A cursor indicates an entity’s position in the feed and must have a single post ref. The fragment must be set to a URI identifying the cursor type.

Tag

https://tent.io/types/tag/v0

A tag is mentioned by other posts in order to categorize them.

Property Required Type Description
name Required String Name of tag.
description Optional String Description of tag.

Favorite

https://tent.io/types/favorite/v0

A favorite references another post.

The post must include a ref and may include a mention of the original post. The type fragment must be set to the type of the original post.

Property Required Type Description
note Optional String Text describing the favorite.