diff --git a/common-components/json_schema/money.yaml b/common-components/json_schema/money.yaml new file mode 100644 index 00000000..b49bf425 --- /dev/null +++ b/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 diff --git a/common-components/proto/aip/type/money.proto b/common-components/proto/aip/type/money.proto new file mode 100644 index 00000000..885489db --- /dev/null +++ b/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; +} diff --git a/common-components/schemas/type/money.md b/common-components/schemas/type/money.md new file mode 100644 index 00000000..44b736f9 --- /dev/null +++ b/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}}` + + +[`Decimal`]: ./decimal.md +