Shared Definitions
app.certified.defs
Overview#
app.certified.defs holds small object definitions that other Certified and Hypercerts lexicons reuse. It defines no record type: nobody publishes a record with this NSID. Its definitions appear inside other records.
It has two definitions, each a wrapper around one identifier:
didnames an account by its DID.recordSubjectnames a record by its AT-URI, without a CID, so the reference keeps pointing at the record as it is updated.
Together with com.atproto.repo.strongRef, which names a record and pins one version with a CID, these are the ways records refer to accounts and other records. For when to pin a version and when not to, see Records That Change Over Time in the Guide.
The signature definitions are a separate document; see Signatures.
Where the definitions are used#
did is an object rather than a plain string so it can be one option in a union, next to a strong reference. It appears in:
- Badge award
subject: the account a badge is awarded to, as an alternative to a strong reference to a record. - Funding receipt
fromandto: the sender or recipient of funds, as an alternative to free text or a strong reference. - Badge definition
allowedIssuers: accounts allowed to award the badge. - Evaluation
evaluators: the accounts that performed the evaluation. - Measurement
measurers: the accounts that performed the measurement.
recordSubject appears in:
- Entity follow
subject: the record being followed.
Schema#
Lexicon version: 2.1.0 · View the schema
Definitions#
did
A Decentralized Identifier (DID) string.
| Property | Type | Required | Description |
|---|---|---|---|
did | string (did) | Yes | The DID string value. maxLength: 256 |
recordSubject
A subject that is a record, referenced by AT-URI. The URI must use the DID form (not handle form) and deliberately carries no CID: it references the record's identity, not a specific version, so references made against it survive updates to the record.
| Property | Type | Required | Description |
|---|---|---|---|
uri | string (at-uri) | Yes | AT-URI (DID form) of the record being followed. Schema validation enforces only general at-uri syntax; writers MUST supply a full record URI (did authority, collection, and rkey — not a handle authority or a partial URI), and consumers (AppView/indexer) are expected to reject or skip subjects that do not conform. |
Examples#
In a union position, such as a badge award's subject, a did object carries a $type:
{
"subject": {
"$type": "app.certified.defs#did",
"did": "did:plc:4yyb5gyoxl3sqdlqrvuxshkp"
}
}
In a plain reference position, such as an evaluation's evaluators, there is only one possible type, so the objects carry just the DID:
{
"evaluators": [
{ "did": "did:plc:ragtjsm2j2vknwkz3zp4oxrd" },
{ "did": "did:plc:ewvi7nxzyoun6zhxrhs64oiz" }
]
}
A recordSubject in an entity follow, naming a project collection without pinning a version:
{
"subject": {
"$type": "app.certified.defs#recordSubject",
"uri": "at://did:plc:4yyb5gyoxl3sqdlqrvuxshkp/org.hypercerts.collection/3lx2m4q7trs2b"
}
}
Rules and best practices#
- Include
$typein union positions. Badge awardsubjectand funding receiptfromandtoare unions, so each value names its variant. In plain reference arrays likeevaluators,$typeisn't needed; readers typically accept the object with or without it. - A DID in a record is the author's claim. Naming an account as an evaluator, measurer, or funding recipient doesn't mean that account agreed or took part. The schema checks DID syntax only, not that the DID resolves or that the account did anything. An acknowledgement from the named account is how it can confirm.
- Don't shorten a DID to fit.
didhas a maximum length of 256. If an account's DID is longer, leave an optional property out or use another variant of the union rather than writing a truncated value. - Use a full, DID-form record URI in
recordSubject. Writeat://<did>/<collection>/<rkey>. Handle-based and partial URIs pass schema validation, but indexers typically skip them. A URI with only a DID names an account, which belongs in a follow, not an entity follow. - Choose the reference by what it's about. Use
recordSubjectwhen the relationship should follow a record across edits, as a follow does. Use a strong reference when it concerns the version seen, as an evaluation or a like does. Usedidwhen the subject is the account itself. - Don't treat an account and its records as the same subject. A badge awarded to an account and a badge awarded to one of its records are different statements. Apps gathering everything said about an account check each form its records can use.
Related#
- Signatures: the shared
signaturesdefinitions. - Follows: uses
recordSubject. - Badge Award, Badge Definition, Evaluation, Measurement, and Funding Receipt: use
did. - Hypercerts Shared Definitions: definitions shared across Hypercerts records.
- Guide: Records That Change Over Time, A Shared Language.