# csharpstandard is where the C# specification text is actually drafted

> dotnet/csharpstandard is the working space of the ECMA C# standard committee, holding the draft text for each language version plus the tooling that converts it to Word, keeps its section anchors correct and compiles every example in the document. It is a document repository with a build system, not a library, and its value is that the specification is auditable in Markdown rather than only in a PDF.

**dotnet/csharpstandard** — Working space for ECMA-TC49-TG2, the C# standard committee.

- Repository: https://github.com/dotnet/csharpstandard
- Stars: 818 · Forks: 99
- Language: C#
- License: CC-BY-4.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/dotnet-csharpstandard

## Branches are versions, and the default one is a draft

This repository is the working space for ECMA-TC49-TG2, the C# standard committee. The default branch is draft-v8, and the branch layout is the documentation structure.

The draft-v9 branch has the draft pull requests and issues for C# 9. The draft-v8 branch has the evolving draft text for C# 8. The standard-v7 branch has the ECMA C# 7 standard text in Markdown format, and the same holds for standard-v6 with the C# 6 standard. The standard-v5 branch has the ECMA C# 5 standard, converted to Markdown, and the README notes that this version is stored there as a base markdown version to compare with future updated standard texts.

That last point is the quiet purpose of the whole repository. ECMA publishes the standard as a PDF and as a Word document, which is fine for a formal deliverable and poor for differential work. Keeping an older version as Markdown in git means that when a new standard text arrives, you can diff the two word by word.

A README.md in the standard folder contains a detailed table of contents for the standard.

So there are two audiences. The committee works here, and anyone who needs the precise text of a C# version can read it in Markdown rather than only in the published document.

## The tools are what make the text maintainable

The tools folder is described as containing tools related to maintaining and converting the ECMA C# spec, ECMA-334. Four of them are worth understanding because each solves a specific way the specification would otherwise rot.

The first is GetGrammar, which contains an ANTLR grammar-extraction tool and support files.

```bash
- ExtractGrammar.exe - the simple-minded grammar-extraction program. It processes only *one* md file.
```

The batch file invokes ExtractGrammar on each Markdown file of the specification that contains ANTLR grammar blocks, in clause order, inserting headers along the way. The result is a file called grammar.md that is a direct replacement for that file in the specification repository. The README is candid about a known wart here: there is an extraneous blank line at the beginning of each of the lexical, syntactic and unsafe grammars, and the amount of programming effort needed to stop that happening seems huge compared with simply deleting those three lines manually.

That is the kind of detail a working repository contains and a published PDF does not, and it tells you the state of the tooling honestly.

The second tool is MarkdownConverter, used by the committee to produce a Word format of the standard for submission to ECMA or ISO. It is run on each pull request so that a correct format can always be produced when needed.

The third is StandardAnchorTags, which creates the outline using section numbers and updates all links to the correct section number. Its purpose is to ensure that all references continue to point at the correct section and that the table of contents shows the correct section numbers. Contributors who add sections are pointed at the contributor guide, and the tool is run on each pull request in a dry-run mode to ensure the changes parse correctly. When a pull request is merged, the tool runs to update all section links.

## Every example in the spec is compiled and run

The ExampleExtractor and ExampleTester pair is the fourth tool group, and it is the one with the most leverage.

The two tools work in tandem to test that the examples presented work, or fail where invalid code is presented, as expected. ExampleExtractor populates a temporary directory with code and metadata extracted from the standard. ExampleTester then compiles and runs, where applicable, that code. A shell script named test-examples.sh provides an easy way of running both tools together.

This is what keeps the document honest. A specification with examples that no longer compile is a specification with a slowly growing set of lies, and the fix in most projects is to stop checking. Here the examples are extracted from the Markdown and built on every change, so a language change that invalidates an example surfaces as a failing test rather than as a documentation bug that a reader finds the hard way.

It also explains the HTML comments in the document, which the README describes as being there for the sake of tooling. Some help in converting the standard to Word, and others are for automated testing purposes. Specifically, some automated test comments refer to error codes that are specific to the Microsoft C# compiler, such as CS0509, to test that compilation fails as expected where an example presents deliberately invalid code.

And here is the caveat the README states plainly: those error codes are not part of the standard and should not be viewed as any kind of compliance check for other compilers. More broadly, no comments should be regarded as being part of the standard itself.

That is a distinction worth keeping in mind when you cite this repository. The prose is normative. The comments are tooling.

## The admin folder records how each version was assembled

The admin folder is described as a home for administrative files, and for now it contains separate logs for past work (V6, V7), present work (V8) and future work (V9) going on to add new features.

That is a small detail with a large meaning for anyone who wants to understand how a language version is actually produced. Feature proposals, their disposition, the discussions and the decisions are all recorded, split by the version they belong to. The repository therefore holds not only the outcome but the trail.

The release list on the repository reflects the same idea. The tags include V8-With-DIM, described as V8 with DIM, and V8-Before-Dim, described as a checkpoint for the v8 branch before DIM merged, both dated 2025-10-22, and C#-7.3, described as the C# standard version 7.3, also dated 2025-10-22. Checkpoint tags like the before and after pair exist so that a reader can see exactly what a specific merge changed.

Two further structural notes. The project has adopted the Contributor Covenant code of conduct, referenced through the .NET Foundation Code of Conduct, and the project is supported by the .NET Foundation. The repository root carries a .markdownlint-cli2.jsonc configuration and a .vscode directory, so there is linting and editor configuration for the Markdown itself, and a .gitattributes file, which for a repository that produces PDFs and DOCX is where line ending and file handling rules for the generated artefacts would live.

## Two licences, and the split is deliberate

The licensing here has two parts and the split is the interesting bit.

The text is licensed under the Creative Commons license, in the LICENSE file. The code for the tools is licensed under the MIT license, in the LICENSE-CODE file.

That separation is the right one for a standards body. A specification is a document meant to be read, quoted and implemented by anyone, including commercial implementers, so a Creative Commons licence on the prose is the sensible choice. The tooling is software that happens to live in the same repository, and MIT is the conventional licence for that. If they had been bundled under one licence, one of the two would have been worse served.

Note also that the repository does not claim to be the official published standard. The README repeatedly directs readers to the ECMA site for the official standard, for each of versions 5, 6 and 7, with the ECMA-334 publication as the reference. What the repository holds is the Markdown working text, which is the input to the process, not the certified artefact.

If you need to cite the C# standard in a document that will be checked, cite the ECMA publication. If you need to link a specific clause, diff two versions, or point a tool at the grammar, this repository is the place.

## Where this repository is the wrong source

The first limitation is that it is not a tutorial. This is a formal specification written for implementers and language lawyers. Nothing here teaches you C#, and the structure, the clause numbering and the grammatical notation will be hostile to someone looking for an explanation.

The second limitation is that it is not a description of compiler behaviour. The README says the error codes in the test comments are specific to the Microsoft compiler and are not a compliance check for other compilers. A C# implementation that differs from Roslyn in a corner case is not thereby non-conforming, and the document will not tell you what any particular compiler does.

The third is that branches are versions, and the default branch is a draft. If you pull the default branch of this repository expecting the current C# specification, you will get the evolving C# 8 draft text instead. The published C# 7 text lives on standard-v7 and the published C# 6 text on standard-v6. Anyone using this as a reference needs to know which branch they want before they read anything.

The fourth is that the tooling is Windows-flavoured. ExtractGrammar.exe is a Windows executable and GetGrammar.bat is a Windows batch file. The README says nothing about cross-platform equivalents for those two, though the test-examples.sh script is a shell script. The StandardAnchorTags and MarkdownConverter tools are described without their platform requirements. If you are contributing, you will need to know what you have available.

And the fifth is that this is a committee workspace, not a mirror of the published document. If you need an authoritative, versioned, citable text, use ECMA-334.

## How it compares to the published PDF or the Microsoft documentation

The published standard on the ECMA site is the authoritative artefact. It is what a conformance claim points at, and it is the only version with a formal identity.

Microsoft's online documentation is the practical reference. It is searchable, it is versioned by runtime, and it is written for people trying to use the language rather than implement it. What it is not is a normative text, and it will not tell you which behaviour is required and which is an implementation detail left to the implementer.

This repository sits in a different position from both. Its advantage over the PDF is that it is Markdown in git, so it diffs, so it has history, and so it has machine-checkable examples. Its advantage over Microsoft docs is authority: this is the committee's own text, so it settles questions rather than describing one implementation.

The tooling is the part nobody else has. If you write a compiler, a linter, a syntax highlighter, a parser generator front end or a documentation tool for C#, the ANTLR grammar extraction is directly useful, because it gives you the grammar in a form a tool can consume rather than a form a human reads. The anchor tag tool solves the section renumbering problem that every large document accumulates. The example tester gives you a corpus of valid and deliberately invalid code with the expectation of each.

So the realistic use is a combination. Read the Microsoft docs to learn, cite ECMA-334 when you need authority, and use this repository when you need to verify, diff or machine-process the text.

The last point about machine processing is worth emphasising. A specification that is only available as a PDF is a specification that only humans can consult. Making the text available in Markdown with extraction tooling is what allows the standard to be checked automatically, and that is a public good even for people who never contribute a clause.

## Conclusion

csharpstandard fits anyone who needs the authoritative C# specification text in a form they can diff, search, script against or link into, and it fits tooling authors who need to know exactly what the standard says rather than what one compiler accepts. It does not fit a developer who wants to learn the language, since the document is a formal specification rather than a tutorial, and it does not fit as a source of compiler behaviour, because the README is explicit that the Microsoft compiler error codes embedded in the test comments are not part of the standard and are not a compliance check for other compilers. Before relying on it, check the branch you need against the official ECMA publication, since the repository holds drafts as well as published standards, and read the contributor guide before opening a pull request because the anchor and grammar tooling run on every change.

## FAQ

### What is dotnet/csharpstandard for?

It is the working space for ECMA-TC49-TG2, the C# standard committee. The repository holds the draft and standard text for each language version in Markdown, plus the tooling used to convert the text to Word, keep its section anchors correct and test the examples it contains.

### Which branch contains the C# 7 standard text?

The standard-v7 branch has the ECMA C# 7 standard text in Markdown format, standard-v6 has the C# 6 standard and standard-v5 has the C# 5 standard. The draft-v8 branch carries the evolving draft text for C# 8 and draft-v9 holds the draft pull requests and issues for C# 9.

### How are the examples in the C# standard checked?

ExampleExtractor populates a temporary directory with code and metadata extracted from the standard, and ExampleTester then compiles and runs that code where applicable. The test-examples.sh script runs both tools together, so a change that invalidates an example shows up as a failing test.

### What does the GetGrammar tool in the csharpstandard tools folder do?

It contains an ANTLR grammar-extraction tool and support files. GetGrammar.bat invokes ExtractGrammar on each Markdown file of the specification that contains ANTLR grammar blocks, in clause order, and the resulting grammar.md is a direct replacement for that file in the specification repository.

### Can I use the Microsoft compiler error codes in the standard as a compliance check?

No. The README states that the error codes in the automated test comments are specific to the Microsoft C# compiler and are not part of the standard, and that they should not be viewed as any kind of compliance check for other compilers. More broadly, no comments in the document should be regarded as being part of the standard itself.

### What licence applies to the csharpstandard repository?

The specification text is licensed under the Creative Commons license in the LICENSE file, and the code for the tools is licensed under the MIT license in the LICENSE-CODE file. The project is supported by the .NET Foundation.

## Sources

- [dotnet/csharpstandard on GitHub](https://github.com/dotnet/csharpstandard)
- [Issues](https://github.com/dotnet/csharpstandard/issues)
- [License: CC-BY-4.0](https://github.com/dotnet/csharpstandard/blob/draft-v8/LICENSE)
- [README](https://github.com/dotnet/csharpstandard/blob/draft-v8/README.md)
- [Releases](https://github.com/dotnet/csharpstandard/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dotnet-csharpstandard