Structured Markdown Schema v1

Two Related but Distinct Schemas

Two JSON Schema artifacts describe "structured Markdown" content, and they serve different purposes. schemas/structured_markdown/v1/Article.schema.json is generated from the StructuredContent Pydantic model and defines the parser's output contract — the shape of the object the parser writes into ParsedDocument.structured_content. model/articles/artArticle.schema.json (and its type-specific siblings such as artHowto.schema.json) is the authoring pattern language that the validator checks the classified content against. The first describes what the parser produces; the second describes what well-formed content looks like. A document can match the output contract (all required fields present) while still failing authoring validation (wrong article type, missing required units), and both conditions are reportable independently.

The Article.schema.json Output Contract

schemas/structured_markdown/v1/Article.schema.json is a self-contained JSON Schema Draft 7 document generated by tools/generate_json_schemas.py. Its $defs section includes inline definitions for Unit, Component, Attribute, SourceSpan, and all relevant enums. The top-level object (StructuredContent) has no required fields; all properties have defaults.

Top-level StructuredContent fields:

Field	JSON Type	Default	Description
schema_version	string	"1"	Output contract version
schema_name	string	"artArticle.schema.json"	Name of the model schema used for authoring validation
version	string	"0.1.0"	Semantic version of the article model
article_id	string or null	null	Optional identifier from front matter
article_type	enum	"unknown"	Classified article type
dita_type	string or null	null	DITA topic type override, when specified in front matter
information_type	enum	"unknown"	Dominant information type
title	string or null	null	Article title
triage_status	enum	"unknown"	Classification confidence: "known", "unknown", or "ambiguous"
metadata	object	{}	Front matter fields carried forward
source	object	{}	Source provenance metadata
content	array of Unit	[]	Ordered list of content units

The Unit Schema

Each element of StructuredContent.content is a Unit. The unit_type field is required.

Unit fields:

Field	JSON Type	Description
unit_type	enum	"introduction", "concept", "procedure", "principle", "process", "fact", "reference", "troubleshooting", "glossary", "glossentry", "prerequisites", "link-nextstep", "link-related", "unknown"
unit_id	string or null	Optional identifier
information_type	enum	Information type for this unit
title	string or null	Section heading text
triage_status	enum	"known", "unknown", or "ambiguous"
procedure_representation	enum or null	For procedure units: "ordered-list", "code-block", "mixed", "unknown"
term	string or null	For glossentry units: the defined term
source	SourceSpan or null	Source location (file path, start line, end line)
metadata	object	Unit-level metadata
content	array of Component	Ordered list of components

The Component Schema

Each element of Unit.content is a Component. The component_type field is required.

Key Component fields:

Field	JSON Type	Description
component_type	enum	E.g., "compParagraph", "compHeaderH2", "compBlockCode", "compListOrdered", "compTable", "compAlert"
markdown	string or null	Raw Markdown source for the component
html	string or null	Rendered HTML equivalent
text	string or null	Plain text content
level	integer or null	Heading level (1–6) for compHeaderH* types
language	string or null	Language identifier for code blocks
code	string or null	Code content for compBlockCode
alert_type	string or null	E.g., "note", "tip", "warning" for compAlert types
row_count	integer or null	Row count for compTable
column_count	integer or null	Column count for compTable
row_role	string or null	"header" or "body" for compTableRow
cell_role	string or null	"header" or "body" for compTableCell
triage_status	enum	Classification confidence for this component
source	SourceSpan or null	Source location
content	array	Nested Attribute or Component objects

The Attribute Schema

Attribute represents inline markup within a Component. The att_type field is required.

Key Attribute fields:

Field	JSON Type	Description
att_type	enum	"attText", "attBold", "attItalic", "attCode", "attLink", "attImage", "attStrong", "attEmphasis", "attAnchor", "attSub", "attSuper", "attSpan", "attUnknown"
markdown	string or null	Markdown source for the inline element
text	string or null	Plain text content
href	string or null	Link target for attLink and attAnchor
target	string or null	Link target attribute (e.g., "_blank")
source	string or null	Image src URL for attImage
alt_text	string or null	Image alt text for attImage
content	array of Attribute	Nested inline elements

Minimal JSON Example

The following is a complete StructuredContent object with one unit and one component:

{
  "schema_version": "1",
  "schema_name": "artHowto.schema.json",
  "version": "0.1.0",
  "article_id": "install-cli",
  "article_type": "howto",
  "information_type": "procedure",
  "title": "Install the CLI",
  "triage_status": "known",
  "metadata": { "author": "eng-team" },
  "source": {},
  "content": [
    {
      "unit_type": "introduction",
      "unit_id": null,
      "information_type": "concept",
      "title": "Overview",
      "triage_status": "known",
      "procedure_representation": null,
      "term": null,
      "metadata": {},
      "source": { "start_line": 5, "end_line": 8, "provenance_status": "available" },
      "content": [
        {
          "component_type": "compParagraph",
          "markdown": "This guide walks you through installing the CLI on macOS.",
          "text": "This guide walks you through installing the CLI on macOS.",
          "triage_status": "known",
          "metadata": {},
          "content": [
            {
              "att_type": "attText",
              "text": "This guide walks you through installing the CLI on macOS."
            }
          ]
        }
      ]
    }
  ]
}

Regenerating the Schema

To regenerate schemas/structured_markdown/v1/Article.schema.json after a change to the StructuredContent, Unit, Component, or Attribute Pydantic models:

python tools/generate_json_schemas.py

Commit the output alongside the Python change. When a breaking field change occurs, update the tool to write to v2/ and retain v1/ for consumers that have not yet migrated.