Create the Money type. (#116)

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

* Add a protobuf implementation of the Money type.

* Update common-components/proto/api/type/money.proto

* Update common-components/proto/api/type/money.proto

* Update common-components/proto/api/type/money.proto

* Change currency code extension prefix to X-.

* Update decimal import.

* Consistency updates

* Add a JSON schema for Money.

* Make JSON schema examples look like JSON.

* Improvements to JSON schema for Money:

* Specify required fields
* Disallow additional properties
* Add trailing newline.

* Rename amount to quantity.

Also, fix the "One and a half Bitcoin" example.

* Update common-components/json_schema/money.yaml

Co-authored-by: Richard Gibson <[email protected]>

---------

Co-authored-by: Richard Gibson <[email protected]>

Author: rofrankel

common-components/json_schema/money.yaml

@@ -0,0 +1,36 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://example.com/product.schema.json
+title: Money
+description: |
+  Represents an amount of money with its currency type.
+
+  Examples:
+
+  Five US dollars === `{"currency_code": "USD", "quantity": {"significand": 5}}`
+  One and a half Bitcoin ===
+    `{"currency_code": "X-BTC", "quantity": {"significand": 15, "exponent": -1}}`
+type: object
+required:
+- currency_code
+- quantity
+additionalProperties: false
+properties:
+  currency_code:
+    description: |
+      A currency code.
+
+      This may be a three-letter currency code defined in ISO 4217.
+
+      APIs may define additional currency codes that are not included in the ISO
+      4217 standard (for example, virtual currencies or cryptocurrencies). These
+      must start with "X-", in order to distinguish them from potential future
+      ISO 4217 codes.
+
+      Examples:
+        "USD"  - ISO 4217 code for United States dollar.
+        "X-BTC" - Potential API-defined extension for Bitcoin.
+        "X-RBX" - Potential API-defined extension for the virtual currency Robux.
+    type: string
+  quantity:
+    description: The quantity of currency.
+    $ref: decimal.yaml#/definitions/Decimal

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

@@ -0,0 +1,39 @@
+syntax = "proto3";
+
+package aip.type;
+
+option cc_enable_arenas = true;
+option go_package = "aip.golang.org/genproto/common-components/type/money;money";
+option java_multiple_files = true;
+option java_outer_classname = "MoneyProto";
+option java_package = "dev.aip.type";
+option objc_class_prefix = "AIP";
+
+import "aip/type/decimal.proto";
+
+// Represents an amount of money with its currency type.
+//
+// Examples:
+//
+// Five US dollars === `{currency_code: "USD" quantity: {significand: 5}}`
+// One and a half Bitcoin ===
+//   `{currency_code: "X-BTC" quantity: {significand: 15 exponent: -1}}`
+message Money {
+  // A currency code.
+  //
+  // This may be a three-letter currency code defined in ISO 4217.
+  //
+  // APIs may define additional currency codes that are not included in the ISO
+  // 4217 standard (for example, virtual currencies or cryptocurrencies). These
+  // must start with "X-", in order to distinguish them from potential future
+  // ISO 4217 codes.
+  //
+  // Examples:
+  //   "USD"  - ISO 4217 code for United States dollar.
+  //   "X-BTC" - Potential API-defined extension for Bitcoin.
+  //   "X-RBX" - Potential API-defined extension for the virtual currency Robux.
+  string currency_code = 1;
+
+  // The quantity of currency.
+  Decimal quantity = 2;
+}

common-components/schemas/type/money.md

@@ -0,0 +1,35 @@
+# Money
+
+The `Money` type represents an amount of money in a specified currency.
+
+## Schema
+
+A `Money` has two fields:
+
+- The `currency_code` field is a string containing a currency code.
+
+  The three-letter currency codes defined in the ISO 4217 standard are always
+  supported.
+
+  APIs may define additional currency codes that are not included in ISO 4217
+  (for example, virtual currencies or cryptocurrencies). These must start with
+  with "X-", in order to distinguish them from potential future ISO 4217 codes.
+
+  Examples:
+
+  - "USD" - ISO 4217 code for United States dollar
+  - "X-BTC" - Potential API-defined extension for Bitcoin.
+  - "X-.RBX" - Potential API-defined extension for the virtual currency Robux
+
+- The `quantity` field is a field of type [`Decimal`][], representing the
+  quantity of currency.
+
+## Examples
+
+- Five US dollars === `{currency_code: "USD", quantity: {significand: 5}}`
+- One and a half Bitcoin ===
+  `{currency_code: "X-BTC", quantity: {significand: 15, exponent: -1}}`
+
+<!--prettier-ignore-start-->
+[`Decimal`]: ./decimal.md
+<!--prettier-ignore-end-->