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

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 "R7RS".

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)

Answer 2

I think the key idea here is "specification doesn't include an implementation."

When Sun was the steward of Java, they would write specifications for features like Java EE and JPA, giving other vendors the freedom to implement as they wished. Sun would usually have an implementation of their own with which to compete, but their goal was to sell hardware. Encouraging other vendors to provide competing implementations only furthered that aim.

Sun's specifications would come with neither code nor JARs; they were prose descriptions of how the code would work.

Answer 3

In Java-land these specifications are started as Java Specification Requests (JSRs).

Defined here:

https://jcp.org/en/jsr/overview

Once accepted, these are specifications.

Answer 4

If one does a Google search, one gets:

spec·i·fi·ca·tion ˌspesəfəˈkāSH(ə)n/ noun noun: specification; plural noun: specifications

an act of describing or identifying something precisely or of stating a precise requirement.

example: "give a full specification of the job advertised"

(...)

It thus means you describe how something should work, not what one has to do in order to let it work (which is the implementation)

There are formal languages to specify for instance pre- and postconditions of a method. One can then use tools to (semi-)automatically verify a subset of these conditions.

Other formal languages enable you to do automated constraint programming (like for instance my specification to solve a multi-sudoku puzzle).

Another example is CSS: you specify how your webpage should look like, the instructions on how to make a button green are not part of CSS.