Bluesky pinned posts clash with a field third-party apps already used

What this means for you

In October 2024 Bluesky added pinned posts, a post that stays at the top of your profile. A few other Bluesky apps had already built the same thing in a slightly different way, and the two clashed, so some people saw errors. If you pin posts from a non-Bluesky app, check that your pin still shows up correctly in the Bluesky app.

The details

• The change: app version 1.92 (October 10, 2024) declared pinnedPost on app.bsky.actor.profile as a com.atproto.repo.strongRef, an object with both the record URI and its CID.
• The collision: since April 2024, clients including Klearsky, Tokimeki and Hagoromo had written pinnedPost as a plain URL string. Under the new schema those records became "invalid", and records valid under the new schema could be invalid for the older software.
• Bluesky's position: the schema for app.bsky.* is controlled by Bluesky (authority follows the NSID's domain). Off-schema fields are allowed and passed through, but Bluesky does not see inserting fields into other parties' records "as a reliable or responsible practice in the long run."
• Recommended pattern: a sidecar record in your own namespace, fetched alongside the original. For records with fixed keys (like self) or TID keys (like posts), use the same record key so a simple GET finds it. app.bsky.feed.threadgate uses this pattern for posts.
• If you must extend: use a long, unique prefix or a full NSID, for example app.graysky.pinnedPost or grayskyPinnedPost, not pinnedPost or extPinnedPost.
• Also noted: clarified validation for the unknown and union Lexicon types and updated schema validation when records are created at PDS instances.

What to do next

• Business owners: If you pin a post, check it appears pinned in the Bluesky app.
• Marketers and agencies: Nothing, unless a client's pinned post looks wrong; re-pin it in the Bluesky app.
• Developers: Write pinnedPost as a strongRef, never write custom fields with generic names into app.bsky.* records, and move extension data to sidecar records.