Moving forward: Concrete proposals for most open issues

Hi all,

As I already said, Ruben and I spent some time in Amsterdam to go through
all open issues. Here is an attempt to summarize our discussions and propose
some concrete solutions.
This is a long mail as we discussed almost every issue. I tried to group the
issues and each issue itself follows the following template:

    -- ISSUE-<xy>: <short desc> --

    <problem desc>

    PROPOSAL: <proposed solution>

    <issue URL>


Please do *not* discuss specific issues by replying directly to this mail.
Instead, please create a new thread by changing the subject to

    ISSUE-<xy>: <short desc>

Basically just copy and paste the title without the hyphens at the beginning
and the end. If your feedback consists of just a vote (+1/0/-1), please add
it as a comment directly to the issue if you have a GitHub account. If you
don't have a GitHub account and don't want to get one, please send all of
your votes in a single mail to the mailing list and I'll add them for you,

I hope this helps to keep the discussions somewhat organized.



######################## Operation ########################

-- ISSUE-2: Use the term Action instead of Operation --

Hydra uses the term "operation" whereas Siren has "actions". Schema.org and
Activity Streams also have actions but they are not directly HTTP
operations.

PROPOSAL: Do nothing. Stick to the term operation as it describes an HTTP
operation and not an (abstract) activity as schema.org and Activity Streams
do.

https://github.com/HydraCG/Specifications/issues/2



-- ISSUE-3: Should we introduce a property to associate operations and their
target directly to an entity? --

Currently, operations are referenced by the resources they apply to. For
example:

  {
    "@id": "/some-resource",
    "operation": [
      ... operation(s) ...
    ]
  }

This puts the resources at the center but in some cases it might be
beneficial to put the operation at the center.

PROPOSAL: Do nothing as it can easily be achieved by reversing "operation".
Add a reverse property "target" to Hydra's JSON-LD context to simplify it's
usage in practice and describe it in the specification:

    {
      "@type": "hydra:Operation",
      "target": { "@id": "/some-resource" },
      "method": "POST",
      "expects": {
        "supportedProperties": {
          "property": "rsvpStatus",
          "required": true
        }
      }
    }

The only issue I see with this solution is that "target" was recently
introduced into schema.org but that's probably not that much of an issues in
practice. In fact, we could also encourage (or at least support)
schema.org/target as alternative. Thoughts?

https://github.com/HydraCG/Specifications/issues/3



-- ISSUE-5: Add RetrieveResourceOperation --

We currently have no RetrieveResourceOperation.

PROPOSAL: Describe in the specification that operations are there to modify
resource state, links (like hydra:search) and IRI templates, on the other
hand, are there to drive the application state, i.e., allow navigation and
retrieval of data. Consequently, a RetrieveResourceOperation would be
inconsistent with this classification.

https://github.com/HydraCG/Specifications/issues/5



-- ISSUE-11: Remove predefined operations from the core vocabulary --

The predefined operations have confused many people as they were regarded as
the complete set of supported operations.

In Amsterdam, Ruben and I were inclined to keep them, but make it clearer
that they can either be specialized or alternatively concepts from, e.g.,
schema.org can be reused. Now that schema.org has completed their Potential
Action vocabulary, I think it would be wiser to get rid of them completely.

PROPOSAL: Remove all *ResourceOperations by replacing them with their
schema.org counterparts CreateAction (CreateResourceOperation), DeleteAction
(DeleteResourceOperation), ReplaceAction (ReplaceResourceOperation). As
Schema.org now has a more or less complete Action model, describe in more
detail how it can be used with Hydra.

https://github.com/HydraCG/Specifications/issues/11



-- ISSUE-4: Map predefined operations to CRUD operations and name them
accordingly --

The point that "CRUD" stands for Create, Read, Update, and Delete was raised
a while ago. In Hydra, however we have a *Replace*ResourceOperation. This
could be seen as a special kind of "Update".

PROPOSAL: If we are going to remove all our *ResourceOperations the problem
will solve itself as schema.org has both an UpdateAction and a
ReplaceAction. The difference is is important in practice (idempotence).

https://github.com/HydraCG/Specifications/issues/4



-- ISSUE-23: Explain how operations dependent on a resource's state can be
described --

Sometimes, the operations supported by a specific resource depend on that
resource's state. For example, a draft blog post may be published or deleted
whereas a published blog post may not be deleted anymore to avoid broken
links.

PROPOSAL: This can be achieved by either including operation directly in the
resource's representation or by using specialized subclasses that convey the
resource's current state. Describe both approaches in the specification.

https://github.com/HydraCG/Specifications/issues/23



-- ISSUE-32: Should hydra:returns and hydra:statusCodes be removed to avoid
tight coupling? --

If misused, i.e., hard-coded into clients, hydra:returns and
hydra:statusCodes might introduce tight coupling.

PROPOSAL: Keep them as they are important for a number of use cases but make
it clearer that they should be interpreted at runtime.

https://github.com/HydraCG/Specifications/issues/32



-- ISSUE-27: Having both hydra:statusCode and hydra:statusCodes should be
avoided --

Currently, we have an hydra:statusCodes property on ApiDocumentation and
Operation that points to a StatusCodeDescription. That StatusCodeDescription
then in turn has a hydra:statusCode property which expresses the HTTP status
code.

PROPOSAL: Rename "statusCodes" to "possibleStatus" and
"StatusCodeDescription" to "Status" and describe that these are enumerations
of possible statuses that might be returned at runtime and tell the
developer (in prose in hydra:description) how to recover from errors etc. To
be clear, "returns" is kept as is and expresses what kind of data can be
expected in case of success.

https://github.com/HydraCG/Specifications/issues/27



-- ISSUE-39: Document how "errors" can be given an identifier and be reused
in responses --

Errors or possible statuses in general can be given an identifier that can
then be directly reused in responses so that clients can recognize these
states/errors and automatically recover in certain cases.

PROPOSAL: Document it in the spec. With the new design proposed in ISSUE-27
above it is much easier to describe.

https://github.com/HydraCG/Specifications/issues/39



-- ISSUE-31: Are Operations violating REST's uniform interface constraint?
--

We had a very long discussion about whether operations violate REST's
uniform interface constraint. Ruben and I discussed this again. Here's our

PROPOSAL: Operations are hypermedia controls and as such do not violate any
of REST's constraints. When the specification will be restructured to talk
about things affecting the application state (links) and things affecting
the resource state (operations) this will hopefully become clearer (see
ISSUE-44 in the "Editorial/Enhancements" section). In general, the intent is
to write the spec mostly from a client's point of view.

https://github.com/HydraCG/Specifications/issues/31



######################## SupportedProperty ########################

-- ISSUE-1: Allow SupportedProperty to overwrite a vocabulary's rdfs:label
and rdfs:comment --

If SupportedProperty is used to create forms, it is often desirable to
overwrite the property's rdf:label.

PROPOSAL: This can be achieved by adding a hydra:title (and perhaps
hydra:description) to SupportedProperty. Nothing needs to be added to the
vocabulary but we should add an example and an explanation thereof to the
specification.

https://github.com/HydraCG/Specifications/issues/1



-- ISSUE-14: Rename readonly/writeonly to readable/writeable --

Currently, it is possible to declare a property to be readonly and writeonly
at the same time. So the properties "correlate" strongly. By renaming them
to readable/writeable they wouldn't correlate anymore and it would become
impossible to create an inconsistency.

PROPOSAL: Rename readonly/writeonly to readable/writeable. In general, try
to describe why something should be documented from the client's perspective
and how it is supposed to be interpreted if it isn't specified. For example,
a client is free to try to send any property, but if writable=false it will
know that the server will ignore it.

https://github.com/HydraCG/Specifications/issues/14



-- ISSUE-24: Nested structures (supportedProperty) --

Expressing nested supportedProperty constructs is quite complicated,
verbose, and inflexible at the moment.

The proposal for ISSUE-37 below addresses this.

https://github.com/HydraCG/Specifications/issues/26



-- ISSUE-37: Define/change the range of "supportedProperty" --

Currently the range of "supportedProperty" is "SupportedProperty" which is
not a real property but a wrapper around a property. This has been found
confusing.

PROPOSAL: Change the range of "supportedProperty" to "rdf:Property" and
introduce something like "constraint" (and rename "SupportedProperty" to
"PropertyConstraint") to define the usage of a property in the context of a
specific class. A concrete definition would then look something like this:

  {
    "@type": "hydra:Class",
    "supportedProperty": [ "rdf:type", "schema:name", "schema:address" ],
    "constraint": [
      {

        "@type": "PropertyConstraint",
        "property": "rdf:type",
        "allowedValue": { "@id": "schema:type" },  <--- doesn't exist yet
        "required": true
      },
      {

        "@type": "PropertyConstraint",
        "property": "schema:name",
        "required": true
      },
      {

        "@type": "PropertyConstraint",
        "property": "schema:addressCountry",
        "propertyPath": [ "schema:address" ]  <-- doesn't exist yet
        "required": true
      },
    ]
  }

There are still a couple of open questions that we should discuss:
  - Is "supportedProperty" still needed in this case?
  - Should "property" and "propertyPath" be combined?
  - Should this information still be bound to a class or should we introduce
    a wrapper similar to the current SupportedProperty?

https://github.com/HydraCG/Specifications/issues/37



-- ISSUE-40: Reversed SupportedProperty --

Sometimes, it is necessary to express constraints on reverse properties
because the reverse property hasn't been assigned a URL (e.g., schema.org
has an "author" property but not "authored" or "created" property).

Gregg proposed to introduce a flag like hydra:reversed or a new type
hydra:InverseProperty to express such things. Ruben and I discussed an
alternative design which defines inverse properties on the fly; either using
owl:inverseOf or adding something like that to Hydra if we want to avoid
pulling in OWL as a dependency. The advantage of such an approach is that it
would also work with a property path:

    {

      "@type": "PropertyConstraint",
      "property": "schema:award",
      "propertyPath": [ { "inverseOf": "schema:author" } ],
      "required": true
    },

This would, e.g., make it possible to point from a Person to the awards it
won for its CreativeWorks:

    schema:Person <--[schema:author]-- schema:CreativeWork
--[schema:award]--> "Award"

PROPOSAL: Describe how reverse properties can be used in
SupportedProperty/PropertyConstraint either using owl:inverseOf or something
like hydra:reverseOf (reverse because that's the term that it's used in
JSON-LD and RDFa).

https://github.com/HydraCG/Specifications/issues/40



######################## Collection ########################

-- ISSUE-45: Introduce hydra:filter (subPropertyOf hydra:search)  --

There are use cases like Ruben's Linked Data Fragments which need to filter
collections. hydra:search is deliberately fuzzy to not restrict its usage
unnecessarily and thus not always suitable. Sometimes it is necessary to
filter a collection's members based on the value of their properties (not
properties of their properties or similar things). To enable such use cases,
a specialized subproperty of hydra:search could be introduced. The semantics
would be that a template (pseudo-code)

    hydra:filter [
      hydra:template "/collection?name={schema:name}"
    ]

that is expanded to

    /collection?name=Markus

would return a collection in which all members correspond to the following
graph pattern

   ?member schema:name "Markus"


PROPOSAL: Add a hydra:filter property with the semantics outlined above.

Question: If we decide to support "propertyPath" in "PropertyConstraint",
should we also support propert paths in IRI template mappings? This would
certainly make filter much more powerful.

https://github.com/HydraCG/Specifications/issues/45



-- ISSUE-6: Should sorting of paged collections be specified (in Hydra
core)? --

It is currently not possible to express the sort order of paged collection,
neither is it possible to change it.

PROPOSAL: Sorting quickly becomes very complicated (almost like querying).
Thus I would say we declare it as out of scope for Hydra 1.0.

https://github.com/HydraCG/Specifications/issues/6



-- ISSUE-16: Introduce something like hydra:memberTemplate --

Members of a collection often follow a specific URL structure and thus
providing information about the used URL structure might enable the creation
of more efficient clients. For example, if you have a user collection and
now that each user can be accessed at /users/{userid} you can access a
specific user directly if you know its ID.


PROPOSAL: Do not introduce hydra:memberTemplate but explain how hydra:filter
(a specialization of hydra:search, see ISSUE-45 below) can be used instead.

https://github.com/HydraCG/Specifications/issues/16



######################## IriTemplate ########################

-- ISSUE-30: Expansion of IRI templates should be better documented --

Currently, the expansion of IRI templates is underspecified.

PROPOSAL: By default, when expanding a IRI template, use only the lexical
representation of the value or the IRI (no quoting). Add a flag
"expandedRepresentation" to "IriTemplateMapping", that, if set to true,
changes the expansion to work as follows:

      - The lexical representation is enclosed in quotes with no escaping of
the value itself
      - the datatype xsd:string is always omitted
      - language tags are appended to the lexical representation by using an
@ symbol
      - datatypes are added using ^ (just one) and then the URL without
enclosing it in <>
      - URLs are kept as they are

Thus, the following values in Turtle notation expand to the following
strings when used in a IRI template

      - """Value with a " inside"""  --> "Value with a " inside"
        (without the """ the inner quote would have to be escaped in Turtle)
      - "English"@en --> "English"@en
      - "24"^^<xsd:integer> -->
"24"^http://www.w3.org/2001/XMLSchema#integer
      - http://example.com/ --> http://example.com/

https://github.com/HydraCG/Specifications/issues/30



-- ISSUE-17: Introduce a datatype for RFC6570 IRI templates --

Currently, the value of hydra:template are simple, untyped strings. People,
however, may want to use different template syntaxes and thus it might be
important to be able to distinguish them.

PROPOSAL: Introduce a datatype for RFC6570 IRI templates, but don't change
the range of hydra:template. Update the Hydra JSON-LD context to type-coerce
template automatically.

https://github.com/HydraCG/Specifications/issues/17



######################## Editorial/Enhancements ########################

-- ISSUE-44: Restructure spec to talk about application state, resource
state, and API as whole --

Currently, the specification is written mostly from the perspective of the
server side as the API publisher needs to create the Hydra descriptions. It
may, however, make more sense to describe things from a client's perspective
as that is where those descriptions are going to be used. That way it
becomes simpler to justify why certain things should be done, what aspects
are improved, and what functionality is enabled by doing so. Nothing is just
described for the sake of it should always happen with a clear purpose in
mind.

PROPOSAL: Restructure the specification to talk about application state
(navigation, etc.), resource state (manipulation of resources on the
server), and the API as a whole (metadata, domain vocabulary etc.). This
will then also describe why, e.g., there's no GetResourceOperation.

https://github.com/HydraCG/Specifications/issues/44



-- ISSUE-7: Mention how authorization might be handled --

Currently, the specification is silent on how authorization might be
handled/described by Hydra.

PROPOSAL: Mention that links can be shown/hidden based on the current user's
permissions and add an example to the specification to illustrate it. Other
than that, authorization is out of scope for the Hydra Core vocabulary but
it would make a lot of sense to create a separate vocabulary for this.

https://github.com/HydraCG/Specifications/issues/7



-- ISSUE-15: Define a property to be used for untyped links? --

In HTML, e.g., untyped links are quite common and for simple applications
like crawling they are enough.

PROPOSAL: Do not introduce a property for untyped links. Existing concepts
like rdf:seeAlso can be used just as well. From a machine client's point of
view, untyped links provide very little value.

https://github.com/HydraCG/Specifications/issues/15



-- ISSUE-28: Should properties and types that only differ in their
capitalization be avoided? --

We have a couple of concepts that differ only in their capitalization, e.g.,
hydra:operation -> hydra:Operation and hydra:apiDocumentation ->
hydra:ApiDocumentation. This may lead to confusion or typos.

PROPOSAL: The most important thing is to be consistent. Typos like these are
also quite easy to detect automatically, do nothing.

https://github.com/HydraCG/Specifications/issues/28



-- ISSUE-35: Specify the expected cardinality of properties (using OWL) --

Before all property names were converted to singular, they indicated their
expected cardinality. There was a proposal the expected cardinality in OWL
but there's no way in OWL to describe an unbounded maximum cardinality
(something like operation 0..*).

PROPOSAL: This is mostly for developers and not directly for machines (apart
from validators). Our needs are quite trivial so I would suggest to simply
define something like hydra:multiple (as I think Gregg proposed) that we can
use both in SupportedProperty and in the vocabulary description.

https://github.com/HydraCG/Specifications/issues/35



--
Markus Lanthaler
@markuslanthaler

Received on Saturday, 19 April 2014 16:23:52 UTC