Searching Lexicons

Search finds lexicons by NSID and by what they do. Type into the search page, or into the box at the top of every page, and press Enter. One page shows up to four sections:

  • Exact match — the lexicon whose NSID is exactly what you typed, with its kind, its authority domain and a link to its documentation.
  • Resolve — when you type a complete NSID that isn't indexed yet, Lexicon Garden looks it up on the network and shows each step: the authority domain, the _lexicon TXT record, the DID document, the schema record, and validation. A lexicon that resolves is indexed at once.
  • NSID matches — indexed NSIDs containing what you typed, ignoring case, with NSIDs that start with it first and then the shortest.
  • By meaning — when you type plain words rather than an NSID, lexicons whose schemas are closest in meaning, found with a text-embedding model. find posts by text finds search methods even if none of them uses the word "find". When the model is unavailable this section is left out and a note says so.

Add type=record (or query, procedure, subscription, permission-set) to the address, repeated for several, to show only those kinds.

Each lexicon's page may also list similar lexicons: ones whose schemas describe something close. They are worth checking before publishing a new lexicon that overlaps an existing one.

Ranking and the authority flag

Anyone can publish a schema under any NSID. A lexicon whose publishing account is the NSID's DNS authority (its _lexicon TXT record) ranks normally. Any other publisher's copy ranks lower and is flagged not from the namespace authority. Each result shows the version the lexicon's own page shows: the newest live record, preferring the authority's.

Deleted lexicons leave the results within minutes. Lexicons on the denylist never appear.

For developers: garden.lexicon.search

Full-text and semantic search over every indexed lexicon is available as an anonymous, rate-limited XRPC query. Full-text search matches, in order of weight, the NSID segment by segment, the main description and definition names, field, parameter and error names (whole or split into words, so starts finds startsAt), and every other description. Word forms match too, and very common words are not indexed.

GET /xrpc/garden.lexicon.search?q=calendar%20event&lexiconType=record&limit=20
  • q (required, 2–256 characters) — the search text. "reading list" matches the phrase, calendar -google leaves out a word, rsvp or attendance matches either, and a complete NSID comes first, marked exact.
  • lexiconType (optional, repeatable) — record, query, procedure, subscription or permission-set.
  • limit (optional, 1–50, default 20) — clamped when out of range.
  • cursor (optional) — from the previous response, for the next page.
  • mode (optional) — keyword (default) or semantic. The response's mode says which ran, since semantic falls back to keyword when unavailable.

Each result carries nsid, did, uri, lexiconType, authoritative, exact, summary, and a plain-text snippet with highlights given as UTF-8 byte ranges, the same convention as richtext facets. The schema is garden.lexicon.search.

For prefix lookups and typeahead, use garden.lexicon.suggest and garden.lexicon.browse instead.

For developers: garden.lexicon.resolveTrace

The resolve panel's lookup is an anonymous XRPC query too:

GET /xrpc/garden.lexicon.resolveTrace?nsid=com.example.recipe.card

It answers with the five steps (authority, dns, did, record, index), each done, failed or pending with a detail; an outcome of found, failed or timeout and a message; and, when found, the record's uri, cid and lexiconType. A failed step leaves every later step pending. Steps answered from Lexicon Garden's caches make no network request; traces that do are limited per client.