SHACL: Use with hydra:expects

[tpluscode]

Describe how sh:NodeShape can be used in place of (together with) hydra:Class to describe request payloads

[alien-mcl]

I'd prefer "together with" - extensions should not replace hydra constructs which could lead to alternate reality available to clients understanding an extensions compared to those not understanding it.

[tpluscode]

Right. To elaborate, I see two possible scenarios, for the two possible kinds of shapes

Shape with implicit target

<Person> a hydra:Class, rdfs:Class, sh:NodeShape .

<CreatePersonOperation> a hydra:Operation ; hydra:expects <Person> .

This one is simple. The <Person> class simultaneously have sh:property and hydra:supportedProperty to provide descriptions for clients who understand the extension and those who do not.

sh:targetClass

<PersonShape> a sh:NodeShape ; sh:targetClass foaf:Person .
<AgentShape> a sh:NodeShape ; sh:targetClass foaf:Agent .

foaf:Person rdfs:subClassOf foaf:Agent .

<CreatePersonOperation> a hydra:Operation ; hydra:expects foaf:Person .

This one is a bit more problematic and potentially falls in the in place of bucket. The shape is super useful in describing API-specific graph structures for external classes. SHACL also supports subclassing by design. The server in this scenario would validate the model using constraints coming both from <PersonShape> as well as <AgentShape>.

There is an overlap with #10, where the client would have to be able to find these shapes so that they know how to construct a request. Of course the worst case scenario is that they would get all shapes and find the right ones in memory at the expense of fetching a larger collection.

The problem I have with trying to simultaneously provide description using both Core and SHACL in such scenarios is that you would end up with a bloated client and server code. I'd rather say in the spec that an API MAY provide the rudimentary Hydra Core descriptions but give them the option to require that clients understand only SHACL. This should be enough for semi-closed scenarios, such as internal APIs

[alien-mcl]

give them the option to require that clients understand only SHACL

I think it is no more an extension. A replacement is a better name.

As for the examples - both looks fine to me. I feel a client would need to understand both