What exactly is a Specification?

Question

I read or hear sentences such as:

The Java Persistence API (JPA) is a Java application programming interface specification...

or

JavaServer Faces (JSF) is a Java specification...

but I am not sure if I understand what a specification exactly is..

Lets say I create a new specification JMA, Java Math API, which is a Java Math Specification..

Is it enough that I define my specification as follows:

JMA must provide a method that adds two integers?

or, do I have to create a document something like:

JMA must provide the method: int jmaAdd(int x,int y)?

or, do I have to create the interfaces and distrubute the source code?

public interface JMA{     int jmaAdd(int x,int y); } 

or do I have to compile the interfaces and publish it as jar?

Also, can a specification contain abstract classes or classes at all? Or must it consist only of interfaces?

What makes a specification, a specification?

Answer 1

Is it enough that I define my specification as follows:

JMA must provide a method that adds two integers?

That's a specification.

It's not a very useful one, because it doesn't give many guarantees to the user of an implementation of that specification. If I wanted to write a program that adds two integers, I couldn't do it just from reading the specification.

It does give the implementor a lot of freedom, though. Generally, you want your specification to be precise in the points that matter to the user, but vague in the points that matter to the implementor. That way, the user gets the guarantees he needs to be able to write his programs, but it also gives the implementor the freedom to tailor his implementation to his particular niche.

For example, the Java Language Specification doesn't say anything about Garbage Collection. It only defines when objects are and aren't reachable, and it defines that you can create new objects. How the memory allocation works, how the garbage collector works, whether it is a reference-counting, tracing, or region-based collector, etc. all of those are left out, and thus different implementations for different niches can use different garbage collector implementations, and different implementations for the same niche can compete with each other.

or, do I have to create a document something like:

JMA must provide the method: int jmaAdd(int x,int y)?

That's also a specification. It is even less useful than the one above. It does define the name of the method, but it doesn't define what it does.

int jmaAdd(int x, int y) { return x - y; } 

is a perfectly valid implementation of that specification, as is

int jmaAdd(int x, int y) { return 0; } 

Again, there are no guarantees for the user and too much leeway (or more precisely: leeway in the wrong areas) for the implementor.

or, do I have to create the interfaces and distrubute the source code?

public interface JMA{     int jmaAdd(int x,int y); } 

I wouldn't necessarily call that a specification. That's code, and thus an implementation.

Note: of course, in Java, interfaces provide specification of behavior that classes then implement. But that's not what is meant by the term specification the way you used it in your question.

or do I have to compile the interfaces and publish it as jar?

Again, that's an implementation.

Also, can a specification contain abstract classes or classes at all? Or must it consist only of interfaces?

A specification doesn't contain anything. It's a piece of paper.

Typically, specifications are written in English. Well, actually, they are written in a specialized specification-writing language, which is often a highly stylized formal subset of English with specific semantics. For example, BCP14/RFC2119: Key words for use in RFCs to Indicate Requirement Levels defines the precise meaning of some common English words in relation to IETF standards documents. (Interestingly, it is also a specification, thus making it a specification for writing specifications.)

Formal Logic is also sometimes used, especially in Programming Language specifications to describe typing rules. And sometimes, even specialized Formal Specification Languages are used, like the Z Notation.

What makes a specification, a specification?

The simple and not very satisfying answer is that a specification is a specification if it is called a specification by people who care about specifications. (Or more generally: thought about as a specification.)

Different communities have different views on specifications. And different names for them.

For example, the original specification for the scheme programming language was simply published in a scientific report. Then after a few rounds of improvements and new reports, they published the "Revised Report on the Algorithmic Language Scheme". And after that the "Revised Revised Report on the Algorithmic Language Scheme". With that began a kind of in-joke, and the current version of the language is defined in the "Revised Revised Revised Revised Revised Revised Revised Report on the Algorithmic Language Scheme", commonly written the "Revised⁷ Report on the Algorithmic Language Scheme" or just "R⁷RS".

None of those reports is called a "specification", yet every single one is a specification. Before Scheme, ALGOL also used the term "Report", as did several other languages.

Internet RFCs are also a good example. Technically, all an RFC is, is a "Request for Comments". Only very few of those RFCs are actually elevated to "Standards" status. Some are also "Best Current Practices". None of them are called "Specification", but many of them are treated that way. For example, HTTP is not a standard, but it is treated as both a standard and a specification, and significant portions of our new world economy are built on that.

If you want to get a feel for specifications, it's probably best if you just read some:

• Haskell 2010 Language Report (Another example of the name "Report")
• Scala Language Specification Version 2.11
• ECMA-262 6th Edition, The ECMAScript 2015 Language Specification
• The Java Language Specification, Java SE 8 Edition
• The Java Virtual Machine Specification, Java SE 8 Edition
• The HTTP Specifications, including but not limited to
  • RFC7230: HTTP/1.1 Message Syntax and Routing
  • RFC7231: HTTP/1.1 Semantics and Content
  • RFC7540: HTTP/2
  • RFC7541: HPACK Header Compression for HTTP/2
• The HTML Living Standard (aka HTML5)