View raw

Badge Definition

app.certified.badge.definition

Overview#

A badge definition describes a form of recognition: what the badge is called, what kind of recognition it represents, what it means, and optionally which accounts may award it. Publishing a definition gives the badge to nobody. Individual awards are separate badge award records that point to the definition.

Badges let a network or certifier recognize an account or a record, such as a project. The definition explains the recognition being offered; the award connects it to a recipient; a response lets the recipient accept or reject it. See Trust and Recognition in the Guide.

How it's used#

  • A network defines the badge once. A certification network, community, or program publishes a definition for each badge it offers, such as a certification for installations that passed its review.
  • Awards point to it. Each award references the definition with a strong reference, so one definition serves many awards and applications can show a consistent title, description, and icon.
  • The allowlist names the issuers. allowedIssuers lists the DIDs whose awards count for this badge. Applications compare it with the account that published each award.

title, badgeType, and createdAt are required.

Schema#

Record key: tid · Lexicon version: 1.6.0 · View the schema

Required properties#

PropertyTypeDescription
badgeTypestringCategory of the badge. Values beyond the known set are permitted. maxLength: 100 Known values: endorsement, verification, participation, certification, affiliation, recognition.
titlestringHuman-readable title of the badge. maxLength: 256
createdAtstring (datetime)Client-declared timestamp when this record was originally created

Optional properties#

PropertyTypeDescription
iconblobIcon representing the badge, stored as a blob for compact visual display. maxSize: 1048576 accept: image/png, image/jpeg, image/webp, image/svg+xml
descriptionstringOptional short statement describing what the badge represents. maxLength: 5000 maxGraphemes: 500
allowedIssuersarray of app.certified.defs#didOptional allowlist of DIDs allowed to issue this badge. If omitted, anyone may issue it. maxItems: 100
signaturesapp.certified.signature.defs#listOptional cryptographic signatures attesting to this record's content.

Example#

A solar network defining a certification it awards to installations it has reviewed, with itself as the only allowed issuer:

JSON
{
  "$type": "app.certified.badge.definition",
  "badgeType": "certification",
  "title": "Certified Community Solar Installation",
  "description": "Awarded to installations that passed the network's independent review of design, safety, and first-year production data.",
  "icon": {
    "$type": "blob",
    "ref": { "$link": "bafkreie5bykzebifztqv2qvkx36h3qsiai7j54w2ujjadjsrgjkatlu4pm" },
    "mimeType": "image/png",
    "size": 20514
  },
  "allowedIssuers": [
    { "did": "did:plc:k3nq7wz2vbx5rmt4ydh6pcsa" }
  ],
  "createdAt": "2026-05-04T09:00:00.000Z"
}

Rules and best practices#

  • Check issuers against allowedIssuers. When the list is present, only awards published by a listed DID count as this badge. The schema doesn't enforce this: an award from any account can reference any definition, so applications compare the DID of the repository holding the award with the list. Never take the issuer from a field inside the award.
  • An omitted list means anyone may issue. Without allowedIssuers, awards from any account reference the badge equally, so the badge only means something combined with who issued it. The schema doesn't say what an empty list means; omit the field rather than writing an empty array.
  • The name and icon alone tell you little. Anyone can publish a definition with any title, including one that copies another network's badge. Applications decide which definition publishers and issuers they recognize.
  • Pick the closest badgeType. Known values are endorsement, verification, participation, certification, affiliation, and recognition. Other values are allowed, but applications may not group them with the known types.
  • Say what the badge means in description. State the criteria for awarding it, so readers can judge what an award represents.
  • Don't change a badge's meaning in place. Awards pin the version of the definition they were made against. Fix wording or an icon by editing, but if the criteria change, publish a new definition so earlier awards keep their original meaning.
  • Deleting a definition doesn't withdraw awards. Awards that reference a deleted definition still exist in their issuers' repositories. Applications typically show them as an unidentified badge from that issuer.