[Lms24]

This PR adds descriptions for attribute namespaces (i.e. the first part of an attribute key).

Why? We've had occasions where attributes landed in the wrong namespace or there was a lot of confusion what kind of semantics one namespace covers.

Therefore, this PR adds:

• Functionality to display a description of a namespace by reading it from a README.md file put into the namespace. The frontmatter part is parsed by our docs setup and rendered with specific UI. The free text markdown underneath is also rendered on docs, but keeps the rendered markdown format.
• Guidelines what not to put into the namespace, and which other namespaces would cover that information better (see screenshot)
• Tests that require contributors to add a new readme for a new namespace. This is done to ensure we think a little bit about the purpose of the namespace at the latest when we add the first attribute to it
• An ignorelist for already existing namespaces without a Readme. I added a readme to 2 namespaces I work a lot with but I don't think it's feasible to one-shot Readmes into every namespace immediately. We can do so over time.

Why a readme over JSON?

• the attribute model directories are built in a way that require every json in an attribute folder to follow the attribute.schema.json file. So we'd need to build exclusions around some kind of _meta.json file or whatever we call it
• Formatting is a bit more annoying in JSON than in Markdown, which is why I think the readme works fairly well, together with the frontmatter.

If reviewers have opinions or other suggestions (or want to go with the _meta.json idea) that's fine. Happy to change it!

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
sentry-conventions	Ready	Preview	Oct 28, 2026 4:20pm UTC

[github-actions]

Semver Impact of This PR

🟢 Patch (bug fixes)

📋 Changelog Preview

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).

---

Internal Changes 🔧

• (attributes) Add descriptions for attribute namespaces by Lms24 in #755

---

_{🤖 This preview updates automatically when you update the PR.}

[alexander-alderman-webb]

Obviously good work!

My main remark is that I feel uneasy that we would have JSON and YAML for various things after this lands. What if we shove JSON instead of YAML into the markdown? Also feel free to ignore me, just what stood out to me.