[p3t] Draft documents demonstrating standards layout

[Russ Allbery]

Dave Morris <dave.morris at metagrid.co.uk> writes:

> We don't need to do anything special to describe the schema in the
> OpenAPI specification.

There are a few places where I think OpenAPI may fall short, but I may be
missing some facility in OpenAPI for dealing with them:

* OpenAPI specifies int32 and int64 integer formats, but not unsigned
  variations of them, so I think we may have to extend it to specify an
  unsigned 64-bit integer.  I'm also not sure if we need to encode 64-bit
  integers as strings for JSON.  RFC 8259 does not have a data type for
  integer, only number, and defines number as those numbers representable
  in a IEEE binary64 (sort of), which cannot represent the entire 64-bit
  integer range.  I am seeing at least some indications that one has to
  encode 64-bit integers as strings for interoperability.  For example:
  https://stackoverflow.com/questions/209869/

* There is an expired Internet-Draft that defines the date-time and
  duration string format using ISO 8601 (which is not my favorite duration
  format, but may still be a reasonable choice), and I *think* the OpenAPI
  specification intends to incorporate that by reference, but I wish it
  were a bit clearer.  Note that this only gives us UTC for timestamps; if
  we want a TAI timestamp, we'll need to define our own data type for
  that.  (I'm always worried about standards that point to expired
  Internet-Drafts.  If folks are going to use it, pushing it through to
  publication or publishing it under the aegis of some other standards
  body seems like it would be a good idea.)

* OpenAPI is somewhat annoyingly ambiguous about real numbers, defining
  "float" and "double" self-referentially.  I think we can assume that the
  range and precision of these values are those of binary32 and binary64
  IEEE floating point numbers, respectively, but we should say that
  explicitly somewhere.  I don't know if we need 128-bit floating point
  numbers for anything.  Hopefully we don't need to deal with 80-bit
  extended precision floating point numbers.

* It looks like we need to say explicitly somewhere that our strings are
  Unicode.  The OpenAPI spec does not appear to do this (maybe I missed
  something?), and RFC 8259 explicitly allows non-Unicode strings.  We may
  also need to define string equality (whether we're doing
  Unicode-normalized comparisons or not).

My larger concern is that I am dubious that OpenAPI will prove to be
resilient against future changes to prevailing protocols and definition
languages any more than XML schemas were.  gRPC does not use OpenAPI, for
example; it uses protobuf as its API definition language.  I fear that
OpenAPI is a specification language for this one particular moment in
time, and in the future people will use something else, similar to how XML
schemas used to be common and now, although they still exist, they're less
widely used.

That said, designing a specification language is an immense amount of
work, and I don't want us to write our own either.  We should use OpenAPI
today because that's what people use today.  But I would like to have some
sort of semantic language specific to the IVOA, ideally one with a minimum
amount of additional formality so that it's easy to read and easy to
write, that nails down all the things that OpenAPI may leave ambiguous and
provides enough additional information that we can adapt our data types to
some new language that comes along later.

-- 
Russ Allbery (eagle at eyrie.org)             <https://www.eyrie.org/~eagle/>