View raw

Profile

app.certified.actor.profile

Overview#

A profile is how an account introduces itself to people: a display name, a short description, pronouns, a website, an avatar, and a banner. Every record in Hypercerts belongs to an account identified by a DID, and the profile gives readers a more readable way to see who stands behind it.

The profile is written by the account it describes. It tells you what the account says about itself, not that anyone has checked it. For how profiles fit into deciding what to trust, see Trust and Recognition in the Guide.

The schema belongs to the app.certified namespace. Certified accounts use it, and any AT Protocol application can read or write it.

How it's used#

  • One profile per account. The record key is literal:self, so an account holds at most one profile, at at://<did>/app.certified.actor.profile/self. Applications can fetch it directly from the DID without listing records. Updating the profile replaces that record.
  • People and organizations both use it. The schema doesn't distinguish between individual and organizational accounts. An organization publishes a profile for its name and images, and adds an organization record for structural details such as legal form and founding date.
  • Applications show it next to records. When displaying an activity, an evaluation, or a badge award, an application looks up the publisher's profile to show a name and avatar instead of a bare DID.

Only createdAt is required. A profile with just a display name is already useful.

Schema#

Record key: literal:self · Lexicon version: 1.6.0 · View the schema

Required properties#

PropertyTypeDescription
createdAtstring (datetime)Client-declared timestamp when this record was originally created

Optional properties#

PropertyTypeDescription
displayNamestringDisplay name for the account. For an organization, the public-facing name it uses in communications; a different registered legal name belongs in app.certified.actor.organization legalName. maxLength: 640 maxGraphemes: 64
descriptionstringFree-form profile description text. maxLength: 2560 maxGraphemes: 256
pronounsstringFree-form pronouns text. maxLength: 200 maxGraphemes: 20
langsarray of string (language)Human language(s) of this record's text fields, as BCP-47 language tags (e.g. 'es', 'pt-BR'); up to three for mixed-language text. Set by the writing app from the text the author wrote, with the author able to correct it; never from the interface language or a profile preference alone. A hint for readers, not a guarantee: consumers must not hide a record because it lacks this field. maxItems: 3
websitestring (uri)Account website URL
avatarunion: org.hypercerts.defs#uri, org.hypercerts.defs#smallImageSmall image to be displayed next to posts from account. AKA, 'profile picture'. Clients crop it to a square or circle, so an organization should use its brandmark (the symbol without the name); the full logo belongs in app.certified.actor.organization logo.
bannerunion: org.hypercerts.defs#uri, org.hypercerts.defs#largeImageLarger horizontal image to display behind profile view.
signaturesapp.certified.signature.defs#listOptional cryptographic signatures attesting to this record's content.

Example#

The profile of a community energy cooperative, with an uploaded avatar and a banner hosted on its website:

JSON
{
  "$type": "app.certified.actor.profile",
  "displayName": "Millbrook Community Energy",
  "description": "A community-owned cooperative installing and running solar power for Millbrook village.",
  "website": "https://millbrookenergy.example.org",
  "avatar": {
    "$type": "org.hypercerts.defs#smallImage",
    "image": {
      "$type": "blob",
      "ref": { "$link": "bafkreibmbrvzxhfz5vldq37maocqy7g4xqkev7yn74giwovqpztyahtsli" },
      "mimeType": "image/png",
      "size": 48213
    }
  },
  "banner": {
    "$type": "org.hypercerts.defs#uri",
    "uri": "https://millbrookenergy.example.org/media/village-hall-roof.jpg"
  },
  "createdAt": "2026-02-10T08:30:00.000Z"
}

Rules and best practices#

  • Take display details from the profile. An account's name, short description, and images belong here. The organization record deliberately has no name or avatar, so don't derive a display name from it.
  • Fall back to an identifier. Many accounts have no profile or no displayName. Show the handle or DID instead, and keep treating the account's records as usable.
  • A profile is self-description, not verification. Display names aren't unique, and anyone can choose a name that resembles another account's. Don't show a profile's name or website as if it had been confirmed. Where it matters, show the handle next to the name, and rely on badges or other signals from recognized issuers for confirmation.
  • A website is a claim. website states which site the account associates with itself; it doesn't prove the account controls that site. A custom domain handle is a stronger signal; see Account & Identity Setup.
  • Handle both image forms. avatar and banner each accept either an uploaded image blob or a URI. Applications that display profiles need to support both. A blob is stored in the account's repository and identified by its content hash; a URI points elsewhere and its content can change without the record changing.
  • Profiles are public. Anyone can read everything in the record. Keep personal details to what the account wants to share publicly.
  • Declare the text's language with langs. List up to three BCP-47 tags (such as es or pt-BR) for the language the author actually wrote in, and let the author correct it. Don't derive it from the interface language or a profile preference. Readers treat it as a hint: don't hide a record because it has no langs.