A TypeSpec-based document specification that defines a rich, structured document model. DocSpec provides a JSON-serializable alternative to HTML's semantic document structure, designed for API consumption and multi-language code generation.
DocSpec uses TypeSpec as the single source of truth for document schemas, then emits:
- JSON Schema for validation
- Go structs for Go applications
- Elixir Ecto schemas with changesets
npm installBuild the schema and generate code for all target languages:
npm run buildThis compiles the TypeScript decorators/emitters, then runs tsp compile . to generate output.
Generated files appear in tsp-output/:
tsp-output/
├── schema/ # JSON Schema
├── go/ # Go structs
└── elixir/ # Ecto schemas
DocSpec mirrors HTML semantics with a structured hierarchy:
DocumentSpecification (version: "alpha")
└── Document
├── Block content (Paragraph, Heading, Table, lists, etc.)
├── footnotes?: Footnote[]
└── assets?: Asset[]
| Element | HTML Equivalent | Purpose |
|---|---|---|
Document |
<body> |
Root container |
Paragraph |
<p> |
Text block |
Heading |
<h1>-<h6> |
Section heading with level |
Table |
<table> |
Table with rows, cells, headers |
OrderedList |
<ol> |
Numbered list |
UnorderedList |
<ul> |
Bulleted list |
BlockQuotation |
<blockquote> |
Quote block with citation |
DefinitionList |
<dl> |
Term/definition pairs |
Preformatted |
<pre> |
Whitespace-preserved text |
ThematicBreak |
<hr> |
Topic/section separator |
| Element | HTML Equivalent | Purpose |
|---|---|---|
Text |
text node | Styled text run |
Link |
<a> |
Hyperlink with purpose |
Image |
<img> |
Embedded image |
Math |
n/a | LaTeX math notation |
FootnoteReference |
n/a | Reference to footnote |
Text and Link elements support styling: bold, italic, underline, strikethrough, superscript, subscript, code, mark.
@resource - Injects identity properties into models:
id: string; // UUID format
type: "https://alpha.docspec.io/{ModelName}";@children(Type1 | Type2 | ...) - Defines allowed child element types:
children: (Type1 | Type2 | ...)[];spec/
├── main.tsp # TypeSpec schema (source of truth)
├── lib/
│ ├── decorators/ # Custom TypeSpec decorators
│ │ ├── resource.ts # Adds id + type to models
│ │ ├── children.ts # Defines allowed children
│ │ └── index.ts # Decorator exports
│ └── emitters/
│ ├── go.ts # Go struct generator
│ └── elixir.ts # Ecto schema generator
├── tspconfig.yaml # Emitter configuration
└── tsp-output/ # Generated code
This project uses a dual license: