There are various situations on which a server would like to + provide additional details on some constraints or additional + requirements. These would be applicable in various areas, like + strongly typed collection description or variable limitations. + This section describes concepts that can be used to achieve + these features.
+ +Hydra allows to express both expected or returned body + description. The first and most common approach is to provide + a class IRI as a target of the expects/returns + predicates - this simply instructs the client that for a given + operation an RDF resource that is of the expressed type. + In case the expected body does not explicitly say it, server + MAY imply it on it's own.
+ +Another approach is to provide a more robust description + with specifies predicate.
+ ++ ++ +
The example above is an equivalent of the `expects`: `schema:Event` + construct, but it is enabled for more detailed description in a + reification-like manner, where a subject of the specification is + a hypothetical resource being specified, property and + object are relation elements that the resource SHOULD be + compliant with. In case the expected resource does not contains + the specified statements, server MAY imply those from the specification + on it's own.
+ +It is possible to build adequate constructs for returns + declaration.
+ +As an alternative to RDF based resource specification, it is also + possible to provide a more generic resource description for non-RDF + Api communication. This can be achieved using a robust approach + in conjunction with mediaType predicate:
+ ++ ++ +
It is NOT recommended to describe non-RDF resources + with property/object predicates with values n.e. from + HTTP in RDF vocabulary. While such a description would provide detailed + information that n.e. a resource expected should have a header name + of a specific value, but this approach is indistinguishable from + actual RDF description of resources meeting some RDF pattern (n.e. + in case of meta-data of non-RDF resources).
+There are circumstances in which a collection should provide more + detailed description about it's members, n.e. by denoting the type + each member is of. This description can be provided on both + Api documentation level and on the actual collection's + hypermedia level with already described robust approach.
+ ++ ++ +
Please note the nested specification through manages predicate + (as this predicate is a sub-property of specifies). + Client SHOULD assume that the nested specification is applicable to + nested resources (resources available in that case in the collection).
+ ++ ++ +