schema:endpointDescription

[smrgeoinfo]

"An alternative that was considered was to create an additional property, schema:endpointDescription with range schema:CreativeWork, in order to create a more explicit separation between human-readable documentation, and machine-readable endpointDescription."

This seems like a good idea to me. The current version is ambiguous on when to use documentation or url; this would at least reduce the ambiguity on where to look for a machine-actionable service description conforming to some convention.

[nickevansuk]

Some further context for this discussion from https://github.com/schemaorg/schemaorg/pull/1445#issuecomment-263563331: the original addition of schema:CreativeWork to the range of schema:documentation was inspired by various formats of human-readable documentation, rather than machine-readable documentation.

And of course the DCAT v2 to schema.org mapping could only map to schema.org properties that existed at the time of publication, rather than propose new ones, so we should not give too much weight to their decision to lump both into schema:documentation.

I could be swayed either way on this. In fact, thinking about our own use case, we'd likely prefer this to be broken out into two separate properties as it makes it easier to parse and display the human- and machine-readable links separately without needing to maintain a "whitelist" of human-readable encodingFormats to distinguish them.

[nathansalter]

I think in our case it also makes sense to split out the two human to non-human readable documentation links. Maintaining lists of acceptable/unacceptable content types to split between the two seems like you'd quickly get issues with not knowing all the content types or variations. The only argument I can see against this is that it's then up to the publisher to define what's human-readable vs machine readable. Also, if you've got a type which on one URI is human-readable but the other URI is not there's no real way of distinguishing between them.

[nickevansuk]

@MikeRalphson - we just covered this issue on the latest OpenActive community group call (https://w3c.openactive.io/meetings/2020-07-15-dataset-site-specification), and requested that thoughts be shared directly on this issue (thanks @nathansalter!).

It does seem like there's a growing consensus that endpointDescription might actually be the way forward here, as whitelisting encodingFormats appears to be an excessive burden on data users given the large number of "human-readable" content types that browsers support, and the variety of other content types that could be considered "human-readable" (e.g. Microsoft Word documents).

Do you think, given the whitelisting challenge, that the resolution here is self-evident, and we should update the draft? Or should we seek wider feedback?

[MikeRalphson]

Consensus certainly seems to be leaning in that direction.

[nickevansuk]

@MikeRalphson so given that this is set for inclusion in the next schema.org release, I've created a PR of the changes required, to make the alternative proposal clear: #17

[thill-odi]

Further context if required: a recording of the call in which the OpenActive W3C Community Group discussed the question is available here: https://youtu.be/swuIW8H8sX8, starting at roughly 39:40.

[smrgeoinfo]

After listening to the discussion in the OpenActive W3C Community Group recording a couple observations:

• endpointDescription is included in DCAT v2 as a property of DataService (in the discussion they didn't seem aware of this). DCAT is focused on DataSets, so really the only API/Services its interested in are DataServices. It isn't much of a stretch to think of a machine-readable endpoint description as applicable to any WebAPI endpoint

• lots of the discussion was about the human readable descriptions, but specifically identifying machine readable descriptions is what's important for automated clients, this is the motivation for an endpointDescription property.. Web browsers can display most of the kinds of machine readable descriptions (JSON, XML) in some form anyway, but an automated client will need a very specific kind of description (e.g. OpenAPI v3.3, OGC GetCapabilities v1.3).

+1 on schema:enpointDescription

[westurner]

1. Would it be appropriate to support Enumerations for https://schema.org/encodingFormat? FWIU, https://github.com/schemaorg/schemaorg/issues/2604 improves support for listing Enumerations in the docs.

2. Could there be an example demonstrating how to indicate that something is a SOLID / LDP API with support for JSON-LD and RDF/XML representations?

Is there a way to query for LDP / SOLID APIs with the proposed schema? I would consider that to be necessary functionality.

"RFC0001 LDP and Solid Content-Types?" https://github.com/webapi-discovery/rfcs/issues/5#issuecomment-465660889

[sumutcan]

Hi, As part of my PhD work I have been trying to use schema.org actions together with the WebAPI type as a web service description vocabulary and currently solving that by using the encodingFormat property on the range of schema:documentation [1]. For machine readable documentations, application/ld+json is recommended, but any other RDF serialization would also work. This is currently enforced by SHACL shapes.

[smrgeoinfo]

@sumutcan we've been exploring that approach as well, based on your Machine Readable Web APIs with Schema.org Action Annotations (https://doi.org/10.1016/j.procs.2018.09.025) publication.
Accessing Data through a Service Endpoint

also relevant https://github.com/schemaorg/schemaorg/issues/2340, https://github.com/schemaorg/schemaorg/issues/2342

If endpointDescription is used, these approaches could be used for a schema.org based endpoint description, but as pointed out in the brief discussion on https://github.com/webapi-discovery/rfcs/issues/15, this is not really necessary for WebAPI discovery, the proposed WebAPI extension stipulates OpenAPI for endpoint descriptions, and there are various interpretation of what 'Actions' are supposed to represent.

[MikeRalphson]

PR #17 has been merged, thanks all.

[westurner]

... Watch "Justin Bieber - Yummy (Lyric Video)" on YouTube

Is there a more complete example than: https://webapi-discovery.github.io/rfcs/rfc0001.html#full-example ?:

"endpointDescription": [
   {
     "@type": "CreativeWork",
     "encodingFormat": "application/json",
     "url": "https://kgsearch.googleapis.com/$discovery/rest?version=v1"
   },
   {
     "@type": "CreativeWork",
     "encodingFormat": "application/vnd.oai.openapi+json;version=3.0",
     "url": "https://api.apis.guru/v2/specs/googleapis.com/kgsearch/v1/openapi.json"
   }
 ],

[MikeRalphson]

The examples are intended to be illustrative, not comprehensive (in that they don't show everything that can be done with the proposed extension). Is there something you feel is glaringly missing? If/when this is adopted by schema.org, I would expect their examples to be the canonical ones.

[westurner]

There's a link to the versioned OpenAPI schema, so that's progress.

The OpenAPI Info Object metadata fields appear to be redundant but roughly congruent: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#fixed-fields-1 https://github.com/OAI/OpenAPI-Specification/