Use the term Action instead of Operation

[lanthaler]

Hydra has "operations" whereas Siren has "actions". Activity Streams also has actions. So has the latest schema.org proposal. I'm not a native speaker and don't really care how this is called but I realized recently that almost everyone else calls these things "actions" :-)

[http://lists.w3.org/Archives/Public/public-hydra/2013Jul/0002.html]

[elf-pavlik]

:+1: helps with avoiding confusion when people use Action subtree from schema.org

[lanthaler]

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.

[lanthaler]

Thomas prefers Operation Gregg is slightly in favor of Action Chris prefers Action Kingsley +1 to Action Markus could live with either term

[dschulten]

:+1: Action

[elf-pavlik]

I posted yesterday email to SocialWG inspired by one of @lanthaler replies - http://lists.w3.org/Archives/Public/public-socialweb/2014Sep/0050.html

I suggest there to distinguish Operation on web resource Action on abstract thing

[tpluscode]

This has been here for over 3 years. Is it fair to say that the term Operation has already gained a foothold in Hydra's spec? I think it's not worth changing it now any more.

[akuckartz]

No such terms in Hydra should be considered final.

[lanthaler]

Yeah, IMO we should keep operation to describe HTTP requests etc. and may use he term action for the abstract act (like something, order something, …)

[tpluscode]

Sounds good. But would the action become a term used in the vocabulary?

[RubenVerborgh]

FYI I have called them “actions” in the draft architectural diagram because this sounded most natural in that context. (Of course this doesn't represent a decision in any way.)

[elf-pavlik]

Short note on Operations (on web resources) and Actions (on abstract things). I've mostly seen instances of hydra:Operation represented with blank nodes but they could as well have @id. Action on abstract thing could possibly reference particular Operation (since each operation could have an @id) and web resource on which to perform it - (maybe with https://schema.org/target )

Taking example of Alice and list of her 'followers', represented by https://www.w3.org/community/hydra/wiki/Collection_Design and used like ldp:IndirectContainer

{
  "@context": { ... },
  "@graph": [
    {
      "@id": "https://dataset.example/api#operation-123",
      "@type": "hydra:CreateResourceOperation",
      "hydra:method": "POST",
      "hydra:expects": "foaf:PersonalProfileDocument"
    },
    {
      "@id": "https://dataset.example/alice",
      "@type": [ "hydra:Resource", "foaf:PersonalProfileDocument" ],
      "foaf:primaryTopic": {
        "@id": "https://idp.example/alice",
        "@type": "foaf:Person",
        "foaf:name": "Alice",
        "schema:potentialAction": [
          {
            "@type": "schema:FollowAction",
            "schema:target": "https://dataset.example/alice/followers/",
            "???:operation": "https://dataset.example/api#operation-123"
          }
        ]
      }
    },
    {
      "@id": "https://dataset.example/alice/followers/",
      "@type": "hydra:Collection",
      "hydra:manages": {
        "hydra:property": "schema:follows",
        "hydra:object": "https://idp.example/alice"
      },
      "hydra:member": [
        "https://dataset.example/alice/followers/1"
      ]
    },
    {
      "@id": "https://dataset.example/alice/followers/1",
      "@type": [ "hydra:Resource", "foaf:PersonalProfileDocument" ],
      "foaf:primaryTopic": {
        "@id": "https://idp.example/bob",
        "@type": "foaf:Person",
        "foaf:name": "Bob"
      }
    }
  ]
}

So to add oneself to list of someone's followers, one would HTTP POST to https://dataset.example/alice/followers/ a copy of profile document:

{
  "@context": { ... },
  "@type": [ "hydra:Resource", "foaf:PersonalProfileDocument" ],
  "foaf:primaryTopic": {
    "@id": "https://idp.example/cecilia",
    "@type": "foaf:Person",
    "foaf:name": "Cecilia"
}

Which server could after validations store as https://dataset.example/alice/followers/2

[tpluscode]

That's quite interesting. I like how you use schema:potentialAction. The only big difference now is the use of schema:target, which turns the action around compared to current operation spec (the target being the subject of hydra:operation). And of course supported operations (potential actions?) in ApiDocumentation would need to be refactored too.

I see now clearly how an action has a domain meaning and the operation is used to describe the technicalities.

Which makes me think that maybe we could simplify the operation terms indeed. If the value of ???:operation was actually a description of the HTTP request could reuse some of the HTTP vocab. Not only would Hydra get decoupled from HTTP but we'd also open a whole new possibility of operations other that HTTP (could be a good thing?).

[tpluscode]

Also, it seems that schema.org does have a term which kind of fills in the hydra:Operation: schema:EntryPoint. See http://schema.org/docs/actions.html#part-3.

Maybe we could build on top of that?

[asbjornu]

@tpluscode: Wow, the level of detail on the use of schema:Action exceeded my expectations. It's even got Input and Output Constraints, such as:

"<property>-input": {
  "@type": "PropertyValueSpecification",
  "valueRequired": true,
  "valueMaxlength": 100,
  "valueName": "q"
}

I wonder how Hydra should relate to this. Adopt it as is, mimic it or what?

[tpluscode]

I think that Hydra should provide extension points. One such extension point could be support for extending operations with custom constraints such as those from schema or SHACL

[lanthaler]

I reviewed most of the Action design in schema.org when it was designed. There are lots of great things about it but when it comes to describing the HTTP requests it is underspecified and not very practical IMO. I think we should align as closely as possible with it but feel free to deviate in some of the details. The <property>-input design for instance is quite tricky to deal with in in practice and might break completely if it is being used with a vocabulary other then Schema.org