SPDX-FileCopyrightText: 2026 Arthit Suriyawongkul SPDX-FileType: DOCUMENTATION SPDX-License-Identifier: CC0-1.0

SpecMD

Convert Markdown model definitions to RDF ontologies and specification documents.

Features

SpecMD reads and validates a complete model directory, then generates one or more outputs:

A few SpecMD syntax additions capture validation rules that spec-parser can only express as prose -- type scoping, conditional cardinality, relationship endpoint typing, numeric ranges, fixed values, and profile conformance -- and compile them to SHACL automatically. See docs/constraints-spec.md for the rule catalogue and docs/design.md for the SHACL mapping.

Installation

pip install specmd

All Python dependencies are installed automatically. The tex format additionally requires pandoc; all other formats need no external tools.

Quick start

# Validate a model directory
specmd validate path/to/model

# Generate all formats into ./out
specmd generate path/to/model --output ./out

# Generate specific formats only
specmd generate path/to/model --formats rdf,mkdocs --output ./out

See the command-line reference for every command and option.

Configuration

An optional specmd.yml file at the model root controls parsing and generation (base URI, namespace order, ontology metadata, vocabulary defaults, output naming, and profile conformance). A worked example is in docs/specmd.yml.example; the full reference is in docs/format.md.

Model files are linter-friendly: they survive a markdownlint --fix pass, and IRI metadata such as id: accepts both a bare URL and the autolink form (id: <https://…>).

Documentation

Compatibility

SpecMD targets compatibility with spdx/spec-parser workflows and accepts the original Markdown format via automatic migration (specmd migrate, or the main.py drop-in shim). Generated output is not byte-for-byte identical -- existing SHACL validation results are preserved, but RDF/OWL consumers should review the differences. See docs/spec-parser-compatibility.md.

This project is not an official SPDX project.