fix: widen description fields from Leaflet ref to union type

[holkexyz]

Summary

• The description field on activity, collection, and attachment was a bare ref to pub.leaflet.pages.linearDocument#main — a hard dependency on a single rich-text format that could never be widened without a breaking change.
• Now a union of descriptionString (inline plain text or markdown with optional rich-text facets) and strongRef (for any rich-text document, including Leaflet).
• Added shared descriptionString def to org.hypercerts.defs to keep the inline variant DRY across all three schemas.

Why

Leaflet is one possible rich-text backend, not the only one. By making this a union, clients can use simple inline markdown for lightweight descriptions or reference any external document format. This matches AT Protocol patterns where unions allow protocol evolution without breaking changes.

Test plan

• npm run check passes
• Generated types reflect the union change
• SCHEMAS.md is regenerated

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Description fields for activities, collections, and attachments now accept inline plain-text/Markdown, structured rich-text documents, or external references—giving more flexible display options.
• Documentation
  • Schema docs updated to describe the new multi-format description options, an inline description object (string + optional rich-text facets), and supported length constraints for inline content.

[changeset-bot]

🦋 Changeset detected

Latest commit: 06fce2c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hypercerts-org/lexicon	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Expands the description field on activity, collection, and attachment from a single Leaflet document ref into a union that allows an inline descriptionString, a Leaflet linearDocument, or a strongRef; adds the shared descriptionString definition and updates docs/diagram and a changeset.

Changes

Cohort / File(s)	Summary
Release & Docs /.changeset/description-union-type.md, SCHEMAS.md, ERD.puml	Adds changeset; updates schema docs and ERD label to reflect widened description type (removed "Leaflet ref" label in diagram).
Description Union Migration lexicons/org/hypercerts/claim/activity.json, lexicons/org/hypercerts/collection.json, lexicons/org/hypercerts/context/attachment.json	Replaces description type: "ref" (Leaflet linearDocument) with type: "union" accepting org.hypercerts.defs#descriptionString, pub.leaflet.pages.linearDocument#main, or com.atproto.repo.strongRef; updates field descriptions.
Shared Definition lexicons/org/hypercerts/defs.json	Adds descriptionString object with required value: string (maxLength/maxGraphemes) and optional facets: ref[] referencing richtext facets for inline plain-text/markdown descriptions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• edit lexicon style guide so that all union variants must be object or… #128 — Related rule/work on union variant types and object/record constraints; aligns with adding descriptionString.
• Unify project and collection schemas #75 — Previously changed collection.description to a Leaflet ref; this PR broadens that field into a union.
• Bring back "type" in the collections #80 — Directly modified collection.description to a Leaflet linearDocument ref; this PR converts that to a union including the Leaflet ref.

Suggested reviewers

• aspiers

Poem

🐰 I nibble schemas in the moonlit night,

Strings and pages now share the light.
A facet here, a doc there — what fun!
Descriptions multiplied, hopping as one.
✨📜

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: widening description fields from a single Leaflet ref type to a union type supporting multiple formats.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Lexicon Documentation Sync	✅ Passed	All modified files are properly synchronized with consistent updates across JSON lexicon files and documentation.
Lexicons Styleguide Compliance	✅ Passed	PR lexicon changes comply with AT Protocol Lexicon Style Guide; automated style checker confirms zero errors and proper union type variant references.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/description-union-type

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[aspiers]

Breaking change, but I'm fine with this in principle if everyone else is and we're confident there aren't any apps yet relying on the presence this field which would be too uncomfortable to break. As with the other breaking changes being proposed now, either we swallow the pain now or go with new NSID prefix which feels like it would create even more pain.

I would like answers to my two questions before merging though.

[s-adamantine]

Unfortunately we are locked in with this change. There are already existing apps that have data stored in this format, and changing it to a union would invalidate all previous certs.

Summary:

• We decided not to adopt this change: switching description to a union would change the stored JSON shape (adds $type), which would break all existing records and apps.
• Current 0.1 behavior is locked in: description on activity, collection, and attachment remains a leaflet linear document ref, not a union of descriptionString and strongRef.
• If we ever need another format in the future, we’ll add new optional fields (or sidecars) instead of changing the existing description type.

[s-adamantine]

Pull request reopened, we got one argument wrong.

"We decided not to adopt this change: switching description to a union would change the stored JSON shape (adds $type), which would break all existing records and apps."

The current implementation uses leaflet, which already has $type. The proposal to widen the description fields is therefore safe and non-breaking.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.changeset/widen-description-to-union.md:
- Around line 1-5: The changeset `.changeset/widen-description-to-union.md` is a
duplicate of `.changeset/description-union-type.md`; delete one of them (either
remove `.changeset/widen-description-to-union.md` or
`.changeset/description-union-type.md`) so only a single changeset describing
the widening of `description` fields to the union type remains, ensuring the
package bump for "@hypercerts-org/lexicon" appears only once in the changelog.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7d9c2df9-3f98-4005-b81b-3127a1b4fa19

📥 Commits

Reviewing files that changed from the base of the PR and between 73b0212 and 2c40ca5.

📒 Files selected for processing (8)

• .changeset/description-union-type.md
• .changeset/widen-description-to-union.md
• ERD.puml
• SCHEMAS.md
• lexicons/org/hypercerts/claim/activity.json
• lexicons/org/hypercerts/collection.json
• lexicons/org/hypercerts/context/attachment.json
• lexicons/org/hypercerts/defs.json

[coderabbitai]

🧹 Nitpick comments (1)

lexicons/org/hypercerts/claim/activity.json (1)

33-39: Clarify the inline description variant as an object, not a bare string.

org.hypercerts.defs#descriptionString is an object ({ value, facets? }), so “inline string” is misleading and can lead to invalid client payloads. Please reword this to describe the inline object shape, then mirror the same wording in the matching description fields in collection, attachment, and regenerated SCHEMAS.md.

Proposed wording tweak

-            "description": "Long-form description of the activity. An inline string for plain text or markdown, a Leaflet linear document for rich-text content, or a strong reference to an external description record."
+            "description": "Long-form description of the activity. Either an inline description object (`value` with optional `facets`) for plain text or markdown, a Leaflet linear document for rich-text content, or a strong reference to an external description record."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lexicons/org/hypercerts/claim/activity.json` around lines 33 - 39, The
current "description" union text incorrectly calls
org.hypercerts.defs#descriptionString an "inline string"; update the prose to
state that the inline variant is an object matching
org.hypercerts.defs#descriptionString (e.g., { value, facets? }) rather than a
bare string, and apply the same wording change to the "description" fields in
collection and attachment schemas; after updating the JSON schema descriptions,
regenerate SCHEMAS.md so the docs reflect the corrected object shape.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@lexicons/org/hypercerts/claim/activity.json`:
- Around line 33-39: The current "description" union text incorrectly calls
org.hypercerts.defs#descriptionString an "inline string"; update the prose to
state that the inline variant is an object matching
org.hypercerts.defs#descriptionString (e.g., { value, facets? }) rather than a
bare string, and apply the same wording change to the "description" fields in
collection and attachment schemas; after updating the JSON schema descriptions,
regenerate SCHEMAS.md so the docs reflect the corrected object shape.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d10699cb-bc24-4419-8204-729139e8fd72

📥 Commits

Reviewing files that changed from the base of the PR and between 719cdc6 and dd2c5eb.

📒 Files selected for processing (4)

• SCHEMAS.md
• lexicons/org/hypercerts/claim/activity.json
• lexicons/org/hypercerts/collection.json
• lexicons/org/hypercerts/context/attachment.json