refactor(schemas): house cleaning

json_schema/decimal.yaml

@@ -1,5 +1,5 @@
 $schema: https://json-schema.org/draft/2020-12/schema
-$id: https://example.com/product.schema.json
+$id: https://aep.dev/json_schema/decimal
 title: Decimal
 description: |
   Represents a decimal number in a form similar to scientific notation.
@@ -10,12 +10,11 @@ description: |
   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),
+  Note that the range of a Decimal exceeds that of a JSON `number` (double),
   as well as that of a `decimal64`.
 type: object
 required:
-- significand
-- exponent
+  - significand
 additionalProperties: false
 properties:
   significand:
@@ -37,3 +36,16 @@ properties:
       the decmial point.
     type: integer
     format: int32
+examples:
+  - 'value_equals_17':
+      significand: 17
+      exponent: 0
+  - 'value_equals_-0.005':
+      significand: -5
+      exponent: -3
+  - 'value_equals_33.5_million':
+      significand: 335
+      exponent: 5
+  - 'value_equals_11/8(1.375)':
+      significand: 1375
+      exponent: -3

json_schema/money.yaml

@@ -1,5 +1,5 @@
 $schema: https://json-schema.org/draft/2020-12/schema
-$id: https://example.com/product.schema.json
+$id: https://aep.dev/json_schema/money
 title: Money
 description: |
   Represents an amount of money with its currency type.
@@ -11,8 +11,8 @@ description: |
     `{"currency_code": "X-BTC", "quantity": {"significand": 15, "exponent": -1}}`
 type: object
 required:
-- currency_code
-- quantity
+  - currency_code
+  - quantity
 additionalProperties: false
 properties:
   currency_code:
@@ -33,4 +33,14 @@ properties:
     type: string
   quantity:
     description: The quantity of currency.
-    $ref: decimal.yaml#/definitions/Decimal
+    $ref: /json_schema/decimal#
+examples:
+  - 'value_equals_$5_USD':
+      currency_code: 'USD'
+      quantity:
+        significand: 5
+  - 'value_equals_1.5 Bitcoin':
+      currency_code: 'X-BTC'
+      quantity:
+        significand: 15
+        exponent: -1

json_schema/phone_number.yaml

@@ -0,0 +1,76 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://aep.dev/json_schema/phone_number
+title: 'Phone Number'
+description: |
+  represents a phone number in a way suitable as an API wire format
+  - should not be used for locale-specific formatting of a phone number, such as
+    "+1 (650) 253-0000 ext. 123"
+  - is not designed for efficient storage
+  - may not be suitable for dialing - specialized libraries (see references)
+    should be used to parse the number for that purpose
+
+  To do something meaningful with this number, such as format it for various
+  use-cases, you will need a library like
+  https://github.com/google/libphonenumber
+oneOf:
+  - type: object
+    required:
+      - short_code
+    additionalProperties: false
+    properties:
+      short_code:
+        description: |
+          This must be exactly one of:
+          - Two alphabetical characters (such as "US"); OR
+          - Three numeric digits (such as "419")
+        type: object
+        additionalProperties: false
+        required:
+          - region_code
+          - number
+        properties:
+          region_code:
+            description: |
+              A string representing a BCP-47 region code.
+            type: string
+            pattern: '^[A-Z]{2}$'
+          number:
+            type: string
+            pattern: '^[0-9]{3}$'
+  - type: object
+    required:
+      - number
+    additionalProperties: false
+    properties:
+      number:
+        description: |
+          A string representing an [E164][] number. 
+          This property is formatted as a leading plus sign (`+`), followed by a phone
+          number that uses a relaxed ITU E.164 format consisting of the country calling
+          code (1 to 3 digits) and the subscriber number, with no additional spaces or
+          formatting
+          The ITU E.164 format limits the latter to 12 digits, but in practice not all
+          countries respect that, so we relax that restriction here. National-only
+          numbers are not allowed.
+        type: string
+        pattern: '^[+][0-9]+'
+        minLength: 7
+        maxLength: 17
+      extension:
+        description: |
+          **must not** include a leading "x" that services simply to
+          indicate that the value is a phone number extension; this is implicit in the
+          property itself.
+        type: string
+        pattern: '^(?!x)[0-9#,pw]+'
+        maximum: 40
+examples:
+  short_code_with_region_code:
+    short_code:
+      region_code: 'US'
+      number": '911'
+  number_only:
+    number: '+15552220123'
+  number_with_extension:
+    number: '+15552220123'
+    extension: '123,,,456'

schemas/type/decimal.md

@@ -8,28 +8,28 @@ point representation in order to avoid precision errors.
 A `Decimal` represents a decimal number in a form similar to scientific
 notation.
 
-It has two fields:
+It has two properties:
 
-- The `significand` field is a 64-bit integer representing the significant
+- The `significand` property 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
+- The `exponent` property is a 32-bit integer representing the position of the
+  deicmal point within the value of the `significand` property; 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
+  When the exponent is greater than `0`, the value represents the number of trailing zeroes
   after the significant digits.
 
-  When the exponent is less than 0, represents how many of the significant
+  When the exponent is less than `0`, the value represents how many 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 `^`
+`significant * 10^exponent`, where `*` represents multiplication and `^`
 represents exponentiation.
 
-Note: The range of a Decmial exceeds that of a JSON `number` (double), as well
+Note: The range of a `Decimal` exceeds that of a JSON `number` (double), as well
 as that of a `decimal64`.
 
 ## Examples

schemas/type/money.md

@@ -4,9 +4,9 @@ The `Money` type represents an amount of money in a specified currency.
 
 ## Schema
 
-A `Money` has two fields:
+A `Money` has two properties:
 
-- The `currency_code` field is a string containing a currency code.
+- The `currency_code` property is a string containing a currency code.
 
   The three-letter currency codes defined in the ISO 4217 standard are always
   supported.
@@ -21,7 +21,7 @@ A `Money` has two fields:
   - "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
+- The `quantity` property is of type [`Decimal`][], representing the
   quantity of currency.
 
 ## Examples

schemas/type/phone_number.md

@@ -33,12 +33,12 @@ if (!wireProto.getExtension().isEmpty()) {
 
 ### `PhoneNumber`
 
-A `PhoneNumber` has two main fields, exactly one of which must be populated:
+A `PhoneNumber` has two main properties, exactly one of which must be populated:
 
-- A `ShortCode` field named `short_code` (see below for details on `ShortCode`).
-- A string field named `number`, representing an [E164][] number.
+- A `ShortCode` property named `short_code` (see below for details on `ShortCode`).
+- A string property named `number`, representing an [E164][] number.
 
-  This field is formatted as a leading plus sign (`+`), followed by a phone
+  This property is formatted as a leading plus sign (`+`), followed by a phone
   number that uses a relaxed ITU E.164 format consisting of the country calling
   code (1 to 3 digits) and the subscriber number, with no additional spaces or
   formatting, e.g.:
@@ -50,14 +50,14 @@ A `PhoneNumber` has two main fields, exactly one of which must be populated:
   countries respect that, so we relax that restriction here. National-only
   numbers are not allowed.
 
-A `PhoneNumber` also has a string `extension` field, which is optional. An
+A `PhoneNumber` also has a string `extension` property, which is optional. An
 `extension` can be no longer than 40 characters. Typically, this is a series of
-numberical digits, but it may also include dialing characters such as `#`, `,`,
+numerical digits, but it may also include dialing characters such as `#`, `,`,
 `p`, and `w`.
 
 An `extension` **must not** include a leading "x" that services simply to
 indicate that the value is a phone number extension; this is implicit in the
-field itself.
+property itself.
 
 ### `ShortCode`
 
@@ -71,19 +71,19 @@ which means the same short code can exist in different regions, with different
 usage and pricing, even if those regions share the same country calling code
 (e.g. US and CA).
 
-A `ShortCode` has two fields, both of which are required:
+A `ShortCode` has two properties, both of which are required:
 
-- A string field named `region_code`, representing a BCP-47 region code. This
+- A string property named `region_code`, representing a BCP-47 region code. This
   must be exactly one of:
   - Two alphabetical characters (such as "US"); OR
   - Three numeric digits (such as "419").
-- A string field named `number`, comprising only numeric digits and representing
+- A string property named `number`, comprising only numeric digits and representing
   the actual number (such as "611").
 
 ## Examples
 
 - `{short_code: {region_code: "US", number: "911"}}`
 - `{number: "+15552220123"}`
-- `{number: "+15552220123", extension: "123,,456"}`
+- `{number: "+15552220123", extension: "123,,,456"}`
 
 [E164]: https://en.wikipedia.org/wiki/E.164