Providing Lexicon Examples

Example records help developers understand how to use your lexicons in practice. Lexicon Garden displays these on the "Examples" tab.

What Are Lexicon Examples?

Example records are stored using the garden.lexicon.example collection. They provide reference implementations that demonstrate correct usage of a lexicon.

The garden.lexicon.example Schema

{
  "$type": "garden.lexicon.example",
  "createdAt": "2026-01-03T03:17:31.040Z",
  "lexicon": "community.lexicon.calendar.event",
  "description": "An example event with a facet.",
  "value": {
    "$type": "community.lexicon.calendar.event",
    "createdAt": "2025-11-12T22:54:25.013Z",
    "name": "Zero Cool Day",
    "description": "Join us in celebrating Zero Cool Day...",
    "startsAt": "2026-08-10T14:00:00.000Z",
    "status": "community.lexicon.calendar.event#scheduled",
    "mode": "community.lexicon.calendar.event#hybrid"
  }
}

Fields Explained

  • $type: Always garden.lexicon.example
  • createdAt: When this example was created
  • lexicon: The NSID (with optional fragment) this example demonstrates
  • description: Brief explanation of what this example shows
  • value: The actual example record data

Fragment Targeting

Use fragments to target specific definitions:

  • com.example.post or com.example.post#main - Primary record type
  • com.example.post#view - A specific view definition
  • com.example.defs#sharedType - A shared type definition

Examples are grouped by fragment on the Examples tab.

Publishing an Example

Use goat to publish an example record from a JSON file:

goat record create -n ./examples/community.lexicon.calendar.event.json

The -n flag creates a new record with a generated rkey.

Best Practices

  • Provide multiple examples showing different use cases
  • Include edge cases (minimum values, maximum values, optional fields)
  • Add clear descriptions explaining what each example demonstrates
  • Keep example values realistic and meaningful

Lexicon Garden

@