Skip to content

Conversation

VinitaSilaparasetty
Copy link

Problem

The existing @adobe/jsonschema2md tool produces poor-quality documentation with:

  • Too many "Untitled/Unknown" labels
  • Arrays listed as top-level items in confusing ways
  • Lack of customization for human-readable output

As mentioned in the original issue, the default generator doesn't provide the needed customization for useful documentation.

Solution

This PR introduces a custom JavaScript-based schema documentation generator that directly addresses these issues:

✅ Fixes the specific problems:

  • Eliminates "Untitled/Unknown" labels by using actual property names from the schema
  • Handles arrays intelligently:
    • Object arrays → documents the object structure with properties
    • Primitive arrays → summarized as "array of [type]"
  • Produces clean, human-readable Markdown with proper formatting and structure

🏗️ Implementation:

  • New script: scripts/generate-schema-docs.js (zero external dependencies)
  • New npm command: pnpm run build:schema
  • Output: docs/schema-docs/configuration-schema.md
  • Integrates with existing Turbo monorepo workflow

📋 Usage:

# Generate schema documentation
pnpm run build:schema

- Addresses issues with @adobe/jsonschema2md output quality
- Eliminates 'Untitled/Unknown' labels by using actual property names
- Handles arrays intelligently (objects documented, primitives summarized)
- Generates human-readable Markdown for OSO Clickhouse schema
- Adds 'build:schema' npm script for easy documentation generation

Resolves schema documentation readability issues mentioned in #[issue-number]
Copy link

vercel bot commented Aug 12, 2025

@VinitaSilaparasetty is attempting to deploy a commit to the Network-Goods Team on Vercel.

A member of the Team first needs to authorize it.

@VinitaSilaparasetty
Copy link
Author

@ryscheng This addresses the schema documentation quality issues by replacing the problematic @adobe/jsonschema2md output with a custom generator that eliminates "Untitled/Unknown" labels and handles arrays properly.

The script generates clean documentation from the Hasura Clickhouse schema and integrates with the existing monorepo workflow via pnpm run build:schema.

Key improvements:

  • Uses actual property names instead of "Untitled/Unknown" labels
  • Handles arrays intelligently (documents object properties, summarizes primitive arrays)
  • Outputs human-readable Markdown to docs/schema-docs/
  • Zero external dependencies, integrates with existing Turbo workflow

I've tested this locally and it produces clean, readable documentation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant