<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40"><head><meta http-equiv=Content-Type content="text/html; charset=utf-8"><meta name=Generator content="Microsoft Word 15 (filtered medium)"><style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Aptos;
panose-1:2 11 0 4 2 2 2 2 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0cm;
font-size:12.0pt;
font-family:"Aptos",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
span.EmailStyle19
{mso-style-type:personal-reply;
font-family:"Aptos",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;
mso-ligatures:none;}
@page WordSection1
{size:612.0pt 792.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
--></style></head><body lang=EN-GB link=blue vlink=purple style='word-wrap:break-word'><div class=WordSection1><p class=MsoNormal><span style='font-size:11.0pt;mso-fareast-language:EN-US'>I had had a similarish idea a while back <a href="https://github.com/ivoa-std/DataLink/issues/53">https://github.com/ivoa-std/DataLink/issues/53</a> - I feel that an openAPI description would be way too low level for this description, however. You will see that I even made the heretical suggestion that perhaps the service description did not need to be embedded within VOTable – that removes a lot of problems…<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;mso-fareast-language:EN-US'><o:p> </o:p></span></p><div id=mail-editor-reference-message-container><div><div><p class=MsoNormal style='margin-left:36.0pt'>On 31/05/2024, 18:54, "p3t" <p3t-bounces@ivoa.net> wrote:<o:p></o:p></p></div><p class=MsoNormal style='margin-left:36.0pt'><span style='font-size:11.0pt'><o:p> </o:p></span></p><div><p class=MsoNormal style='margin-left:36.0pt'><span style='font-size:11.0pt'>Russ Allbery via p3t <p3t@ivoa.net> writes:<br><br>> This does not (at all) solve the problem of how to then embed these<br>> things in VOTables, since OpenAPI does not (so far as I know) have an<br>> XML representation for a schema. I think only JSON and YAML are<br>> defined. So that's another obvious drawback that I'm not sure how to<br>> approach.<br><br>I went for a walk and thought about this some more, and I think I have an<br>idea. This will at least make it obvious what sort of complexity would be<br>involved in going this route.<br><br>Currently service descriptors define two separate things: a simple schema<br>or standard protocol reference for an associated service, and a set of<br>instructions for how to set parameters to that service from either static<br>values or columns in the VOTable.<br><br>I have no desire to specify an XML serialization of an OpenAPI schema.<br>That doesn't sound like a good time. But what if we separated those two<br>things? A service descriptor would then be a link to a schema<br>(specifically, in the OpenAPI context, to an operation specified by that<br>schema), and a set of instructions for how to set input values. Those<br>instructions would be an identifier for the input parameter, which would<br>be a string whose meaning is determined by the type of schema, and the<br>value, which similar to today would either be a static value or a<br>reference to a column in the associated VOTable.<br><br>We would continue to define an XML serialization of this service<br>descriptor, as well as a JSON serialization (and any future protocol<br>serialization). The JSON version of a service descriptor would look<br>something like this:<br><br> {<br> "schema": {<br> "type": "openapi",<br> "url": "https://urldefense.com/v3/__https://example.com/service/openapi.json*/__;Iw!!PDiH4ENfjr2_Jw!GOfLj4fKgYpG37s2WU2gWq0g1PobVXoGBwr1uwVMPYm3D9X5i6ZgUOn473wMPKiWLHkJP36iHMEqPGfGIQ4$ [example[.]com]<json-pointer>"<br> },<br> "inputParams": [<br> {<br> "parameter": "<json-pointer>",<br> "value": "static-value"<br> },<br> {<br> "body": "<json-pointer? json-path? see below>",<br> "ref": "primaryID"<br> }<br> ]<br> }<br> <br>(This is very incomplete; more fields would be needed.)<br><br>The end of the URL is a JSON-Pointer to the operation in the schema. This<br>means that in the case of web services that publish their own OpenAPI<br>schemas, the service descriptor can just point to the OpenAPI schema<br>published by the service with the appropriate JSON-Pointer to reference<br>the specific intended operation. (An "operation" is basically a path plus<br>an HTTP verb.)<br><br>Input parameters then reference either an OpenAPI parameter or a field in<br>the body of the request. Referencing parameters is easy, since they're<br>right there in the schema so this can just be another JSON-Pointer<br>relative to the operation. The body is a bit harder, since (to support<br>content negotiation) it's defined in the OpenAPI schema as a content type<br>mapped to a schema, and then the schema defines the nested structure. I'm<br>not sure if we want a JSON-Pointer to the schema definition or (for JSON<br>network serializations) a JSON path within the body.<br><br>Advantages:<br><br>1. We're leaning into OpenAPI already, at least for now, and we can tag<br> the type of schema to give us the flexibility to use other types of<br> schemas in the future (asyncAPI or whatever).<br><br>2. Being able to point directly to the OpenAPI schema provided by the<br> service is a nice reduction in duplicated information. Right now, our<br> DataLink services have to first write the service, which creates an<br> OpenAPI schema, and then separately also define the same information in<br> a DataLink snippet, which is annoying and involves two sources of data<br> that can get out of sync.<br><br>3. This gives us the ability to handle any HTTP verb and any format that<br> can be defined by OpenAPI, or any similar specification standard we<br> adopt in the future. This is way more power than the current service<br> descriptor syntax has.<br><br>Disadvantages:<br><br>1. Parsing the semantics of an entire OpenAPI schema is way work than<br> clients are going to want to do. I think we would need to be able to<br> define a really narrow subset of information in the schema that clients<br> would need to look at and allow clients to ignore everything else, and<br> we're still paying some complexity cost because there probably aren't<br> great OpenAPI schema client libraries for doing this sort of operation.<br> And we do want the client to parse the schema in order to get things<br> like a list of allowable values, minimum and maximum values, etc. Most<br> of the JSON Schema libraries I'm aware of are focused on validation of<br> input data, not in parsing the schema for semantic information that one<br> might want to use to, for instance, build an HTML form.<br><br>2. Related, even finding the schema is going to be complicated,<br> particularly for a request body. I'm not sure if a pointer into the<br> schema is the right approach, because the schema can be a reference to<br> a different part of the OpenAPI schema, which in turn can reference<br> other parts of the OpenAPI schema.<br><br>2. I'm not sure how good the library support for JSON-Pointers is. It<br> does look like there are a few good Python libraries out there.<br><br>4. If we want the specification of the service to continue to contain IVOA<br> type information (and I think we do), we will need to define an OpenAPI<br> extension that carries that information. I suspect we'll want to do<br> that anyway, because I suspect we'll want to add IVOA type information<br> to all of our schemas, but I'm not sure how hard that's going to be.<br><br>-- <br>Russ Allbery (eagle@eyrie.org) <https://urldefense.com/v3/__https://www.eyrie.org/*eagle/__;fg!!PDiH4ENfjr2_Jw!GOfLj4fKgYpG37s2WU2gWq0g1PobVXoGBwr1uwVMPYm3D9X5i6ZgUOn473wMPKiWLHkJP36iHMEqJDz6o3k$ [eyrie[.]org]><br>-- <br>p3t mailing list<br>p3t@ivoa.net<br><a href="https://urldefense.com/v3/__http:/mail.ivoa.net/mailman/listinfo/p3t__;!!PDiH4ENfjr2_Jw!GOfLj4fKgYpG37s2WU2gWq0g1PobVXoGBwr1uwVMPYm3D9X5i6ZgUOn473wMPKiWLHkJP36iHMEqPB9p7Rk$">https://urldefense.com/v3/__http://mail.ivoa.net/mailman/listinfo/p3t__;!!PDiH4ENfjr2_Jw!GOfLj4fKgYpG37s2WU2gWq0g1PobVXoGBwr1uwVMPYm3D9X5i6ZgUOn473wMPKiWLHkJP36iHMEqPB9p7Rk$</a> [mail[.]ivoa[.]net]<o:p></o:p></span></p></div></div></div></div></body></html>