Call for consensus/feedback: inconsistency between AS2's normative context document and normative vocabulary document

Context: https://github.com/w3c/activitystreams/issues/595

About 2 years ago, I noticed that the property "href" (as found on a
Link) is inconsistently defined between two of our normative
documents.

In the normative context document, it is defined like so:

"href": {
  "@id": "as:href",
  "@type": "@id"
}

This definition means that the value of "href" is expanded into a Reference:

{
  "@type": ["https://www.w3.org/ns/activitystreams#Link"],
  "https://www.w3.org/ns/activitystreams#href": [{"@id":
"https://target.example/"}]
}

However, AS2-Vocab defines "href" like so:
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-href

Specifically, the vocabulary definition calls out the range as being xsd:anyURI.

2 years ago I thought the context document might be mistaken, but I
have since come to understand that it is AS2-Vocab which is mistaken.
The reasoning for this is below.

First of all, the meaning of @id and the meaning of xsd:anyURI should
be covered. Conceptually, there is a difference between a Reference
(@id in JSON-LD) and a Literal (@value in JSON-LD).
https://en.wikipedia.org/wiki/Value_type_and_reference_type

When a JSON-LD term definition says something is @type: @id, it means
that the value should be interpreted as a reference or link. This is
what makes "linked data" work.

When a JSON-LD term definition *doesn't* include @type: @id, it
defaults to a literal @value. It is not a Thing, but rather a String.

Given that @id makes something into a reference and thus a link can be
followed, it makes sense to say that our AS2 Link should be a
reference, so it can be used as a link. In the definition for Link
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-link we call out
that the fundamental model of AS2 Link is intended to be the same as
in RFC 5988 Web Linking (later superseded by RFC 8288). That RFC also
defines web links as a form of reference.

Another affordance that links have (but literals don't) is that they
can be passed to any URI/IRI library directly, and they inherit the
current networking context, so relative links can be made absolute
against the current resource using the algorithm described in RFC 3986
(URI generic syntax).

Semantically, xsd:anyURI is inappropriate for describing links
because, as a value typing, the datatype is a hint for coercing the
literal string value (its lexical form) into some other datatype. The
meaningful difference between a statement like "John wrote what is
referenced by https://foo.example/" and "John wrote the literal string
https://foo.example/" is that in the former, we are claiming that John
has written some resource, and in the latter, we are claiming that
John has written the sequence of characters h, t, t, p, s, colon,
slash, slash, and so on. https://stackoverflow.com/a/75603513

Given all of this, I would conclude that AS2-Vocab should be amended
such that the range of "href" is NOT xsd:anyURI, but rather we should
point out it is a reference to some resource -- exactly how links are
supposed to work. We make a similar mistake in defining "type"
https://www.w3.org/TR/activitystreams-vocabulary/#dfn-type and
"formerType" https://www.w3.org/TR/activitystreams-vocabulary/#dfn-formertype
which claim to have ranges of "anyURI" and "Object" but are actually
supposed to have a range of Class (since types are specifically
classes). These other issues have been raised in
https://github.com/w3c/activitystreams/issues/440 and
https://github.com/w3c/activitystreams/issues/655 previously.

Evan disagreed with the conclusion above, believing that the context
document should be changed to define "href" as @type: xsd:anyURI
instead, on the basis that "href" should be a Literal and not a
Reference. The concern Evan raises is that objects may be embedded as
the value of "href", and it would make more sense to prevent that. I
point out that this is a schematic concern and not a semantic concern,
since the goal of having the value be expressed as a JSON string is
independent of whether that string should be interpreted as a
reference/link or as a literal/value. We could define schematic
requirements for AS2 documents, although we currently mostly don't
define any schematic constraints.

To illustrate the difference, consider how "href" would currently be expanded:

{
  "@type": ["https://www.w3.org/ns/activitystreams#Link"],
  "https://www.w3.org/ns/activitystreams#href": [{"@id":
"https://target.example/"}]
}

And if it were defined to be xsd:anyURI instead, then it would expand
to this instead:

{
  "@type": ["https://www.w3.org/ns/activitystreams#Link"],
  "https://www.w3.org/ns/activitystreams#href": [
    {
      "@value": "https://target.example/",
      "@type": "http://www.w3.org/2001/XMLSchema#anyURI"
    }
  ]
}

I think most people would agree that the latter is more confusing than
the former. I am asking the mailing lists to provide feedback that
confirms or denies this.

PROPOSAL: For activitystreams issue 595, the correct resolution is to
amend the vocabulary document to clarify that the range of "href" is a
reference, not xsd:anyURI.

Please respond to this mailing list thread, and/or to the GitHub issue
provided as context. When consensus is reached, we can errata
AS2-Vocab.

Received on Monday, 20 April 2026 01:00:12 UTC