Profiles offered by a service must be discoverable through a machine-readable graph of metadata that describes what is offered and how to invoke the offered profiles. [ID5] (5.5)

[nicholascar]

Entered from Google Doc

[larsgsvensson]

tl;dr: IMHO this requirement is not in scope for conneg-by-ap.

The UC for this requirement is Discover available content profiles. Having built up the motivation for the feature, the UC goes on to say:

Thus there is a need for discovering which profiles a service will offer for a given resource, and a canonical machine readable graph of metadata about what such offerings consist of and how they may be invoked. This may be as simple as providing a profile name, or content profile, schema choice, encoding and languages.

Discoverability and invocation of profiles is handled by the abstract methods list profiles and get resource by profile, so we're fine there.

In the context of profile negotiation, the relevant part is "Thus there is a need for discovering which profiles a service will offer for a given resource [...] and how they may be invoked. This may be as simple as providing a profile name, or content profile, schema choice, encoding and languages." I. e. the part about the machine-readable graph is not in part of the scope for profile negotiation.

This comment is part of ACTION-240

[nicholascar]

I suggest removing label profile-negotiation and leaving profile-guidance to let the gGuidance group examine this Requirement.

[kcoyle]

I think we can distill something usable from this but not take it whole-cloth. The part about "how to invoke the offered profiles" seems out of scope for the profile guidance document. That is because profgui isn't going into how to use profiles, only what they are and how to publish them. I do think that the guidance should address the issue of discoverability and make some suggestions on how to make your profile more discoverable (and to whom and for what purpose, which I don't think we've covered yet). This can include using schema.org in an html version or as a separate file, using the profile ontology, if you use PDFs make sure they include searchable text, use sitemaps, etc.

We probably shouldn't require a machine-readable graph since we aren't assuming an RDF-only profile environment. Maybe some other wording relating to search engines would be useful here?

[smrgeoinfo]

I agree the 'how to invoke' is probably out of scope; it should be sufficient for the profile representation document (whether graph, html, xml...) to specify the protocol; clients will be expected to look for affordances using protocols the client implements.

[agreiner]

I don't think hardly anybody uses sitemaps anymore.

[aisaac]

Hardly anybody uses sitemaps? As in 'sitemaps to be consumed by search engines'? This is still step 1 of SEO in many cases...

[larsgsvensson]

+1 to @aisaac
Can perhaps @danbri weigh in on this?

[agreiner]

That is sitemaps as a form of site navigation. Look around any major site and see how readily you can find a site map.

[larsgsvensson]

@agreiner scripsit:

That is sitemaps as a form of site navigation. Look around any major site and see how readily you can find a site map.

Ah, I assumed that @kcoyle meant XML-Sitemaps.

[aisaac]

Let's come back to some of the original discussion for this requirement. @agreiner had suggested in a old call to re-word it as "It must be possible for profiles to be made discoverable through machine-readable metadata that describes what is offered and how to invoke the offered profiles."

While I'm not sure it fixes all the questions one could have about this requirement, I feel it would be a pity not to validate this re-wording. I think it brings a welcome clarification.

[kcoyle]

It is indeed clearer, although I'm still not sure what we mean by "how to invoke" - what kind of invoking are we talking about? Is this more than indicating that it's a PDF vs. a SHACL file or an XSD?

[aisaac]

It is about how to invoke a specific profile for a data resource. This is DCAT-level (or in fact any resource that is described in RDF). A service publishing data tells which profile it has, and how the data that conforms to them can be obtained.
It sounds like requiring a mixture of PROF (for describing profiles), DCAT (for linking a piece of data to a profile), and the methods in the Conneg doc that list profiles available for a specific negotiation option (Conneg or QSA). The issue is that how to represent the 'how to invoke' probably depends on the negotiation method.
@rob-metalinkage @RubenVerborgh @nicholascar can you confirm this reading?

[RubenVerborgh]

Conneg, however performed, will indicate the profile(s) the response conforms to.
Concretely, there will be:

Content-Profile: https://example.org/profile/A, https://example.org/profile/B

So this gives the URI of the profile, which can be dereferenced.

[larsgsvensson]

@aisaac scripsit:

It is about how to invoke a specific profile for a data resource.

I still don't understand what "invoke a profile" means... Is it the same as "get content conforming to a profile"?

This is DCAT-level (or in fact any resource that is described in RDF).

Yes, it's definitely not constrained to DCAT (and thus I don't think it's a DCAT requirement)

It sounds like requiring a mixture of PROF (for describing profiles), DCAT (for linking a piece of data to a profile), and the methods in the Conneg doc that list profiles available for a specific negotiation option (Conneg or QSA). The issue is that how to represent the 'how to invoke' probably depends on the negotiation method.

I see the relation to PROF and to conneg, but not to DCAT in particular. Any piece of data sent can conform to a profile, so we need a mechanism that doesn't depend on DCAT.

[larsgsvensson]

@RubenVerborgh scripsit:

Conneg, however performed, will indicate the profile(s) the response conforms to.

Yes, the question is if we say that the use of http headers is the only way of sending this information. I think it should be, but that's just my opinion...

[RubenVerborgh]

Yes, the question is if we say that the use of http headers is the only way of sending this information.

Of this particular header actually (because there is also Link).

Please, let there be one way.

[aisaac]

@larsgsvensson yes to me 'invoking a profile for a resource' means 'getting content conforming to that profile for the resource'.
And I'm using 'DCAT-level' as a generalization of what DCAT does, i.e. describing how datasets can be accessed. I fully agree that the requirement is wider than DCAT, but I don't see anything elsewhere that would provide such 'hooks' for the requirement. POWDER, maybe?
The issue is that as @RubenVerborgh says, Conneg somehow meets the requirement: it's clear what is offered and how to get it. But Conneg itself doesn't offer a 'machine-readable graph of metadata' that describes what is offered for a resource and how to get it, as this requirement seems to ask for.

[larsgsvensson]

Thanks @aisaac, that clarifies a lot.

Regarding the "machine-readable graph", my view has always been that when you dereference the profile URI you should get something back that describes what the profile is and that would/could be a "machine-readable graph" using e. g. the profile ontology. Would that satisfy the requirement?

[RubenVerborgh]

We can just say it SHOULD be available as RDF, without having to specify the exact content schema.

[rob-metalinkage]

Just RDF doesn't buy much value - although its better than anything that doesn't even provide namespaces for data elements - such as XML without schema, or JSON.

I think we should drop the word "graph" - but also we all need to be aware that XML or JSON or any other nested structure is also a graph - it merely implies that such metadata is unlikely to be a trivial flat record or a scalar value (a single literal). That's reality - now we work out how to communicate it better...

We should make a statement about the actual requirement here - which is not machine-parsing - its machine-interpretation - i.e. the ability to recognise a canonical description of the key elements of a profile (its conceptual model),

The reason for SHOULD is mainly because we don't have enough experience and evidence to dictate a canonical form (which would give maximum interoperability) , but we do have a candidate we can recommend now at least.

So I think the wording for the requirement could be more along the lines of

Requirement: profiles offered by a service must be discoverable through metadata that describes what is offered and how to invoke the offered profiles. This metadata SHOULD be described using a canonical expression such as the Profiles Ontology.

[rob-metalinkage]

Or even closer to the actual intent perhaps:

Requirement: profiles offered by a service must be discoverable through metadata that describes what is offered and how to invoke the offered profiles. This metadata MUST be machine-readable and SHOULD be described using a canonical expression such as the Profiles Ontology.

[kcoyle]

Is the "service" here being understood solely as a content negotiation service, or could it be a service as defined by DCAT (an example of which is an API)? If the latter then this adds a new requirement on DCAT, and I don't know what the implications of that are. @davebrowning @agbeltran ?

[RubenVerborgh]

I think "offered by a service" is actually inaccurate language. I think it should be "a resource should provide discovery for the profiles to which any of its representations conform". We do not identify the service as an entity.

[aisaac]

+1 for clarifying 'offered by a service'. But I think it's still important to keep the notion of 'data offer' and less as a constraint for the representation).
Maybe "For a given resource, a data service must enable the discovery of the profiles for which a data consumer can access conformant representations of that resource. This must happen through machine-readable metadata that describes what is offered and how to invoke the offered profiles".

I would not add references to canonical representation and PROV. This is going toward the side of solution space, considering the original case. Even the canonical representation was not even there. It's rather a good design principle that we are going to adopt in our response to the requirement.
(and I think it's completely fair that a requirement brought by a specific use case wouldn't necessarily incorporate all the best practices that are relevant for it)