feat: support non-standard markdownDescription property (#23)

twelvelabs · Dec 28, 2023 · 1cf627a · 1cf627a
1 parent a01965f
commit 1cf627a
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 8 deletions.
diff --git a/internal/jsonschema/schema.go b/internal/jsonschema/schema.go
@@ -40,6 +40,7 @@ type Schema struct {
 	ID                    string             `json:"$id,omitempty"`
 	If                    *Schema            `json:"if,omitempty"`
 	Items                 *Schema            `json:"items,omitempty"`
+	MarkdownDescription   string             `json:"markdownDescription,omitempty"`
 	MaxContains           int                `json:"maxContains,omitempty"`
 	Maximum               float64            `json:"maximum,omitempty"`
 	MaxItems              int                `json:"maxItems,omitempty"`
@@ -125,6 +126,16 @@ func (s *Schema) Clone() (*Schema, error) {
 	return s.Context.parse(doc, s.Parent)
 }
 
+// DescriptionMarkdown returns the schema description formatted as Markdown,
+// Will prioritize the non-standard `markdownDescription` attribute if present,
+// otherwise uses `description`.
+func (s *Schema) DescriptionMarkdown() string {
+	if s.MarkdownDescription != "" {
+		return s.MarkdownDescription
+	}
+	return s.Description
+}
+
 func (s *Schema) EntityName() string {
 	if s.Title != "" {
 		return s.Title
@@ -259,6 +270,8 @@ func (s *Schema) Merge(other *Schema) {
 			s.If = other.If
 		case "items":
 			s.Items = other.Items
+		case "markdownDescription":
+			s.MarkdownDescription = other.MarkdownDescription
 		case "maxContains":
 			s.MaxContains = other.MaxContains
 		case "maximum":

diff --git a/internal/jsonschema/schema_test.go b/internal/jsonschema/schema_test.go
@@ -93,6 +93,27 @@ func TestSchema_RefURI(t *testing.T) {
 	)
 }
 
+func TestSchema_DescriptionMarkdown(t *testing.T) {
+	require := require.New(t)
+
+	// Defaults to empty string.
+	schema := Schema{}
+	require.Equal("", schema.DescriptionMarkdown())
+
+	// Uses `.Description` if present.
+	schema = Schema{
+		Description: "This _could_ be Markdown",
+	}
+	require.Equal("This _could_ be Markdown", schema.DescriptionMarkdown())
+
+	// Uses `.MarkdownDescription` if present.
+	schema = Schema{
+		Description:         "This _could_ be Markdown",
+		MarkdownDescription: "This **is** Markdown",
+	}
+	require.Equal("This **is** Markdown", schema.DescriptionMarkdown())
+}
+
 func TestSchema_EntityName(t *testing.T) {
 	require := require.New(t)
 
@@ -252,6 +273,7 @@ func TestSchema_Merge(t *testing.T) {
 			"$id":                   true,
 			"if":                    true,
 			"items":                 true,
+			"markdownDescription":   true,
 			"maxContains":           true,
 			"maximum":               true,
 			"maxItems":              true,

diff --git a/internal/jsonschema/templates/markdown.tpl.md b/internal/jsonschema/templates/markdown.tpl.md
@@ -16,32 +16,30 @@
 | -------- | ---- | -------- | ------- | ----------- |
 {{ $propParent := . -}}
 {{ range $key, $prop := $propParent.Properties -}}
-| `{{ $key }}` | {{ $prop.TypeInfoMarkdown }} | {{ if $propParent.RequiredKey $key }}✅{{ end }} | {{ $prop.Default }} | {{ $prop.Description | toHTML }}{{ template "ConstTpl" $prop.Const }}{{ template "EnumTpl" $prop.EnumMarkdown }}{{ template "ExamplesTpl" $prop.ExamplesMarkdown }} |
-{{ end }}
+| `{{ $key }}` | {{ $prop.TypeInfoMarkdown }} | {{ if $propParent.RequiredKey $key }}✅{{ end }} | {{ $prop.Default }} | {{ $prop.DescriptionMarkdown | toHTML }}{{ template "ConstTpl" $prop.Const }}{{ template "EnumTpl" $prop.EnumMarkdown }}{{ template "ExamplesTpl" $prop.ExamplesMarkdown }} |
+{{ end -}}
 {{ end -}}
 {{ end -}}
 
 # {{ .EntityName }}
 
-{{ .Description }}
+{{ .DescriptionMarkdown }}
 
 ## {{ .EntityName }} Properties
 
-{{ template "PropertiesTpl" . -}}
-
+{{ template "PropertiesTpl" . }}
 {{ range $key, $def := .Definitions -}}
 {{ if $def.Enum }}{{ continue }}{{ end -}}
 
 ## {{ $def.EntityName }}
 
-{{ $def.Description }}
+{{ $def.DescriptionMarkdown }}
 
 {{ if $def.Properties -}}
 
 ### {{ $def.EntityName }} Properties
 
-{{ template "PropertiesTpl" $def -}}
-
+{{ template "PropertiesTpl" $def }}
 {{ end -}}
 
 {{ if $def.OneOf -}}