An Introduction to OpenAPI’s Numeric Data Types

By Robert Delwood, a Lead API documentation writer

Data types are used extensively in programming. In fact, they’re required for all variables and data structures in almost all languages. But they’re not commonly understood by writers. To make the problem worse, how programmers use data types is different than how OpenAPI uses data types. This isn’t poor planning. Quite the opposite. It’s well designed, at least on OpenAPI’s part. But for writers to take advantage of that, some understanding of what data types are, and how they’re used by programmers is needed.

What is a Data Type?

To answer that, here’s some background. The smallest item in a computer’s memory is a bit. Ultimately, this is a single transistor. It either has electricity running through it or not. If it does have electricity, it’s said to be on. If it doesn’t, it’s off. We know this as binary, true/false, 1/0, on/off, yes/no, ja/nein. While practical, it’s hardly a useful amount of information. It only has two values. For more information, bits can be chained together. Two bits can hold four values, three bits, eight values, four bits, 16 values, and so on. Each additional bit doubles the amount of information it can store. The formula is 2x. At eight bits (28), this is 256 values. The computer industry thought that was finally a useful amount of information. For starters, that’s more than the number of characters on a standard keyboard. Eight bits were agreed on to be called a byte and that’s now the standard building block of information.

Still, in this discussion, they’re just bits, that is, 1s and 0s. We could have the following sequence:

0100 0001

That sequence has value but it doesn’t have meaning. We’re the ones who give it meaning. If we interpret that sequence as a number, a decimal number specifically, it would be 65. If we interpret that as a character, it’d be the capital letter A (as defined by ASCII). That’s the essence of data types: Assigning meaning to a cluster of bits.

Types of Data Types

There are many data types. Each programming language defines their own. Most are in common, such as integer, character, and byte. However, languages are free to implement their own data types. For instance, Java has unique data types called BigInteger and BigDecimal. In addition, data types can be defined by the programmer. This provides flexibility. For example, a human resources application would work with employees. Therefore, it’s likely it will have a custom data type they named Employee. That data type would have fields for first and last names, age, employee number, and start date, for example.

All other data types aside; we’re interested in just numbers. There are basically two kinds: Integers and non-integers.

Integers are whole counting numbers. There are no factions or decimal places. Examples include 0, 500, and -500.

Non-integers, also called floating-point numeric types, have fractions and decimal places. Examples include 2.5, -101.1, and 32000.89. What looks like integers are included, too, like 0, 500, and -500 but in practice they are treated as 0.0, 500.0, and -500.0.

In choosing the data type, there are three considerations: Range, precision, and accuracy. They are based on the number of bytes. There is complexity being skipped, too.

• The range is the numeric range the data type allows. The tables show the different data type’s ranges.

Floating-point numeric types have precision and accuracy.

• Precision is the number of decimal places. The more decimal places, the more precise the value.
• Accuracy is how accurate the number is. Computers can’t always accurately represent all numbers. For example, the number 0.1 can’t be exactly represented by four- and eight-byte floating point numbers. There will eventually be rounding errors. 0.1 can be exactly represented with 16-byte numbers. Accuracy is not a common consideration. For most calculations, it’s not an issue. It’s mentioned here for completeness.

Programmers typically declare a data type for all variables they use. The practice is that they pick the smallest data type that fits their need. For example, if they’re writing a school grading application, elementary teachers might get by with a one-byte numeral since most school rooms have only about 30 students, well within the range of a one-byte integer. Probably not at the university level. Classrooms could get to over 300. Then a two-byte numeral would work.

It’s the same for floating-point numerals. Most everyday calculations don’t need 17-point precision, often just two or three is good enough, so a four-byte floating point is good. The exception is monetary or scientific applications that need precision and accuracy. Precision, though, comes at a cost. Memory limitations and performance could be affected. Therefore, programmers have a vested interest in selecting the right data type.

OpenAPI handles numbers differently. It has only two numeric data types: integer and number.

• Integer are still whole counting numbers.
• Number are any number, integer or floating point.

OpenAPI having two data types is by design and is a good decision. It intends to be numerically agnostic. That is, it doesn’t need to know about any language-specific data types.

What is the impact to the writers?

Writers must decide which data types to use in OpenAPI. They will know what data type programmers think a number should be. Asking programmers about each field becomes onerous. Besides, it’s a task that writers should be able to do. The most basic question to ask is will the item be used counting? For instance, if the item is the number of customers or the number of Cap’t Crunch boxes on a store shelf, it’ll be a whole number, and so, an integer. If the item is the average number of users or the weight of a package, it’ll probably include a fraction, a number.

So why not just make everything a number, then? Writers could, yes. It would be technically correct and would pass linting and syntax checks. But it would be inaccurate for the client programmers. Remember, they want the smallest container that fits their need. In addition, it may be an annoyance or more if programmers get that wrong. Too small a number type and the application could throw an error. Too large, and the application’s performance could suffer. Programmers could figure this out themselves, but that costs them time and effort, two things writers are supposed to help with.

API guides should be as precise as possible. OpenAPI helps supports this through the format tag. This is an optional tag that is paired with the type tag. Format is not enforced, meaning it could be any value, and still pass validation. For numbers, OpenAPI defines four format values.

While an integer could be any integer value, it’s further specified as int32 and int64. These are the four- and eight-byte values. For floating points, these are float and double, again, representing four- and eight-byte values. OpenAPI supports the nuanced range and precision of programming languages. Not every programming language numeric data type maps directly to an OpenAPI one, but OpenAPI presents values close enough. The following is an example in OpenAPI.

It is important to use the OpenAPI-specified values. As mentioned, any value for format will pass validation. However, many third-party tools rely on those specific values. It’s in the writer’s best interest to keep to these values.

Conclusion

Data types can easily be overlooked, if not taken for granted. But they play an important part of the documentation. Keep in mind that the goal should always be great document and great document anticipates every question the programmer might have. Minding these details are a step along that journey.