draft VOSITables changes for user-managed tables #3
Conversation
Well, it turns out there hasn't been one all these years, which means that
all VOSI StandardIDs ("ivo://ivoa.net/std/VOSI#capabilities") really pointed
nowhere.
That nobody even noticed may raise questions on how useful StandardsRegExt
StandardKeys actually are. But that's beside the point here.
I need the record here to say something about what #availability is
in a post-caproles VO.
Also changing the inclusion of the VOSITables schema to lstinputlisting; pulling this from the authoritative, on-disk version seems a good idea. Whether it's a good idea to print the two schema files at all is another matter. I'd say no, but I'd leave removing them to the editor.
Also including git metadata.
initial user-managed table extension in OpenAPI
Remove availability
Add/Update gh-Workflows for PDF Preview
trying to make the prose less specification and more explanation and examples
preview: update checkout to v3
There was a problem hiding this comment.
Some minor comments on the open-api definition.
More broadly, I'm wondering if there's overlap between OpenAPI and /capabilities. Is there potential for OpenAPI to replace /capabilities? I imagine that the registry extension parts would become quite complicated.
Are there any uses of /tables outside of DAL? Could that part of the spec be moved out of GWS to DAL?
With /availability gone, this spec is getting pretty thin. Just throwing these ideas out there to encourage conversation and not necessarily action at this point.
fix operationId for vosi-table (post)
|
Yes, there is considerable overlap between OpenAPI and capabilities. Capability, TableSet, and Table are really part of the core VOResource et al and thus registry model; VOSI just provides some small xsd to define stand-alone documents and a simple API for service self-description. I think VOSI-capabilities (self-description) serves some purposes beyond client asking about the API. Even for that client interaction, there is no obvious way for a client looking at the OpenAPI description to determine that the endpoint matches some standard the client knows about... for example, sure it could see an endpoint that returns a VOSI-tableset document and has min and max params, but that isn't the same as knowing the expected behaviour. For now (VOSI-1.x) I expect that OpenAPI augments the standard itself; including the openapi.yaml in a service and maybe using it to generate API docs is possible... code generation is possible... but making the presence of openapi.yaml a requirement is TBD at best. |
|
As for VOSI-tables itself, tables can conceptually be part of anything and it might not (in future) be only DAL services. I'd be against moving it, especially in VOSI-1.x, for no real gain. Others might draw the line between VOSI and DALI in a different place, but the latter has a far bit of astronomy-specific things, while VOSI is more or less domain-agnostic. |
|
Thanks, I pretty much agree. There's sometime to be said for minimizing the number of changes at once too. |
3 participants
plus change to WD-VOSI-1.2 but no doc changes yet
This now includes text in the document and a reference to the OpenAPI spec.
Still TODO:
Also, section 2 (interface binding) and 3 (metadata) are probably backwards and cvould be swapped. Then most of the interface description could stay in section 3 which would be interface description. Alternatively, maybe a section{Capabilities} and a Section{Tables} where each flows nicely from metadata to interface description. I think that would be better...