[p3t] Draft documents demonstrating standards layout

[Russ Allbery]

Hi all,

I have finished a very preliminary first draft of some documents that
hopefully demonstrate what I had in mind for how to organize standards
documents, and that also start fleshing out the specification for a JSON
protocol.

Some caveats:

The main point of these documents is to demonstrate a possible way of
structuring standards and offer an example of the level of detail that I
think documents should provide.  These documents therefore include a lot
of specific specification details.  Those details are very much up for
debate and I suspect many of them are incorrect.  At this stage I think
the exact content is less important than the structure and the "vibes."
My goal is to help create an intuitive feel for what a specification could
look like under this organization scheme.

I invented a new type system for these documents and did not attempt to
reconcile it with the existing IVOA type system.  This is only due to lack
of time, not because I don't think that should be done.  There are a few
new types that don't quite fit into the IVOA type model, but most if not
all of the primitive types here should be replaced with the standard IVOA
types.  The point was merely to demonstrate the pattern of the main
document defining a set of primitive types, the service document using
them, and the network protocol document describing an encoding for them.

This is very incomplete even relative to the deliverables I've been
working on.  Missing are the UWS specification and how to write a service
document that uses UWS, the OpenAPI schema, and multiple other things.
This is just a starting point to discuss.  I may be able to add some more
Monday morning before the meeting.

These documents are all published via our internal tech note system only
because that was fast and I didn't have to learn anything new and I wanted
to focus on getting content down to talk about.  All of this can be lifted
into the proper IVOA documentation system when we start hammering out
actual documents.

With those caveats in mind, here are the three documents I've started:

https://sqr-091.lsst.io/
    The framework document that lays out the standards structure, defines
    data types, provides data models that are shared between standards
    such as structured error messages, and says what the other documents
    should contain.  Please don't put any weight on the structured error
    specification here; it's just a half-baked iteration on the model from
    our previous discussion, included as a placeholder.

https://sqr-092.lsst.io/
    The JSON network protocol encoding.  This is where we get to the heart
    of the new work.  I tried to write the separation between this
    document and the other documents with both an HTTP XML and a gRPC
    specification in mind and put the things that would vary in this
    document.  It's also a starting point for a proper JSON serialization
    specification.

https://sqr-093.lsst.io/
    A web service specification for a very simple SODA-style cutout
    service.  This is not a great example service.  I picked this one just
    because I was already very familiar with it and could write it
    quickly, and because I'm currently working on that part of our service
    stack.

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