Create the Decimal type (#117)

* Add a schema definition for the `Decimal` type.

* Add a protobuf implementation of the Decimal type.

* Updates to Decimal type:

* digits -> significand (based on steering committee feedback)
* Updated package names
* Changed exponent from int64 to int32 (had meant to do this sooner).

* Update common-components/schemas/type/decimal.md

* Rename the api directory to aip to match proto package.

* Update documentation to refer to `significand` rather than `digits`.

* Update common-components/schemas/type/decimal.md

Co-authored-by: Yusuke Tsutsumi <yusuke@tsutsumi.io>

* Update common-components/schemas/type/decimal.md

Co-authored-by: Yusuke Tsutsumi <yusuke@tsutsumi.io>

* Consistency fixes

* Add a JSON Schema for Decimal.

* Add note comparing range to double and decimal64.

* Convert JSON schema to YAML.

* Add trailing newline to decimal.proto.

* Make JSON schema examples look like JSON.

* Update Decimal JSON schema to be stricter.

* Remove defaults from JSON schema; comment consistency.

---------

Co-authored-by: Yusuke Tsutsumi <yusuke@tsutsumi.io>

Author: rofrankel

common-components/json_schema/decimal.yaml

@@ -0,0 +1,39 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://example.com/product.schema.json
+title: Decimal
+description: |
+  Represents a decimal number in a form similar to scientific notation.
+
+  Examples:
+  17            === {"significand": 17,   "exponent": 0}
+  -0.005        === {"significand": -5,   "exponent": -3}
+  33.5 million  === {"significand": 335,  "exponent": 5}
+  11/8 (1.375)  === {"significand": 1375, "exponent": -3}
+
+  Note that the range of a Decmial exceeds that of a JSON `number` (double),
+  as well as that of a `decimal64`.
+type: object
+required:
+- significand
+- exponent
+additionalProperties: false
+properties:
+  significand:
+    description: The significant digits of the number.
+    type: integer
+    format: int64
+  exponent:
+    description: |
+      Represents the position of the decimal point within the significand.
+
+      When the exponent is 0, the value of the Decimal is simply the value of
+      `significand`.
+
+      When the exponent is greater than 0, represents the number of trailing
+      zeroes after the significant digits.
+
+      When the exponent is < less than, represents how many of the
+      significant digits (and implicit leading zeroes, as needed) come after
+      the decmial point.
+    type: integer
+    format: int32

common-components/proto/aip/type/decimal.proto

@@ -0,0 +1,38 @@
+syntax = "proto3";
+
+package aip.type;
+
+option cc_enable_arenas = true;
+option go_package = "aip.golang.org/genproto/common-components/type/decimal;decimal";
+option java_multiple_files = true;
+option java_outer_classname = "DecimalProto";
+option java_package = "dev.aip.type";
+option objc_class_prefix = "AIP";
+
+// Represents a decimal number in a form similar to scientific notation.
+//
+// Examples:
+// 17            === {significand: 17   exponent: 0} (or just {significand: 17})
+// -0.005        === {significand: -5   exponent: -3}
+// 33.5 million  === {significand: 335  exponent: 5}
+// 11/8 (1.375)  === {significand: 1375 exponent: -3}
+//
+// Note that the range of a Decmial exceeds that of a JSON `number` (double), as
+// well as that of a `decimal64`.
+message Decimal {
+  // The significant digits of the number.
+  int64 significand = 1;
+
+  // Represents the position of the decimal point within the significand.
+  //
+  // When the exponent is 0, the value of the Decimal is simply the value of
+  // `significand`.
+  //
+  // When the exponent is greater than 0, represents the number of trailing
+  // zeroes after the significant digits.
+  //
+  // When the exponent is less than 0, represents how many of the significant
+  // digits (and implicit leading zeroes, as needed) come after the decmial
+  // point.
+  int32 exponent = 2;
+}

common-components/schemas/type/decimal.md

@@ -0,0 +1,40 @@
+# Decimal
+
+The `Decimal` type represents a decimal numeric value. It uses a non-floating
+point representation in order to avoid precision errors.
+
+## Schema
+
+A `Decimal` represents a decimal number in a form similar to scientific
+notation.
+
+It has two fields:
+
+- The `significand` field is a 64-bit integer representing the significant
+  digits of the number.
+- The `exponent` field is a 32-bit integer represesnting the position of the
+  deicmal point within the value of the `significand` field; it is the power of
+  ten to which `significand` should be raised.
+
+  When the exponent is `0`, the value of the `Decimal` is simply the value of
+  `significand`.
+
+  When the exponent is greater than 0, represents the number of trailing zeroes
+  after the significant digits.
+
+  When the exponent is less than 0, represents how many of the significant
+  digits (and implicit leading zeroes, as needed) come after the decimal point.
+
+The general formula for converting a `Decimal` to its numeric value is
+`significant * 10^exponent`, where `*` represents multplication and `^`
+represents exponentiation.
+
+Note: The range of a Decmial exceeds that of a JSON `number` (double), as well
+as that of a `decimal64`.
+
+## Examples
+
+- 17 === `{significand: 17, exponent: 0}`
+- -0.005 === `{significand: -5, exponent: -3}`
+- 33.5 million === `{significand: 335, exponent: 5}`
+- 11/8 === 1.375 === `{significand: 1375, exponent: -3}`