Documenting Your Lexicons

Good documentation helps developers understand and use your lexicons effectively. Lexicon Garden extracts and displays documentation from your schema definitions.

Why Documentation Matters

• Helps developers understand your lexicon's purpose and usage
• Displayed on the "Docs" tab in Lexicon Garden
• Improves discoverability and adoption

Schema-Level Documentation

Add a description field to your main definition:

{
  "lexicon": 1,
  "id": "com.example.post",
  "defs": {
    "main": {
      "type": "record",
      "description": "A user post with optional media attachments.",
      ...
    }
  }
}

Property Documentation

Add description to individual properties:

{
  "properties": {
    "text": {
      "type": "string",
      "description": "The post content. Maximum 300 characters.",
      "maxLength": 300
    },
    "createdAt": {
      "type": "string",
      "format": "datetime",
      "description": "When the post was created (ISO 8601)."
    }
  }
}

Best Practices

• Be concise but complete: Explain what each field does without unnecessary verbosity
• Document constraints: Explain validation rules, min/max values, and format requirements
• Explain relationships: Note how fields relate to other lexicons or records
• Include examples: When helpful, describe valid values in the description