Schema definition for external tooling

[theletterf]

The VS Code Extension for V3 docs is about to be open sourced: https://github.com/elastic/elastic-docs-v3-vscode. The main issue with it is how to keep it updated with V3 adding or removing stuff, especially in the frontmatter and directives.

I see opportunities for schema definition and content reuse in the docs-builder project that could allow the VS Code extension and any kind of tool to obtain quick, structured knowledge of the V3 syntax:

Directive schema

Current state:

• 13+ directive types implemented in C# (src/Elastic.Markdown/Myst/Directives/)
• Directives include: Admonition, AppliesSwitch, AppliesTo, CsvInclude, Diagram, Dropdown, Image, Include, Mermaid, Settings, Stepper, Tabs, Version

Opportunity:
Create a JSON Schema for Directive Definitions that can be:

• Consumed by VS Code extensions for autocompletion
• Used for validation in CI/CD pipelines
• Shared across documentation teams
• Version-controlled separately from implementation

Configuration schema

docset.yml schema definition

Current state:

• YAML configuration file with fields: project, max_toc_depth, dev_docs, cross_links, exclude, subs, features, api, toc
• No formal JSON Schema for validation

Opportunity:
Create a JSON Schema for docset.yml to enable:

• IDE autocompletion and validation
• Pre-build validation
• Documentation generation
• Type-safe configuration

Frontmatter schema

Current state:

• 4 documented frontmatter fields: navigation_title, description, applies_to, products
• No formal schema definition

Opportunity:
Create a Frontmatter JSON Schema with:

• All supported fields
• Type validation
• Product ID enumeration
• applies_to validation

applies_to schema

Current state:

• Complex nested structure with multiple keys (stack, deployment, serverless, product)
• Lifecycle states: preview, ga, beta, deprecated, removed
• Version specifications

Opportunity:
Create a dedicated applies_to JSON Schema for reuse across:

• Frontmatter validation
• Directive parameter validation
• Build-time validation

Content reuse

Substitution variables as shared schema

Current state:

• Substitution variables defined in docset.yml (subs: key)
• 200+ variables in example docset.yml
• Variables include: product names, app names, URLs, feature names
• Support for mutations (lowercase, uppercase, kebab-case, etc.)

Opportunity 1: central variable registry
Create a shared substitution variables registry as JSON:

Benefits:

• Single source of truth for common variables
• Can be imported into individual docset.yml files
• Version control for variable changes
• Autocompletion support in IDEs

[theletterf]

@Mpdreamz Created this one following our conversation yesterday.