]> Microsoft Corporation

clemensv@microsoft.com

Web and Internet Transport Building Blocks for HTTP APIs Internet-Draft This document specifies "JSON Structure Symbols, Scientific Units, and Currencies", an extension to JSON Structure Core. This specification defines a set of annotation keywords for associating scientific unit and currency metadata and constraints, primarily for use with numeric values. JSON Structure Scientific Units provides a mechanism for schema authors to explicitly declare the unit associated with numeric data, thereby enabling precise mapping between schema representations and external data systems. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction This document is a companion specification to JSON Structure Core . It defines annotation keywords that allow numeric types to be enriched with measurement unit or currency information. The primary purpose of this extension is to help numeric values be interpreted consistently by specifying their associated scientific units or currencies. This specification defines the syntax and semantics of the keywords that annotate numeric types with scientific unit or currency information. Implementations of JSON Structure Core that support this extension MUST process these keywords according to the rules defined herein.

Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Symbol Annotations This section defines the keywords used to annotate schema elements with symbols that accompany values when presented to users.

The symbol Keyword The symbol keyword provides a mechanism for annotating a schema element with a symbol that annotates the value of the element when presented to users. The keyword MAY appear alongside the type keyword in object properties or array items or map values.

• The value of symbol MUST be a JSON string.
• The string value of symbol SHOULD contain a Unicode character or a multi-character symbol that represents the value of the annotated element.
• The symbol keyword MAY be used as an annotation on any schema element.
• symbol MAY be used in conjunction with unit or currency annotations or independently.

Example: or or

The symbols Keyword The symbols keyword provides a mechanism for annotating a schema element with a set of symbols that annotate the value of the element when presented to users. The keyword MAY appear alongside the type keyword in object properties or array items or map values.

• The value of symbols MUST be a map.
• The keys of the symbols map MUST be strings that represent a purpose indicator. The lang: prefix is reserved for language-specific symbols. The suffix after the colon specifies the language code. The language code MUST conform to the standard.
• The values of the symbols map MUST be strings that represent the symbol.
• The symbols keyword MAY be used as an annotation on any schema element.

Example:

Scientific Unit Annotations This section defines the keywords used to annotate numeric types with scientific unit information.

The unit Keyword The unit keyword provides a mechanism for annotating a numeric schema (or a schema based on a numeric extended type such as number, int32, uint32, int64, uint64, int128, uint128, float, double, or decimal) with its measurement unit. The keyword MAY appear alongside the type keyword in object properties or array items or map values.

• The value of unit MUST be a JSON string.
• The string value of unit SHOULD contain:
  • An SI unit symbol or derived unit symbol conforming to the Bureau International des Poids et Mesures (BIPM) International System of Units (SI)
  • A unit symbol defined in ISO/IEC 80000 series
  • A non-SI unit symbol defined in NIST Handbook 44 Appendix C

For "derived" SI units that reflect a multiplication, the unit symbols MUST be separated by the asterisk character (*). For derived units that reflect a division, the unit symbols MUST be separated by the forward slash (/). The notation for exponentiation MUST be indicated using the caret (^). For example, acceleration SHALL be denoted as "m/s^2". Units that use Greek-language symbols (including supplementary or derived units) such as Ohm ("Ω") MUST be denoted with those Greek symbols (using the corresponding Unicode code points). The unit keyword MAY be used as an annotation on any schema element whose underlying type is numeric. Schema processors that support JSON Structure Scientific Units MUST use the value of the unit keyword to interpret, convert, or display numeric values appropriately. Example:

Unit Annotations This is a list of common scientific units that MAY be used with the unit. Units are defined according to ISO/IEC 80000, BIPM SI, and NIST HB44:

Measure	unit	Description	Reference
Length	m	Meters, SI unit of length
Velocity	m/s	Meters per second
Acceleration	m/s^2	Meters per second squared
Weight	kg	Kilograms, SI unit of mass
Time	s	Seconds, SI unit of time
Temperature	K	Kelvin, SI unit of temperature
Volume	L	Liters, non-SI unit accepted in SI
Pressure	psi	Pounds per square inch, non-SI unit
Energy	J	Joules, SI unit of energy
Power	W	Watts, SI unit of power
Electrical Resistance	Ω	Ohms, SI unit of electrical resistance
Electrical Current	A	Amperes, SI unit of electric current
Light Intensity	cd	Candelas, SI unit of luminous intensity
Area	m^2	Square meters, SI unit of area
Volume	m^3	Cubic meters, SI unit of volume
Length	ft	Feet, non-SI unit
Volume	gal	Gallon, non-SI unit
Pressure	bar	Bar, non-SI unit
Digital Storage	B	Bytes, non-SI unit
Data Rate	bit/s	Bits per second

Unit Prefixes The following SI prefixes MAY be used with base units:

Prefix	Symbol	Factor
yotta	Y	10²⁴
zetta	Z	10²¹
exa	E	10¹⁸
peta	P	10¹⁵
tera	T	10¹²
giga	G	10⁹
mega	M	10⁶
kilo	k	10³
milli	m	10⁻³
micro	μ	10⁻⁶
nano	n	10⁻⁹
pico	p	10⁻¹²
hecto	h	10²

Examples:

• "km": Kilometers
• "mm": Millimeters
• "μm": Micrometers
• "nm": Nanometers
• "ps": Picoseconds
• "mΩ": Milliohms
• "kΩ": Kilohms
• "MW": Megawatts

Currency Annotations This section defines the keywords used to annotate numeric types with currency information.

The currency Keyword The currency keyword provides a mechanism for annotating a numeric schema (or a schema based on a numeric extended type such as number, int32, uint32, int64, uint64, int128, uint128, float, double, or decimal) with a currency annotation. The keyword MAY appear alongside the type keyword in object properties or array items or map values.

• The value of currency MUST be a JSON string.
• The string value of currency SHOULD contain a three-letter currency code conforming to the standard.
• The currency keyword MAY be used as an annotation on any schema element.

Example:

Enabling the Annotations These annotations can be enabled in a schema or meta-schema by adding the JSONSchemaUnits key to the $uses clause when referencing the extended meta-schema: The annotations are enabled by default in the validation meta-schema:

Security and Interoperability Considerations Alternate unit annotations do not affect the fundamental validation of instance data. They are purely metadata and MUST be ignored by validators that do not support this extension. Applications that rely on unit annotations for conversion or display MUST implement appropriate validation against recognized standards (BIPM SI and NIST HB44) to ensure consistency.

IANA Considerations This document has no IANA actions.

Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document describes the structure, content, construction, and semantics of language tags for use in cases where it is desirable to indicate the language used in an information object. It also describes how to register values for use in language tags and the creation of user-defined extensions for private interchange. This document, in combination with RFC 4647, replaces RFC 3066, which replaced RFC 1766. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Institute of Electrical and Electronics Engineers Physical Measurement Laboratory National Institute of Standards and Technology International Electrotechnical Commission International Electrotechnical Commission International Electrotechnical Commission International Electrotechnical Commission International Organization for Standardization n.d.

Changes from draft-vasters-json-structure-units-00

• Fixed typo in document abbreviation.

Acknowledgments TODO acknowledge.