Skip to content
View raw

Organization

app.certified.actor.organization

Overview#

An organization record adds organization-specific details to an account: its legal or operational form, reference links, where it is based, when it was founded, and a longer description of its mission or history. It complements the profile, which holds the account's name, short description, and images.

Like the profile, the record is written by the account it describes. It is how an account presents itself as an organization, not evidence that the organization is registered or that the details are accurate. For how to weigh self-descriptions against other signals, see Trust and Recognition.

How it's used#

  • One record per account. The record key is literal:self, so an account holds at most one organization record, at at://<did>/app.certified.actor.organization/self. It sits next to the profile at the same key in a different collection; fetching one doesn't return the other.
  • Profile plus organization. An organizational account publishes a profile for how it appears everywhere, then an organization record for the extra details an organization page or directory shows.
  • Links to a location. location is a strong reference to a location record describing where the organization is based.
  • Directories and discovery. Platforms that list organizations can use organizationType to filter and visibility to decide whether to include the account in public listings.

Only createdAt is required. Add the fields your users will actually look at.

Schema#

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

Required properties#

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

Optional properties#

PropertyTypeDescription
legalNamestringThe organization's registered legal name. The public-facing name belongs in app.certified.actor.profile displayName. maxLength: 2560 maxGraphemes: 256
logounion: org.hypercerts.defs#uri, org.hypercerts.defs#smallImageThe organization's full logo: a wordmark, or a combination mark pairing the symbol with the name. Used where the logo appears without the name beside it, such as partner listings or badge displays. Prefer a horizontal image with a transparent background (PNG or WebP). The square symbol alone (brandmark) belongs in app.certified.actor.profile avatar, which is cropped to a square or circle.
publicEmailstringA contact email address the organization wants shown publicly (e.g. 'hello@example.org'). Records are public, so never put a personal or internal address here. maxLength: 254
organizationTypearray of stringLegal or operational structures of the organization (e.g. 'nonprofit', 'ngo', 'government', 'social-enterprise', 'cooperative'). maxItems: 10 item maxLength: 128 item maxGraphemes: 100
urlsarray of urlItemAdditional reference URLs, each with a display label: social media profiles, contact pages, donation links, and similar. The organization's main website belongs in app.certified.actor.profile website, not here.
locationstrongRef → app.certified.locationA strong reference to the organization's primary location: where it is based, and where it is shown when a map displays one point per organization. The referenced record must conform with the lexicon app.certified.location. Because a strong reference pins a specific version (CID) of that record, update this reference whenever the location record is edited. Further locations go in additionalLocations.
additionalLocationsarray of strongRef → app.certified.locationStrong references to further locations where the organization operates, such as branches, outlets, or field offices. Excludes the primary location, which is in location; do not repeat it here. Each referenced record must conform with the lexicon app.certified.location. As with location, update a reference whenever its record is edited. maxItems: 1000
foundedDatestring (datetime)When the organization was established. Stored as datetime per ATProto conventions (no date-only format exists). Clients should use midnight UTC (e.g., '2005-01-01T00:00:00.000Z'); consumers should treat only the date portion as canonical.
longDescriptionunion: org.hypercerts.defs#descriptionString, Leaflet linear document, strongRefLong-form description of the organization, such as its mission, history, or detailed project narrative. An inline string for plain text or markdown, a Leaflet linear document record embedded directly, or a strong reference to an existing document record.
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
visibilitystringControls whether the organization or project is publicly discoverable on platforms that honor this setting. Known values: public, unlisted.
signaturesapp.certified.signature.defs#listOptional cryptographic signatures attesting to this record's content.

Definitions#

urlItem

A labeled URL reference.

PropertyTypeRequiredDescription
urlstring (uri)YesThe URL. maxLength: 10000 maxGraphemes: 2048
labelstringNoOptional human-readable label for this URL (e.g. 'Donation page'). maxLength: 640 maxGraphemes: 64

Example#

The organization record for the community energy cooperative whose profile shows its name and avatar:

JSON
{
  "$type": "app.certified.actor.organization",
  "organizationType": ["cooperative", "social-enterprise"],
  "urls": [
    { "url": "https://millbrookenergy.example.org/join", "label": "Become a member" },
    { "url": "https://millbrookenergy.example.org/reports", "label": "Annual reports" }
  ],
  "location": {
    "uri": "at://did:plc:4yyb5gyoxl3sqdlqrvuxshkp/app.certified.location/3lwq6d2nf7s2c",
    "cid": "bafyreibwbgsy3r6nexk2zvxy4hhqpzgpuqdlw6ayh3ktkhqw3nxgvcqf7i"
  },
  "foundedDate": "2019-04-01T00:00:00.000Z",
  "longDescription": {
    "$type": "org.hypercerts.defs#descriptionString",
    "value": "Millbrook Community Energy is a member-owned cooperative. It finances, installs, and maintains solar arrays on community buildings and reinvests surplus income in local energy-saving projects."
  },
  "visibility": "public",
  "createdAt": "2026-02-10T08:32:00.000Z"
}

Rules and best practices#

  • Keep display details on the profile. The organization record has no name or avatar. Applications take those from the profile, so an organizational account without a profile shows up as a bare handle or DID.
  • The record only describes its own account. There is no subject field: the record is always about the account whose repository holds it. It can't be used to describe another organization.
  • Self-declared, not registered. Legal form, founding date, and links are easy to mistake for a registry entry. Present them as the organization's own statements. A badge from a recognized issuer is the way to show that something has been checked.
  • organizationType is free text. Examples in the schema include nonprofit, ngo, government, social-enterprise, and cooperative, but there is no fixed list. Prefer common lowercase terms so other applications can match them, and when reading, compare case-insensitively and keep values you don't recognize.
  • Write foundedDate as midnight UTC. The field is a datetime because AT Protocol has no date-only format. Use a value like 2019-04-01T00:00:00.000Z and read only the date part, without converting time zones, so the date doesn't shift by a day.
  • location is where the organization is based. It is not the site of the organization's work. Activities, collections, and other records carry their own locations. Because it is a strong reference, it points to one version of the location record; update the reference if you revise that record.
  • Link labels are chosen by the account. A urls entry pairs a URL with an optional label written by the same account. Show the destination host when rendering a labeled link so people know where it goes.
  • visibility is a preference. unlisted asks platforms that honor the setting to leave the organization out of directories and search. The record is still public and readable by anyone.
  • Pick a longDescription form. Use the inline description string for plain text or markdown. Use an embedded Leaflet document for structured content, or a strong reference to an existing document record. Applications that can't render a form can fall back to the profile's description.
  • 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.