API description in schema.org

[smrgeoinfo]

Linking to existing machine-readable descriptions (documentation or endpointDescription) is great, but doesn't account for the existing APIs that don't have such a description. There might not be an OpenAPI, API Blueprint or RAML (etc.) document describing the service, and not all clients will be able to use one of those. Documenting operations with a schema.org approach would solve that.

If you don't want to pick a winner in the OpenAPI, API Blueprint or RAML (etc.) arena, then the existing suggestions to use potentialAction to describe the operations offered by a service are a solution Machine Readable Web APIs with Schema.org, Template, Service, Interchange format, Interface/API. The benefit of using potentialAction this way is interoperability, at least at some level. It doesn't preclude having links to other documents for clients that use them.

A couple of example instances for actual geoscience data services
https://github.com/earthcubearchitecture-ecresourcereg/ecrro/blob/master/Examples/Interface-ChordsWebAPI-W3Cdraft.json
https://github.com/earthcubearchitecture-ecresourcereg/ecrro/blob/master/Examples/WebAPI-w3cdraft-IRIS-fsdnEvent-JSON.json

[MikeRalphson]

This is outwith the scope of this working group. The scope is to enable use of a schema.org WebAPI type to discover existing human- and machine-readable documentation and related endpoints, not to attempt to replace OpenAPI (which has comfortably seen off RAML and API Blueprint in recent years) with a collection of schema.org types and relations.

[smrgeoinfo]

Perhaps you didn't read what I wrote (I think what you meant is 'not within the scope'????). There are lots of existing services in use that don't have openAPI descriptions. I guess your solution is for the metadata creator to generate an OpenAPI description of the service, and post it somewhere accessible via URL?

The schema.org types and relations are for the most part already there with Actions.