Annotations

• Annotation Fields
• Limits
• Creating, Updating and Deleting
• Retrieving
• Displaying
• Namespaces
• Documenting annotations
• Replacement values

Annotation Fields

{
  "type": "com.example.awesome",
  "value": {
    "annotations work": "beautifully"
  }
}

Limits

• Each object (User, Post, Channel, Message, File) is allowed at most 8192 bytes worth of annotations (in total, when serialized as JSON). This value can be retrieved from the Configuration endpoint.
• Post and Message annotations are immutable and can only be added at creation time.
• A Post or Message can have multiple annotations of the same “type”.
• User and Channel annotations are mutable and can be updated at any time.
• Because they are mutable, a User or Channel object can only have one annotation of each “type”.
• User annotations are meant to provide more information about the user. They are not meant to be an arbitrary data store for apps.
• Some annotations are read-only and will be ignored or rejected if you try to write to them.

Creating, Updating and Deleting

For Posts, Messages, Channels, and Files, you can create annotations when you create the object. You must pass JSON objects that include annotations matching the above schema. Please see the documentation for creating Posts, Messages, Channels, or Files.

To add or update User or Channel annotations, you update a User’s profile, update a Channel, or update a File and pass in the annotations you want to add or update. To delete an annotation, omit the value key for the annotation type you want to delete. For example, to delete a user’s blog url, specify:

{
  "type": "net.app.core.directory.blog"
}

Retrieving

Since annotations can be up to 8192 bytes, they are never included by default. When making a request for Users, Posts, Channels, Messages, or Files, you can use the parameter include_annotations=1 to receive all applicable annotations. When requesting Users or Posts you can use include_user_annotations=1 or include_post_annotations=1 to include just those annotations. When requesting Channels or Messages you can use include_channel_annotations=1 or include_message_annotations=1 to include just those annotations. When requesting Files you can use include_file_annotations=1 or include_user_annotations=1 to include just those annotations.

Displaying

You are free to choose if and how you render annotations. Be very careful when consuming this data and do not assume that it follows a specific schema. Treat data in annotations as untrusted data. Program defensively: your app should not crash or otherwise throw an error if it receives a string where there is usually a dictionary, etc.

Namespaces

App.net will coordinate with the community to define schemas for common annotation formats. They will live under the net.app.core.* namespace. This is the only restricted annotation namespace for the type field. Any annotation in this namespace must be validated by the API against a published schema. Outside of this namespace, developers should create annotations in either the net.app.[username] namespace or a reversed-domain namespace of their choosing.

In the value of any annotation (including non-core annotations), we treat any key that starts with +net.app.core.* as a special replacement value. They will be validated against a schema just like the core annotations.

Documenting annotations

To foster collaboration and adoption, we’ve set up a github repository for documenting annotations. To discuss annotations, please use the associate issue tracker. For more information on submitting / updating documentation please review the README.

Core annotations

Annotations that are considered particularly useful and/or well defined may be promoted to “core”. As opposed to general annotations, core annotations are validated server-side to match their documented schemas.

We currently define the following core annotations:

If you are interested in proposing another annotation, please open an issue.

Developers are encouraged to create annotations for data not well represented here. If possible, care should be taken not to overlap with existing annotations. Annotations designed to address edge-cases in well-known annotations should include both the well-known annotation and only the augmented parts in the enhancing annotation.

Replacement values

When App.net processes annotation values, any value with a key that starts with +net.app.core.* will be rewritten based on the core schemas defined below. For example, when attaching a File to a Post, you might send App.net the following annotation:

{
  "type": "com.example.my_own_annotation",
  "value": {
    "+net.app.core.file": {
      "file_id": "1",
      "format": "url",
      "file_token": "12345abcdef"
    },
    "foo": "bar"
  }
}

As explained in the schema for the net.app.core.file value, this annotation will be rewritten when the Post is requested from the API:

{
  "type": "com.example.my_own_annotation",
  "value": {
    "file_id": "1",
    "file_token": "12345abcdef",
    "foo": "bar",
    "url": "http://example.com/link_to_file",
    "url_expires": "2013-01-25T03:00:00Z"
  }
}

We currently define the following replacement values in annotations: