Units for json schemas

[schwehr]

Is it possible to add an optional units to the schemas? For scientific data, that can be critical information to declare for a field and the schema seems a reasonable place to state the expectation for the value.

Doesn't have to be more than the string. e.g. Some languages bring conversion infrastructure along, which seems out of scope.

Related, but a lot of these are beyond scope of a schema:

• https://en.wikipedia.org/wiki/International_System_of_Units
• https://www.unidata.ucar.edu/software/udunits/
• https://en.cppreference.com/w/cpp/language/user_literal
• https://www.boost.org/doc/libs/1_47_0/doc/html/boost_units/Examples.html
• https://pypi.org/project/siunits/
• https://docs.scipy.org/doc/scipy/reference/constants.html#units

[karenetheridge]

Anything is possible. Are you picturing a keyword that does validation in some way, or is purely annotative?

[schwehr]

At the schema level, I am only thinking annotative. I think it's up to an application to decide how to use the unit annotation should it exist. The most common case is likely with annotating visualizations of data with the units. Perhaps the user could turn to something like udunits to do a conversion. Unit conversion and range checking are two heavy weight tasks that don't seem to be reasonable within the spec of the schema.

At the edge of reasonable would be to give a list of accepted strings. But that could be large and likely users in diverse fields will have units that are not in the list. e.g. scipy units doesn't have magnetic units found at IEEE Magnetics

This is from our custom schema type that will hopefully become json-schema based. The user's code could check the schema on a collection type and at halt with an error if speed isn't what it expects. e.g. If a program only handles m/s, but it finds knots.

      "max_wind_kts": {
        "description": "Maximum wind speed",
        "type": "DOUBLE",
        "unit": "knots"
      },
      "min_pressure": {
        "description": "Minimum pressure",
        "type": "DOUBLE",
        "unit": "millibars"
      },
      "numEntries": {
        "description": "Number of points for a particular hurricane",
        "type": "DOUBLE"
      },
      "radii_ne_34kt": {
        "description": "34 kt wind radii maximum extent in northeastern quadrant",
        "type": "DOUBLE",
        "unit": "nautical miles"
      },

[handrews]

@schwehr This would make for an excellent extension vocabulary, now that those are supported :-) It's a common problem, as you note, but probably not quite fundamental enough to go into the main spec.

Also, if you want types like DOUBLE you're going to need a new keyword for that as well. The type keyword is not extensible, and given how heavily used it is and how stable it has ben for many years, the bar for changing it is very high.

[gregsdennis]

I think number is what you're looking for instead of DOUBLE. Though if you're looking to declare precision, perhaps a precision keyword would be better suited.

{
  "type": "number",
  "precision": "double"
}

This would also live in your extension vocab.

[Ark-kun]

Don't type and format provide enough flexibility for specifying the units?

A bit of a tangent, by JsonSchema's naming of type and format seems counter-intuitive to me. They'd be less confusing if they were reversed.

There are millions of types in the world. Yet the number of [serialization] formats is smaller. And if we talk about JSON, there are only a handful of ways something can be represented in JSON: string, number, boolean, array, object.

I think it would have been more intuitive to reverse the naming:

{
    "type": "Nautical miles",
    "format": "number"
}

{
    "type": "Positive integer",
    "format": "number"
}

{
    "type": "E-mail address",
    "format": "string"
}

{
    "type": "JPEG image",
    "format": "blob"
}

[handrews]

@Ark-kun type correlates to the JavaScript (the JS in JSON) notion of types. format has never been implemented consistently across implementations and should be replaced by coherent vocabularies of keywords.

[handrews]

I'm going to move this over to the vocabularies repo.

[silverwind]

Being able to define a unit for time periods would be very useful:

uptime:
  type: integer
  unit: microseconds
  example: 50

Some possibly useful spec text here.

[sm-Fifteen]

Like I said in OAI/OpenAPI-Specification#2061 (comment), Unicode CLDR and ECMAScript Intl both define the same composable string format as well as a set of base units and prefixes to allow some form of "universal" unit specification like this. Both only do so with the main use case of text internationalisation and display unit conversion, but co-opting this into a JSON Schema vocabulary would be enough to cover the vast majority of use cases around data structure documentation as well.

As for unusual/domain-specific units like decibel-milliwatts or tons of TNT or parts-per-octet "percentages" and whatnot, the CLDR notation allows for private-use units starting with xxx- (formerly x-), allowing users to also define custom units where the stock ones aren't sufficent.

[gregsdennis]

This is still an annotative-only concept. We have some ideas cooking that may help in defining annotative keywords, but it's on hold until we sort out a few other things.

As it stands, there's nothing preventing someone from just creating (and publishing) a new vocabulary that defines the units keyword, its valid values, and its intended use. The JSON Schema framework is already in place to support such a vocabulary.

It's good to see there's continued interest in this, though.

[karenetheridge]

As it stands, there's nothing preventing someone from just creating (and publishing) a new vocabulary that defines the units keyword, its valid values, and its intended use. The JSON Schema framework is already in place to support such a vocabulary.

It's not even necessary to do that much, for a purely-annotative keyword, because the latest version of JSON Schema specifies that unknown keywords should be collected as annotations by default. If you're using json schemas in the context of OpenAPI 3.1.x, you may need to define a custom metaschema that allows for unknown keywords, however, but this is a simple matter of creating the data file, and no extra code is needed (nor additional support in implementations, as long as they are specification-conformant).

[silverwind]

More standardization would be nice tought, so that for example a UI can render 9124 seconds as 2 hours, 31 minutes. Deep integration like that can only happen with some standardization across implementations.