endpoints should be defined as either @container: @id or @container: @nest

[trwnh]

Please Indicate One:

• Editorial
• Question
• Feedback
• Blocking Issue
• Non-Blocking Issue

Please Describe the Issue:

originally w3c/activitystreams#536

Proposal

One of the following:

• endpoints should have "@container": "@id" defined, in order to declare its keys as IRIs.
• endpoints should have "@container": "@nest" defined, in order to declare its nesting as semantically irrelevant.

Motivation

The semantics of endpoints are not fully captured at present. Are they properties of the actor which are shared server-wide, or are they an ID map? https://www.w3.org/TR/json-ld11/#node-identifier-indexing

(Tangentially, I am unsure if "@type": "@id" is appropriate on those endpoints, given that it seems to specifically signal node identifiers, and the endpoints are not nodes on a graph, they are endpoints. Perhaps something like xsd:anyURI or leaving it as the default @value? I might be wrong on this, unsure.)

[evanp]

Per discussion at issue triage, @trwnh will provide some examples in the LD playground of how the structure looks under:

1. Current situation (no change)
2. with @container: @id
3. with @container: @nest

We should be able to identify what this change will do for developers.

[trwnh]

Having another look at this, I believe that I was somewhat mistaken here -- @container: @id is for treating a map as an array, to allow easier indexing of an array item rather than having to process and filter the entire array. Example:

[
  {
    "https://www.w3.org/ns/activitystreams#endpoints": [
      {
        "@id": "https://example.com/oauth"
      },
      {
        "@id": "https://example.com/proxyUrl"
      }
    ]
  }
]

This would help in the case that each endpoint was actually a linked data node, and had its own properties... which doesn't seem to be the case.

---

Meanwhile, @nest is actually meant to be aliased as @id: @nest in order to signal that the linked data node is not a real node... which in ActivityPub, it sometimes is (as it can be a reference to an external document that is shared server-wide). Example:

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    {
      "endpoints": {
        "@id": "@nest"
      }
    }
  ],
  "type": "Person",
  "name": "Alyssa P. Hacker",
  "oauthAuthorizationEndpoint": "https://example.com/oauth",
  "proxyUrl": "https://example.com/proxyUrl"
}

This might be semantically more accurate (or arguably not), but it represents a breaking change, so it's probably not worth going for this.

---

Given the above two examples: I think the best option would actually be to do nothing re: endpoints. That does leave open the question about whether each of the defined endpoints should be @type: @id or @type: xsd:anyURI, but that seems like a different issue, so I will close this one and file a more specific, narrower issue regarding those endpoints.