Clarify/improve documentation of the unit property
25 views
Skip to first unread message
Simon Speich
Jun 21, 2023, 7:26:08 AM6/21/23
to json-stat
Currently, the unit property is documented with an example as:
... It takes the form of an object where category ID is the key and the value is an object.
"concept": {
"category": {
"label": {
"pop": "population"
},
"unit": {
"pop": { … }
}
}
}
Four properties of this object are currently closed: decimals, label, symbol and position.
"unit": {
"exp": {
"decimals": 1,
"label": "millions",
"symbol": "$",
"position": "start"
}
}
Following the previous example, a client could display a value of 10 of metric exp as “$10.0 millions”.
If think the example is confusing because in one case the category id "pop" is used and in the other one "exp" is used as the key. Also the multiplier property is missing:
"unit": {
"pop": {
"decimals": 1,
"multiplier": 6,
"label": "millions",
"symbol": "$",
"position": "start"
}
}
Xavier Badosa
Jun 25, 2023, 1:17:38 PM6/25/23
to json-stat
Hi Simon,
You are absolutely right: the spec used two completely different examples in the "unit" section. I changed it to always refer to "exp" (exports).
The example focuses on the "closed" properties: that's why "multiplier" is not present.
It's a pity that the "unit" section is so "open". The problem comes from the first release of JSON-stat where this section was just a discussion section (it dealt with properties that could be useful to consider to describe the unit), and unfortunately has partially remained so. In the first release of JSON-stat, "extension" didn't exist, so it wasn't possible to leave these "suggestions" to an extension. As a consequence, some early JSON-stat adopters have been using some of the suggestions of the first release (for example, "base") that haven't ended up in JSON-stat v.2.0 as a "closed" property: the reason why they weren't removed from the spec altogether is because they appeared as a suggestion in the first release and they already had adopters.
If I had to re-write from scratch the spec, it would only mention decimals, label, symbol and position and would suggest the possibility of enriching the metric information with an extension.
X.
Simon Speich
Jun 26, 2023, 3:47:01 PM6/26/23
to json-stat
Hi Xavier
Thanks for the explanation and changes.
Kind regards, Simon
Simon Speich
Dec 21, 2023, 5:31:57 AM12/21/23
to json-stat
I think it would be useful to have a full, real-world example for the recommended use of the unit including parent label (which should not repeat the unit label):
"label": {
"exp": "exports"
},
"unit": {
"exp": {
"label": "million",
"decimals": 1,
"symbol" : "m³",
"position" : "end"
}
"extension": {
"multiplier": 6,
"base" "m",
}
}
full label example --> "exports 6,1 million m³"
Note: Not sure about the placement of the different parts. Position refers to the symbol, but what about the positioning of the unit label property?
On Sunday, June 25, 2023 at 7:17:38 PM UTC+2 xba...@gmail.com wrote:
Xavier Badosa
Dec 28, 2023, 6:03:43 AM12/28/23
to json-stat
> I think it would be useful to have a full, real-world example for the recommended use of the unit including parent label (which should not repeat the unit label)
I think such an example already exist in the sample library: https://json-stat.org/samples/canada.json (this is actually the canonical JSON-stat example). It probably could be referred to in the full spec.
An export/import example could look like:
"dimension": {
"concept": {
"label": "concepts",
"category": {
"index": ["exp", "imp"],
"label": {
"exp": "exports",
"imp": "imports"
},
"unit": {
"exp": {
"decimals": 1,
"label": "M",
"symbol": "$",
"position": "start"
},
"imp": {
"decimals": 1,
"label": "M",
"symbol": "$",
"position": "start"
}
}
}
},
"year": {...},
"area": {...}
}
An export value of 10 should, according to the unit info, be expressed as: "$10.0 M".
The spec avoids dealing with "extension" because it's open by definition and can be used freely. At some point my idea was to document some usual "extension" practices. The agenda was that, if enough providers used some extensions in the same way, this practice could end up in the standard as regular properties ("extension" as a device to identify needed functionality).
In your example, I'm not sure if "base" should be "m", or "m3" or "m³".
The unit "label" is assumed to be a text that is always placed after the value.
Xavier
On Thursday, December 21, 2023 at 11:31:57 AM UTC+1 simon wrote:
I think it would be useful to have a full, real-world example for the recommended use of the unit including parent label (which should not repeat the unit label):"label": {"exp": "exports"},"unit": {"exp": {"label": "million","decimals": 1,"symbol" : "m³","position" : "end"}"extension": {"multiplier": 6,"base" "m",}}full label example --> "exports 6,1 million m³"Note: Not sure about the placement of the different parts. Position refers to the symbol, but what about the positioning of the unit label property?
On Sunday, June 25, 2023 at 7:17:38 PM UTC+2 xavier wrote:
Hi Simon,You are absolutely right: the spec used two completely different examples in the "unit" section. I changed it to always refer to "exp" (exports).The example focuses on the "closed" properties: that's why "multiplier" is not present.It's a pity that the "unit" section is so "open". The problem comes from the first release of JSON-stat where this section was just a discussion section (it dealt with properties that could be useful to consider to describe the unit), and unfortunately has partially remained so. In the first release of JSON-stat, "extension" didn't exist, so it wasn't possible to leave these "suggestions" to an extension. As a consequence, some early JSON-stat adopters have been using some of the suggestions of the first release (for example, "base") that haven't ended up in JSON-stat v.2.0 as a "closed" property: the reason why they weren't removed from the spec altogether is because they appeared as a suggestion in the first release and they already had adopters.If I had to re-write from scratch the spec, it would only mention decimals, label, symbol and position and would suggest the possibility of enriching the metric information with an extension.X.
Reply all
Reply to author
Forward
0 new messages