potentialAction

[smrgeoinfo]

An approach to description of service operation in Schema.org has been outlined (Part 3: Action EntryPoints) , but there are some issues that need to be clarified. See https://github.com/schemaorg/schemaorg/issues/2340, https://github.com/schemaorg/schemaorg/issues/2342

[MikeRalphson]

It's not clear what your call-to-action is here? Is it simply to create a place to link issues in other repositories? The schema.org examples are outwith the scope of this working group, as is use of potential Actions of a CRUD nature to describe the contract of a WebAPI. This is about discovery.

[nickevansuk]

@smrgeoinfo I also made the same error initially when I read https://schema.org/docs/actions.html as an opportunity to enable a hypermedia-driven API using schema.org vocab (and without going all the way to adopting Hydra). Indeed a previous iteration of one of our own specifications adopted this pattern erroneously.

If you look at potentialAction in the wild, however, its actual use case becomes much more apparent:

• https://developers.google.com/actions/media/reference/data-specification/tv-shows-specification
• https://developers.google.com/actions/media/reference/#action_markup
• https://developers.google.com/search/docs/data-types/sitelinks-searchbox
• https://developers.google.com/gmail/markup/reference/go-to-action
• https://developers.google.com/actions/media/collect-information/identify-the-deep-links#deep_link

"Actions are used to describe an affordance to perform a certain operation..." (ref). Also see here for a clearer description of the intent of Actions.

As you can see from the above, they were not intended to compete with what is now OpenAPI and other similar forms of machine-readable API description.