OpenAPI components for common DALI parameters

[pdowler]

These are small openapi components that can be included in another spec like TAP using the OpenAPI $ref mechanism.

Currently, this just describes the common query parameters in DALI. Even then, it includes only the ones that have a functional impact on current standards, so not: the old VERSION, unused REQUEST, and probably removable RUNID.

[pdowler]

see TAP PR #8 for how these are used to by another spec.

[jwfraustro]

pattern: might also be useful here to enforce some simple regex for the comma separation.

[pdowler]

OK, minimal pattern added (I did not try to handle the complexity of the location part of that param). The openapi linter I use thought it was OK, but swagger doesn't render anything so it's a little hard to verify and my regex-fu doesn't extend to ECMA-script so I hope those predefined character classes are standard.

[jwfraustro]

I did a quick check with regex101.com and it seems okay to me. \w covers [a-zA-Z0-9_], but not - as a character, if that's acceptable.

I agree with not tackling the location path.

[pdowler]

I think \w is roughly correct for valid table names... although it does not capture the fact that the name must start with an letter. I should fix that.

That regex101.com site is great - thnx for that pointer!

[pdowler]

I have also added very minimal reference from the document to the openapi component files, but have not tried to address the parts of the text that conflict: the case-insensitive parameter name bit.

That's one of the outstanding questions we have to discuss/decide (at the interop).

[pdowler]

converted to draft pending discussion of how to progress on case-insensitive -> OpenAPI-compliant

[pdowler]

The 3 openapi components needed for WD-TAP-1.2 are included and referenced in the file, but are not otherwise viewable/readable from the document. Those 3 files do need to end up included in the std package, uploaded to doc repo, and should end up being downloadable from stable URLs there...

For viewability: include the content in an appendix? these are small but in other standards I suspect this strategy won't be as viable..

It seems like the same kind of issue as standards with schema files... any ideas?

[molinaro-m]

For standards technical counterparts this is a long standing issue impacting the document repository.
IIRC there is some discussion ongoing with the potential new setup of that repository, in connection with the ivoatex upload solution that goes in the direction of a manifest for the content of the uploaded package.
Would it be worth to have a dedicated discussion in Goerlitz for this? (from what I know, we should have good coverage of interested people in person there)

For the openapi content: in P3T, again IIRC, there was the idea to have those documents alongside but separate, but we didn't end up with a proper solution or formatting for that. I wonder if an appendix section with a listing of the openapi files would be enough. Still, it leaves open the question raised above: where do they end up so that the URL links are stable and clear?

Simple (simplistic) solution might be ending up in the documents folder with, e.g.:

doc.pdf
doc.html
openapi/this.yaml
openapi/that.yaml

that currently will be done manually, but I suspect ivoatex can package quickly using AUX_FILES.

Another question, related, is: since there are already openapi cross-references, should the document repository also aggregate openapi yaml(s) from the different standards under one unique (let's say) ivoa.net/openapi folder, so that relative referencing can actually work?
(sorry, it might be a silly question)

[pdowler]

I experimented with cross-referencing quite bit since TAP is made from VOSI, UWS, DALI, and itself (TAP); this does not include very careful thought about external formats (eg VOTable) yet. There are essentially two options to ref:

1. use a fully qualified URL
2. use a relative path

I envision that RECs would be written to use full URLs like https://ivoa.net/std/DALI/openapi/dali-maxrec.yaml, but that's painful at the WD and PR stages. I think it isn't too hard to materialise (build) from top-level openapi.yaml by navigating, downloading all refs, and rewriting all external URLs to just the openapi/dali-maxrec.yaml bit... I would want to do that to embed API docs in my service, for example, and decouple from ivoa.net. I think that kinds of build process would need to also support referring to draft versions of components, somehow.

There is some complexity just to do the above that would inform how to store them on ivoa.net, and I haven't even thought about versioning at all.

---

Right now, I include them as AUX_FILES, they should end up in the uploaded package, and I think that's good enough for now. We should discuss further at the Interop.

[jwfraustro]

Happy seeing the first integration steps for these components.

[Zarquan]

I created a tool for merging OpenAPI specifications.
https://github.com/ivoa/Calycopis-Isobeon

If you point it at a top level schema file it will resolve all the external $ref links and import the content to create one huge schema file. This solves the problems that the code generators have had with resolving $ref links.

It only does local files at the moment but easy enough to extend it to fetch http:// references.