Open smrgeoinfo opened 4 years ago
I believe we were explicitly steered towards using Actions
for this. They are intended to be follow on (potential) actions to the discovery process. isRelatedTo
sounds somewhat vague (especially given the description "A pointer to another, somehow related product (or multiple products).") whereas I agree what we might want is something along the lines of the HTTP Link
header rel
(relation-type). @nickevansuk thoughts?
It's a bit of a philosophical point, but my understanding is that potentialAction
s are designed to affect the intended object via a website or app deep link, rather than directly.
When using TrackAction
to track the ParcelDelivery
, the target
in the example takes you to http://fedex.com/track/1234567890
, and hence the mail client (in this case) displays a link to http://fedex.com/track/1234567890
. The client does not interact with the physical parcel itself, but instead with the service that delivers the parcel.
Hence when using RegisterAction
to register for access to a WebAPI
, the target
in the example takes you to https://developers.google.com/knowledge-graph/how-tos/authorizing
, and hence the API aggregator client displays a link to https://developers.google.com/knowledge-graph/how-tos/authorizing
. The client does not interact with the actual API itself, but instead with the service that delivers the API.
Apologies for the contrived analogy, but hopefully helps clarify!
Also isRelatedTo
would be more useful to link to alternative API versions (as per https://github.com/schemaorg/schemaorg/pull/1445#issuecomment-265199747)
Suggestions for potentialActions (API console, API SLA, and API Support, API Authentication, API Payment) are not actions on the API, but links to related resources. isRelatedTo is an obvious property for these cases. The example in Section 5 has a potentialAction that has a different endpoint from the endpointUrl. This should be an isRelatedTo link to a Service for API client Registration.