How to design a Lexicon Community lexicon
This guide is for anyone who wants a new community.lexicon.* lexicon to exist, or wants to change one. It walks the full path from idea to a published, resolving schema.
(Photo by Sven Mieke on Unsplash)
1. Start with a real-world use case
Real-world use is the acceptance bar. The strongest proposals start with an application, SDK, or tool that exists (or is being built) and needs a shared schema to interoperate with others. "This would be neat" is not a use case; "these three apps each invented their own bookmark record and they can't read each other's" is.
2. Check what already exists
Browse the published lexicons. Your idea may fit an existing namespace, or extend an existing schema.
Search the forum: the discussion may already be in motion, and joining an existing effort beats duplicating it.
Look beyond this namespace on Lexicon Garden: someone else in the ATmosphere may have already published something close to what you need.
3. Form a working group
Working groups are self-formed (no approval is needed to begin). Post your announcement on the forum so others can find you.
You can use this simple template to make sure all of the basics are covered:
Working group: <short name>
Objective: one or two sentences that scope the work.
Use case: the application, SDK, or tool that needs this, and who else is building in the space.
Expected deliverable: e.g. schema definition(s), example records, reference code.
Timeline: a rough target.
Looking for: the collaborators or expertise you want.Small is fine; most working groups are one to three people. Not every change needs one at all: small, clear improvements can go straight to a pull request (see best practices).
4. Design and iterate in the open
Use Lexicon Garden to create experimental lexicons and try schema shapes against real records before anything is official.
Build against your draft: example records based on real scenarios, and reference code that constructs and reads them. This is what makes review fast.
Follow the conventions of adjacent schemas in the lexicons repository; similar things should be named and shaped in similar ways.
Keep the discussion on your forum thread as the design evolves, so the eventual pull request represents consolidated agreement.
5. Propose the pull request
Schemas live in the repository as one JSON document per NSID, under community/lexicon/<namespace>/<name>.json. Open the pull request against tangled.org/lexicon.community/lexicons, and include in its description: the use case, links to the forum discussion, example records, and any reference code. Review the best practices and considerations before you open it — those are the questions reviewers will ask.
6. Review, approval, merge
Review happens in the open, and anyone can weigh in. Pull requests can only be approved by Technical Steering Committee members, under the governance model's participation and quorum rule, with an agreed "do not merge before" date so the community has time to respond. Once approved and merged into main, the lexicon is production.
7. Publication and announcement
Merged lexicons are published as schema records in the @lexicons.lexicon.community repository, where NSID resolution finds them. See Publishing and resolution for exactly how that works and how to verify it. New lexicons are announced here on the blog and from @lexicon.community.
8. Afterward: stewardship
A published lexicon keeps living: implementations find edge cases, documentation needs improving, and adjacent proposals need an informed voice. If you drove a lexicon to publication, consider staying involved with it; if you build with one whose authors have moved on, your experience is especially valuable.
With all of that said, if there is one take away, it is that work starts in the forum.
