<p>Recently a team of Rust developers have started working on the Rust specification. This <a href="https://rust-lang.github.io/rfcs/3355-rust-spec.html" rel="noreferrer">RFC 3355</a> introduced the proposal. My question is that basically what's the difference between a <em>spec</em> and a <em>reference</em> for a programming language? Rust currently has a <a href="https://doc.rust-lang.org/reference/" rel="noreferrer">reference</a>. 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?</p>
<p>I didn't add rust tag to the question, because my question is regardless of the programming language.</p>
<h4>Further links:</h4>
<p><a href="https://blog.rust-lang.org/inside-rust/2023/11/15/spec-vision.html" rel="noreferrer">https://blog.rust-lang.org/inside-rust/2023/11/15/spec-vision.html</a></p>

<specification>
What is the difference between specification and a reference for programming languages?
<h1>Who to blame</h1>
<p>A <em>reference</em> 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.</p>
<p>A <em>specification</em> is an <em>exact</em> description of a language. This generally includes specifying every rule a hypothetical compiler would have to follow in order to be &quot;compliant&quot;, 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.</p>
<p>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.</p>

CC BY-SA 4.0
2024-01-30T12:59:17.353Z
2024-02-01T22:34:32.447Z
2024-02-01T22:34:32.447Z
blueberry
CC BY-SA 4.0
2024-01-30T18:47:44.207Z
Would it be fair to say that the language spec. is for compiler-writers, and the language reference is for developers?
gidds
CC BY-SA 4.0
2024-01-30T20:17:08.680Z
@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.)
Eric Lippert
CC BY-SA 4.0
2024-01-30T22:51:25.403Z
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.
Simon Geard
CC BY-SA 4.0
2024-02-01T11:37:17.510Z
C++ perspective: the [Reference](https://cppreference.com/) is the developer's user manual. It describes everything a language user needs to know. The [Specification](https://github.com/cplusplus/draft/releases/tag/n4917) 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.
ojdo
<p>While there is overlap in how they <em>look</em>, the difference is the <em>purpose</em> of the document.</p>
<p>A <strong>specification</strong> is <em>prescriptive</em>. It DEFINES how the language is supposed to work. Specifications are <em>primary</em>: the authoritative source documents.</p>
<p>A <strong>reference</strong> is <em>descriptive</em>.  It describes how the language works. References are derivative works, based on the specifications (or on other secondary sources).</p>
<p>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.</p>
<p>An analogy might be the actual laws passed by a legislature (prescriptive, spcification) vs. a legal textbook that describes those laws (descriptive, reference).</p>
<p>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:</p>
<p><a href="https://262.ecma-international.org/14.0/?_gl=1*ablqyx*_ga*NjAwODYzMjcxLjE3MDY2NzkwMTg.*_ga_TDCK4DWEPP*MTcwNjY3OTAxNy4xLjAuMTcwNjY3OTAxNy4wLjAuMA..&amp;_ga=2.173648103.592924252.1706679018-600863271.1706679018#sec-date" rel="noreferrer">ECMAScript Date Constructor (Section 21.4.2.1)</a></p>
<p>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:</p>
<p><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date" rel="noreferrer">MDN JavaScript Date Constructor</a></p>
<p>(There are also important differences between a Reference, a Textbook, and a Tutortial, but that's a different question...)</p>
<p>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.</p>
<p>With regard to the Rust question in the original post: &quot;<em>what's the purpose of writing a specification when the reference can be completed?</em>&quot;</p>
<p>One of the citations in the original post, <a href="https://rust-lang.github.io/rfcs/3355-rust-spec.html" rel="noreferrer">The Rust RFC Book</a>, has this to say about why the Rust Reference alone is not sufficient:</p>
<blockquote>
<p>Why do we want a Rust specification at all?</p>
<p>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 <em>normative</em>.</p>
</blockquote>
<p>The emphasis on &quot;normative&quot; was added by me to highlight that the raison d'être for a specification is to be prescriptive.  That's what &quot;normative&quot; means. The &quot;normative vs. informative&quot; dichotomy is just another way of expressing the &quot;prescriptive vs. descriptive&quot; dichotomy.  See this article that uses one set of words to explain the other: <a href="https://www.standards.govt.nz/news-and-updates/normative-vs-informative/#:%7E:text=Normative%20elements%20are%20those%20that,offer%20help%20to%20understand%20concepts." rel="noreferrer">Standards New Zealand article</a>.</p>

CC BY-SA 4.0
2024-01-31T03:39:14.097Z
2024-02-01T00:36:40.573Z
2024-02-01T00:36:40.573Z
Syntax Junkie
CC BY-SA 4.0
2024-01-31T04:23:24.103Z
Perhaps provide a brief summary of the webpage article you linked?
Redz
CC BY-SA 4.0
2024-02-01T18:39:13.047Z
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.
John Bollinger
CC BY-SA 4.0
2024-02-01T20:23:31.177Z
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.
supercat
<p>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.</p>

CC BY-SA 4.0
2024-01-30T12:57:15.820Z
2024-01-30T12:57:15.820Z
Ginger
CC BY-SA 4.0
2024-01-30T22:28:53.090Z
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.
supercat
CC BY-SA 4.0
2024-01-31T08:11:03.777Z
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.
ruakh
CC BY-SA 4.0
2024-01-31T19:20:12.957Z
@ruakh: Small languages can be completely specified. A common example for many developers might be regular languages, which are specified by [Kleene algebras](https://en.wikipedia.org/wiki/Kleene_algebra), also known as closed semirings. This example is illuminating because the semantics allow for nondeterministic execution while still determining the results of operations.
Corbin
CC BY-SA 4.0
2024-02-01T20:38:14.517Z
@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.
supercat
CC BY-SA 4.0
2024-02-02T08:58:27.373Z
@Corbin Even the tiniest language specification will leave some things implementation-defined, for example the font size of the output.
Michael Kay
# What is the difference between specification and a reference for programming languages?
Posted by: username_0 on 2024-01-30
Recently a team of Rust developers have started working on the Rust specification. This [RFC 3355](https://rust-lang.github.io/rfcs/3355-rust-spec.html) 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](https://doc.rust-lang.org/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:

<https://blog.rust-lang.org/inside-rust/2023/11/15/spec-vision.html>
**Tags:** specification
---
## 3 answers
### Answer by username_1 on 2024-01-30. Score: 29 | Accepted answer
# 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.
> **Comments:**
> **username_2** (2024-01-30): Would it be fair to say that the language spec. is for compiler-writers, and the language reference is for developers?  
> **username_3** (2024-01-30): @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.)  
> **username_4** (2024-01-30): 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.  
> **username_5** (2024-02-01): C++ perspective: the [Reference](https://cppreference.com/) is the developer's user manual. It describes everything a language user needs to know. The [Specification](https://github.com/cplusplus/draft/releases/tag/n4917) 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.  
---
### Answer by username_6 on 2024-01-31. Score: 15
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 21.4.2.1)](https://262.ecma-international.org/14.0/?_gl=1*ablqyx*_ga*NjAwODYzMjcxLjE3MDY2NzkwMTg.*_ga_TDCK4DWEPP*MTcwNjY3OTAxNy4xLjAuMTcwNjY3OTAxNy4wLjAuMA..&_ga=2.173648103.592924252.1706679018-600863271.1706679018#sec-date)

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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date)

(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](https://rust-lang.github.io/rfcs/3355-rust-spec.html), 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](https://www.standards.govt.nz/news-and-updates/normative-vs-informative/#:%7E:text=Normative%20elements%20are%20those%20that,offer%20help%20to%20understand%20concepts.).
> **Comments:**
> **username_7** (2024-01-31): Perhaps provide a brief summary of the webpage article you linked?  
> **username_8** (2024-02-01): 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.  
> **username_9** (2024-02-01): 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.  
---
### Answer by username_10 on 2024-01-30. Score: 7
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.
> **Comments:**
> **username_9** (2024-01-30): 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.  
> **username_11** (2024-01-31): 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.  
> **username_12** (2024-01-31): @ruakh: Small languages can be completely specified. A common example for many developers might be regular languages, which are specified by [Kleene algebras](https://en.wikipedia.org/wiki/Kleene_algebra), also known as closed semirings. This example is illuminating because the semantics allow for nondeterministic execution while still determining the results of operations.  
> **username_9** (2024-02-01): @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.  
> **username_13** (2024-02-02): @Corbin Even the tiniest language specification will leave some things implementation-defined, for example the font size of the output.  
---
