Recently a team of Rust developers have started working on the Rust specification. This RFC 3355 introduced the proposal. My question is that basically what's the difference between a spec and a reference for a programming language? Rust currently has a reference. I know this reference is currently incomplete, but what's the purpose of writing an specification when the reference can be completed? I mean, is there any fundamental difference between specification and reference?

I didn't add rust tag to the question, because my question is regardless of the programming language.

Further links:



3 Answers 3


Who to blame

A reference is generally an informal document. It tries its best to show all the parts of a compiler/language, and all behaviours from these parts. However, if something in the compiler doesn't agree with the reference, the compiler is (nix bugs) usually considered correct. The reference is updated to meet the behaviour of the compiler.

A specification is an exact description of a language. This generally includes specifying every rule a hypothetical compiler would have to follow in order to be "compliant", from parsing to runtime behaviour. If the specification and compiler disagree, (nix bugs in the specification, which can happen), the compiler is incorrect. The compiler is updated to comply with the specification.

In languages with multiple compilers, each compiler may have its own reference, but each compiler may comply to the same standard. An excellent example of this is SML, which has compilers such as SML/NJ, MLTon, MoscowML, and many more - each of these have their own reference, but each follows the SML specification. In situations such as this, certain compilers may implement extensions on top of the specification - these would obviously be in the reference, but not the specification.

  • 3
    $\begingroup$ Would it be fair to say that the language spec. is for compiler-writers, and the language reference is for developers? $\endgroup$
    – gidds
    Jan 30 at 18:47
  • 4
    $\begingroup$ @gidds: Yes. Both documents are for the developer, but the specification is written primarily for the compiler development team, not the end user. (Remember also that team consists of designers, compiler developers, testers, technical writers, evangelists, and so on. Compiler teams do lots of spec-driven work that is not just development.) $\endgroup$ Jan 30 at 20:17
  • 10
    $\begingroup$ Another way to look at it - the reference describes how it does work, a specification describes how it should work. For a single implementation, the latter isn't particularly important... but if you want multiple implementations, it's critical. $\endgroup$ Jan 30 at 22:51
  • $\begingroup$ C++ perspective: the Reference is the developer's user manual. It describes everything a language user needs to know. The Specification is the langauge implementors' user manual. It describes everything a lanugage implementation developer needs to know. The specification therefore is a superset of the reference, which typically is also much less rigorously worded, but much easier to read, while omitting edge cases. The spec cannot take such shortcuts. $\endgroup$
    – ojdo
    Feb 1 at 11:37

While there is overlap in how they look, the difference is the purpose of the document.

A specification is prescriptive. It DEFINES how the language is supposed to work. Specifications are primary: the authoritative source documents.

A reference is descriptive. It describes how the language works. References are derivative works, based on the specifications (or on other secondary sources).

Why have both? Specifications are often written in highly rarefied, technical language that is of use to people implementing language compilers or interpreters. References, on the other hand, attempt to distill the specification into more digestible information for users of the language. There will only ever be ONE specification from the designer(s) of the language (albeit, possibly with different versions), but there may be zero or more references, depending on how many authors want to take a hand at trying to explain the specification for more ordinary audiences.

An analogy might be the actual laws passed by a legislature (prescriptive, spcification) vs. a legal textbook that describes those laws (descriptive, reference).

For example, take a look at this section from the ECMAScript specification (that defines the JavaScript language). It specifies how the Date constructor should operate. It's incredibly detailed with specific implementation requirements:

ECMAScript Date Constructor (Section

I hope you can see why a Reference may try to distill this down to something a developer can use to quickly look up the syntax and high-level details about how to use the Date Constructor. For example, see this reference page from the Mozilla Developer Network:

MDN JavaScript Date Constructor

(There are also important differences between a Reference, a Textbook, and a Tutortial, but that's a different question...)

Keep in mind that the complexity and/or completeness is not the crucial difference between a specification and a reference. I've worked with some specifications that were so simple and clear that I never needed to look for a reference. And I've worked with some references that were so poorly written that I ended up looking at the specification in order to get some clarity. So complexity is not the main difference. The main difference is the prescriptive vs. descriptive purpose of the documents.

With regard to the Rust question in the original post: "what's the purpose of writing a specification when the reference can be completed?"

One of the citations in the original post, The Rust RFC Book, has this to say about why the Rust Reference alone is not sufficient:

Why do we want a Rust specification at all?

Things like the Rust Reference, the Unsafe Code Guidelines Project, the Rustonomicon, and so on, all exist to fulfill certain needs.....Unfortunately, their use is currently limited, because none of these are complete, entirely accurate, or normative.

The emphasis on "normative" was added by me to highlight that the raison d'ĂȘtre for a specification is to be prescriptive. That's what "normative" means. The "normative vs. informative" dichotomy is just another way of expressing the "prescriptive vs. descriptive" dichotomy. See this article that uses one set of words to explain the other: Standards New Zealand article.

  • 1
    $\begingroup$ Perhaps provide a brief summary of the webpage article you linked? $\endgroup$
    – Redz
    Jan 31 at 4:23
  • $\begingroup$ This. The fundamental difference between the two types of documents is exactly purpose and role, as described here. Everything else -- language used, precision, coverage of implementation details -- they all follow on. $\endgroup$ Feb 1 at 18:39
  • $\begingroup$ An important trait of normative specifications is that they partition the universe into useful categories of things that are conforming and things that are not conforming. A specification for X can only exercise normative authority in circumstances where an otherwise-conforming X could be rendered non-conforming by failing to satisfy a particular requirement. $\endgroup$
    – supercat
    Feb 1 at 20:23

A specification is an exact, unambiguous, and fully complete description of a language's syntax and behavior; a reference is more of an overview of the language, written more informally. It's like the difference between a blueprint of a house and a book describing the house. In the case of Rust, as the RPC describes, there are multiple documents which attempt to be a blueprint; they are suggesting consolidating them into one location. The Rust Reference (from my brief glance over it) seems to already be close in structure to a specification; it's just incomplete.

  • 3
    $\begingroup$ Language specifications should ideally be exact and unambiguous, but specifications written for languages which are already in use can sometimes be a bit hand-wavy, especially if implementations do certain things differently, none of which is unambiguously the best. $\endgroup$
    – supercat
    Jan 30 at 22:28
  • $\begingroup$ I don't think it's true that specifications are "fully complete"; in my experience they nearly always allow some variation between implementations, as well as some nondeterminism. $\endgroup$
    – ruakh
    Jan 31 at 8:11
  • $\begingroup$ @ruakh: Small languages can be completely specified. A common example for many developers might be regular languages, which are specified by Kleene algebras, also known as closed semirings. This example is illuminating because the semantics allow for nondeterministic execution while still determining the results of operations. $\endgroup$
    – Corbin
    Jan 31 at 19:20
  • $\begingroup$ @ruakh: A language specification can specify that some constructs may, when given certain particular inputs, select freely from among multiple possible outputs, without any ambiguity as to what outputs would be permissible for any particular input. The question of whether a complex sequence of operations could yield some particular output may be uncomputable, but that wouldn't imply any ambiguity in the specification. $\endgroup$
    – supercat
    Feb 1 at 20:38
  • $\begingroup$ @Corbin Even the tiniest language specification will leave some things implementation-defined, for example the font size of the output. $\endgroup$ Feb 2 at 8:58

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .