xsd-former 1.0.0__tar.gz

xsd_former-1.0.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @folded

xsd_former-1.0.0/.github/workflows/lint.yml

@@ -0,0 +1,28 @@
+name: lint
+
+on:
+  pull_request:
+    types: [opened, ready_for_review, synchronize]
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    # Runs every hook in .pre-commit-config.yaml — the whole static-check gate.
+    # Skip draft PRs.
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+      # Pre-sync the lint env so the pyright hook's `uv run` is a no-op.
+      - run: uv sync --locked --group lint --python 3.13
+      - uses: actions/cache@v6
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+      - run: uv run pre-commit run --all-files --show-diff-on-failure

xsd_former-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: release
+
+# Publishes to PyPI via Trusted Publishing (OIDC) — no API token. The PyPI
+# project's trusted publisher must reference this repo, this workflow filename,
+# and the `pypi` environment. Triggered on a published GitHub Release; the tag
+# must match the package version (guarded below).
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+      # Publishing a version is irreversible, so fail loudly if the release tag
+      # (vX.Y.Z) doesn't match the version in pyproject.toml.
+      - name: Check tag matches package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(uv version --short)"
+          if [ "$tag" != "$pkg" ]; then
+            echo "Release tag '$GITHUB_REF_NAME' does not match package version '$pkg'"
+            exit 1
+          fi
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # The trusted-publisher and OIDC scope both key off this environment name.
+    environment: pypi
+    permissions:
+      id-token: write # mint the OIDC token PyPI exchanges for an upload token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

xsd_former-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,39 @@
+name: tests
+
+on:
+  pull_request:
+    types: [opened, ready_for_review, synchronize]
+  push:
+    branches: [main]
+
+jobs:
+  pytest:
+    # Skip draft PRs.
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+      - uses: actions/setup-node@v4
+        with:
+          # @typespec/compiler >=1.13 requires Node >=22 (imports `glob` from
+          # `fs/promises`, added in Node 22). On Node 20 the toolchain crashes at
+          # runtime instead of skipping, failing the gated tsp tests.
+          node-version: '22'
+      # Enables the skipif-gated Node tests: the xsd->tsp->proto round-trip
+      # (`_tsp.tsp_available()`) and the pydantic equivalence gate
+      # (`_tsp.json_schema_available()`, via `@typespec/json-schema`). Without it
+      # both skip.
+      - name: Install TypeSpec toolchain
+        working-directory: tests/xsdformer/typespec/tsp_project
+        run: npm install
+      - run: uv sync --locked --group test --python ${{ matrix.python-version }}
+      - run: uv run pytest -q

xsd_former-1.0.0/.gitignore

@@ -0,0 +1,135 @@
+# Python codebase default gitignore (github template)
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# local irrelevant files
+.idea
+.DS_Store
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

xsd_former-1.0.0/.markdownlint.json

@@ -0,0 +1,13 @@
+// https://github.com/DavidAnson/markdownlint#optionsconfig
+// Disabling some rules here as we find them too restrictive.
+{
+  "default": true,            // Include all rules by defauls
+  "line-length": false,       // To allow working with soft wraps in editors
+  "no-inline-html": {         // Sometimes we need to use <img> html tags in GitHub markdown,
+                              // as it doesn't allow setting the image size with markdown tags
+    "allowed_elements": ["details", "img"]
+  },
+  "ul-indent": false,          // To allow indenting the whole list to distinguish it visually
+  "no-multiple-blanks": false  // To allow multiple blank lines between a header and
+                               // the previous paragraph
+}

xsd_former-1.0.0/.markdownlintignore

@@ -0,0 +1 @@
+CLAUDE.md

xsd_former-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,51 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+        exclude: '\.*conda/.*'
+      - id: end-of-file-fixer
+        # Vendored schemas (NLM DTD, ClinVar XSD) and real efetch record fixtures
+        # are kept byte-faithful to their upstream form; don't normalize them.
+        exclude: '^tests/xsdformer/(typespec/schemas|pydantic/records)/'
+      - id: trailing-whitespace
+        exclude: '\.txt$|\.tsv$|^tests/xsdformer/(typespec/schemas|pydantic/records)/'
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: debug-statements
+      - id: check-added-large-files
+
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.45.0
+    hooks:
+      - id: markdownlint
+
+  - repo: https://github.com/populationgenomics/pre-commits
+    rev: "e37928f761f17d54aca5cedf93848b40ec7cff26"
+    hooks:
+      - id: cpg-id-checker
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.1
+    hooks:
+      - id: ruff
+      - id: ruff-format
+
+  # pyright needs the project deps to resolve imports, so it runs in the lint env
+  # via `uv run`; `--group lint` provisions it on demand. Whole-project (include
+  # set in pyproject), so pass_filenames: false; fires on any staged .py.
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run --group lint pyright
+        language: system
+        files: \.py$
+        pass_filenames: false
+
+  # YAML formatter (ruff can't format YAML).
+  - repo: https://github.com/google/yamlfmt
+    rev: v0.21.0
+    hooks:
+      - id: yamlfmt

xsd_former-1.0.0/.yamlfmt

@@ -0,0 +1,10 @@
+# YAML formatter config; the YAML analogue of ruff-format / biome.
+# retain_line_breaks_single: yamlfmt can't selectively strip blank lines
+# between block-sequence items, so the no-blank-line-between-steps layout in
+# .github/workflows is kept by hand — this setting only stops yamlfmt from
+# reintroducing or multiplying blank lines elsewhere.
+formatter:
+  type: basic
+  retain_line_breaks_single: true
+  trim_trailing_whitespace: true
+  eof_newline: true

xsd_former-1.0.0/CLAUDE.md

@@ -0,0 +1,74 @@
+# xsdformer development notes
+
+xsdformer converts an XSD or DTD schema into Protobuf, JSON Schema, TypeSpec,
+Pydantic models, and Python XML-to-protobuf converters. See
+[`CONTEXT.md`](CONTEXT.md) for the domain model and language, and
+[`README.md`](README.md) for usage.
+
+## Working norms
+
+Operating directives for Claude (and any agent) in this repo; they counteract default
+model dispositions.
+
+- **Resist the minimal-diff reflex.** Don't reach for the smallest change that hides the
+  symptom (special-casing, papering over root causes). Aim for the correct fix at the
+  right complexity level — not the smallest, not gold-plated.
+- **Fail loudly and early.** Raise on a missing expected input or precondition; never fall
+  back to a default/placeholder to limp along. A placeholder is an explicit caller input,
+  never a code default.
+- **Push back; don't just comply.** When a design, name, or approach seems worse —
+  including a shortcut you're asked to take — say so with reasoning, unprompted. The
+  author owns the final call.
+- **Offer better alternatives with trade-offs.** When a materially better approach than
+  the proposed one exists, present it and the trade-offs — don't just execute the ask.
+- **Investigate before producing.** Read the code and verify constraints first. Don't
+  treat a training-pattern convention as load-bearing unchecked; don't speculate about
+  what you can read.
+- **Explain non-obvious changes first.** For a change whose rationale isn't self-evident,
+  give the why before showing or applying the diff.
+- **Ask when unsure** rather than assume intent.
+- **No intensifiers or emphasis filler.** Drop words and phrases that add emphasis but no
+  information — "that's the key", "crucially", "importantly", "the key insight", "it's
+  worth noting". State the point plainly. Applies to all prose: chat replies, PR/review
+  comments, commit messages, and docs.
+
+## Commands
+
+```bash
+uv sync --group test --group lint   # install dev dependencies
+uv run pytest                 # run the test suite
+uv run pytest tests/xsdformer/xsd/test_xsd.py::test_name -x   # single test
+uv run pre-commit run --all-files   # the full static-check gate (see below)
+```
+
+Some tests are gated on a TypeSpec (Node) toolchain and skip when it is absent;
+CI installs it. See [`CONTEXT.md`](CONTEXT.md) for what each module does.
+
+## Code style
+
+@docs/style/general.md
+@docs/style/python.md
+
+## Docs
+
+The primary audience for docs is a model reading them as context; humans second. Be
+terse: state each decision, mechanism, and rationale once — no rhetorical emphasis, no
+persuasion, no recaps. Every token written is re-paid on every future read. Design
+decisions with lasting consequences get an ADR under [`docs/adr/`](docs/adr).
+
+## Committing
+
+- **Stage explicit paths**, not `git add -A` / `.`.
+- **Pre-commit is the full static-check gate** (`.pre-commit-config.yaml`): lint, format,
+  hygiene, and pyright. CI runs the same hooks via `pre-commit run --all-files`, so the
+  two can't drift. Ensure hooks are installed (`pre-commit install`) — if not, install or
+  ask the author; never bypass with `--no-verify`.
+- **Correct a pushed branch with a new commit on top**, not amend + force-push. PRs
+  squash-merge, so `main` history stays linear regardless and intermediate fixups vanish
+  on merge. Reserve force-push for rebasing a branch onto `main`.
+
+## CI and review
+
+- **Pin third-party GitHub Actions to the latest stable release**: the moving major tag
+  (`@v3`) where the action publishes one, else the exact latest version (`@v8.2.0`). Verify
+  against the action's releases when adding or bumping one.

xsd_former-1.0.0/CONTEXT.md

@@ -0,0 +1,115 @@
+# xsdformer
+
+xsdformer converts an XML schema — an **XSD** or a **DTD** — into code that
+describes and processes the same data in other ecosystems: Protobuf
+definitions, JSON Schema, TypeSpec, Pydantic models, and Python code that
+parses conforming XML into Protobuf messages.
+
+It supports enough of XSD/DTD to convert the
+[ClinVar](https://www.ncbi.nlm.nih.gov/clinvar/) and
+[BioC](http://bioc.sourceforge.net/) schemas. Full coverage of the XSD
+specification is a non-goal; the parser raises on constructs it does not model
+rather than emitting a silent approximation.
+
+## Pipeline
+
+```text
+schema (XSD | DTD) → parse → IR (TypeDefinition graph) → transform → generate → output
+```
+
+A front end parses the schema into an intermediate representation (IR). The IR
+is a topologically sorted graph of type definitions, independent of both the
+input schema language and the output target. Each back end (generator) walks
+that IR to emit one output format. Adding an input or output format touches one
+front end or one generator, not the pipeline.
+
+## The IR — language
+
+The IR lives in [`xsd/xsd.py`](src/xsdformer/xsd/xsd.py). These are the domain
+terms; use them exactly.
+
+**TypeDefinition**:
+A named type in the schema. The base for the three concrete kinds a generator
+must handle:
+
+- **Message** — a structured type (an XSD complex type): a set of fields.
+- **Enumeration** — a closed set of named values.
+- **MapType** — a type that models a map (key/value) rather than a record.
+
+**FieldDefinition**:
+A member of a `Message`. The base for leaf **Field** kinds and **container**
+kinds:
+
+- **Field** — a leaf carrying a value. Subtypes: **Elem** (a child element),
+  **Attr** (an XML attribute), **ValueElem** (an element's text content).
+- **Seq** — an ordered group of fields.
+- **Choice** — a mutually-exclusive group of fields.
+
+**computed_occurs**:
+A field's effective `(min, max)` occurrence after multiplying through every
+enclosing container. A field that is optional inside a repeated `Seq` is
+repeated overall; `computed_occurs` is that resolved multiplicity.
+
+**enclosing_type**:
+Links a nested (enclosed) type to the `Message` it is defined inside. A type
+with no `enclosing_type` is top-level.
+
+**path**:
+The tuple of names from the root schema type down to a given type — its fully
+qualified position in the type graph.
+
+## Front ends (parsers)
+
+- [`xsd/xsd.py`](src/xsdformer/xsd/xsd.py) — parses XSD via the `xmlschema`
+  library, topologically sorts types by dependency, and produces the IR.
+- [`dtd/dtd.py`](src/xsdformer/dtd/dtd.py) — parses DTD into the same IR.
+- [`transforms.py`](src/xsdformer/transforms.py) — optional IR-level
+  simplifications (dropping fields, inlining single-field wrapper types,
+  collapsing a type to a plain string) applied before generation, driven by a
+  YAML transform spec (see `clinvar_transforms.yaml`, `pubmed_transforms.yaml`).
+
+## Back ends (generators)
+
+[`generator.py`](src/xsdformer/generator.py) defines the `IGenerator` protocol
+and `generate_with()`, which drives any generator over the IR and skips enclosed
+types at the top level (the enclosing type emits them). Each generator
+implements `IGenerator`:
+
+- [`protobuf/generator.py`](src/xsdformer/protobuf/generator.py) — emits
+  `.proto` syntax.
+- [`py/xml_converter.py`](src/xsdformer/py/xml_converter.py) — emits Python code
+  that converts parsed lxml elements into Protobuf message instances. Runtime
+  helpers (e.g. `_xml_bool`, `_consume`) are embedded into the generated output
+  via `inspect.getsource`.
+- [`jsonschema/generator.py`](src/xsdformer/jsonschema/generator.py) — compiles
+  proto (from the IR or an existing `.proto` file) via `grpc_tools.protoc` into
+  a `FileDescriptorSet`, then walks the Protobuf descriptors to emit JSON
+  Schema.
+- [`typespec/generator.py`](src/xsdformer/typespec/generator.py) — emits
+  TypeSpec (`.tsp`). See [ADR 0001](docs/adr/0001-typespec-output-format.md).
+- [`pydantic/`](src/xsdformer/pydantic) — emits Pydantic models
+  (`generator.py`) and a converter (`converter.py`), sharing naming logic in
+  `_naming.py`. See [ADR 0002](docs/adr/0002-pydantic-codegen-and-proto-hub.md).
+
+## CLI
+
+[`tool.py`](src/xsdformer/tool.py) exposes a Click group with three commands:
+
+- `xsdformer xsd <file>` — XSD front end; emit any combination of proto, Python
+  converter, JSON Schema, TypeSpec, and Pydantic outputs (one `--*-out` flag
+  each).
+- `xsdformer dtd <file>` — DTD front end; same output flags.
+- `xsdformer proto <file> <namespace>` — Proto-to-JSON-Schema only, bypassing
+  the XSD/DTD front end.
+
+## Package builder
+
+[`build.py`](src/xsdformer/build.py) assembles a standalone, pip-installable
+Python package from a schema: generated proto (compiled to `_pb2.py`), the XML
+converter, and Pydantic models, wrapped in a generated `pyproject.toml`.
+
+## Text utilities
+
+[`xsd/text.py`](src/xsdformer/xsd/text.py) — `snake_case`, `pascal_case`, and
+`keep` (wraps a string in `_Exact` to bypass case conversion). All identifier
+naming flows through these.

xsd_former-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Centre for Population Genomics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xsd_former-1.0.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: xsd-former
+Version: 1.0.0
+Summary: Generate Protobuf definitions, JSON Schema, and Python XML-to-protobuf converters from XSD and DTD schemas.
+Project-URL: Repository, https://github.com/populationgenomics/xsd-former
+Project-URL: Issues, https://github.com/populationgenomics/xsd-former/issues
+Author: Toby Sargeant
+License: MIT
+License-File: LICENSE
+Keywords: bioc,clinvar,code-generation,dtd,json-schema,protobuf,typespec,xml,xsd
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: grpcio-tools>=1.60
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: lxml>=5.0
+Requires-Dist: protobuf>=6.32.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: xmlschema>=4.0
+Description-Content-Type: text/markdown
+
+# XSDFormer
+
+XSDFormer deforms [XML schema definitions
+(XSDs)](https://www.w3.org/XML/Schema) into [Protobuf
+definitions](https://protobuf.dev/). It also generates Python code
+to convert parsed XML into the corresponding Protobuf representation.
+
+It supports enough of the XSD specification to convert the
+[ClinVar](https://www.ncbi.nlm.nih.gov/clinvar/) and
+[BioC](http://bioc.sourceforge.net/) schemas; full support for all
+XSD features is a non-goal.
+
+## Why convert from XSD to Protobuf?
+
+While XML and XSDs (or alternatively JSON and JSON schemas) are
+powerful for defining complex, human-readable data structures, they
+have some drawbacks, especially in high-performance applications
+or when dealing with large datasets.
+
+### Performance and Size
+
+* **Parsing Speed:** XML is a text-based format and can be slow to
+  parse. Protobuf is a binary format that is designed for speed and
+  efficiency. Converting XML data to Protobuf can result in significantly
+  faster parsing times.
+* **Storage Space:** XML is verbose, with opening and closing tags
+  that add to the file size. Protobuf's binary format is much more
+  compact, leading to smaller file sizes. This is a major advantage
+  for storing large datasets or for transmitting data over a network.
+  Effectively compressing XML requires a schema-specific dictionary,
+  or compressing multiple records together so that the dictionary of
+  tag/key names can be reused. However this limits the possibility
+  for random access enabled by compressing records individually.
+
+### Developer Experience
+
+* **Generated Code:** Protobuf compilers generate code in many
+  languages, providing a simple and consistent way to work with the
+  data.
+* **Type Safety:** The Protobuf schema provides strong typing, which
+  can help to prevent bugs. Parsing the wire format requires the
+  protobuf definition, meaning that the data is tied to its typed
+  representation. Conversely XML representations are only optionally
+  validated by a schema, and so by default type information is lost
+  during parsing (everything is treated as text).
+
+By converting XSDs to Protobuf definitions, `xsd-former` allows
+developers to take advantage of the benefits of Protobuf while still
+working with data that is originally defined in an XML schema.
+
+## Output formats
+
+From a single XSD (or DTD) source, XSDFormer can emit:
+
+* **Protobuf** (`.proto`) — `--proto-out`.
+* **Python XML→protobuf converters** — `--py-out`/`--py-module`.
+* **JSON Schema** — `--json-schema-out` (from the XSD, or directly from
+  a `.proto` via the `proto` subcommand).
+* **TypeSpec** (`.tsp`) — `--typespec-out` (see below).
+
+## TypeSpec output
+
+[TypeSpec](https://typespec.io/) is a compact, authorable schema
+language that fans out to OpenAPI, JSON Schema, and protobuf — and from
+those to pydantic and zod. XSDFormer emits a `.tsp` so the same model
+that backs the stored protobufs can also drive backend pydantic models
+and frontend zod validators, all interconvertible.
+
+```bash
+# Default: clean, readable TypeSpec (string-valued enums, native scalars).
+# Suited to pydantic/zod generation.
+xsdformer xsd schema.xsd --typespec-out schema.tsp
+
+# DTD sources work too (e.g. PubMed).
+xsdformer dtd pubmed.dtd --typespec-out pubmed.tsp --proto-package pubmed
+
+# proto-compat: adds @typespec/protobuf decorations (@package, @field,
+# integer-valued enums) so `tsp -> proto` can be run as a regression
+# check that it matches the directly generated proto.
+xsdformer xsd schema.xsd --typespec-out schema.tsp --proto-compat
+```
+
+The `.tsp` is a derived artifact — regenerated from the XSD alongside
+the proto, never hand-edited. The governing invariant is that
+`xsd → proto` and `xsd → tsp → proto` agree at the wire/semantic level
+(field numbers, field types, enum numbers); cosmetic differences
+(`oneof` grouping, nested-vs-hoisted placement, comments, ordering) are
+tolerated. See [`docs/adr/0001-typespec-output-format.md`](docs/adr/0001-typespec-output-format.md)
+for the full design.