it might be a good idea to read the json-ld specification too, since the activitystreams 2 is based on json-ld
the short summary is that json-ld is about “linked data” – basically, json documents can refer to other json documents by their id. the json-ld parser is like a normal json parser, but it can fetch other documents and construct a graph.
when working with json-ld, you have two main algorithms to consider: expansion and compaction. consider the following example from the playground:
{
"@context": "http://schema.org/",
"@type": "Person",
"name": "Jane Doe",
"jobTitle": "Professor",
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com"
}
- expansion uses the
@context
definitions to turn all property names and any @value
of @type
= @id
into a fully qualified URI.
the example above expands to the following (in other words, it is equivalent):
[
{
"@type": [
"http://schema.org/Person"
],
"http://schema.org/jobTitle": [
{
"@value": "Professor"
}
],
"http://schema.org/name": [
{
"@value": "Jane Doe"
}
],
"http://schema.org/telephone": [
{
"@value": "(425) 123-4567"
}
],
"http://schema.org/url": [
{
"@id": "http://www.janedoe.com"
}
]
}
]
this expanded form is an array of every node in the document. this document has 1 node, which contains an array of every property in standard json-ld notation, which includes some defined keys such as @id
, @type
, @value
, etc.
- compaction uses the expanded form and the associated
@context
definition to shorten any IRIs and inline the context back into the json-ld document.
the example above compacts to the following and is once again equivalent:
{
"@context": "http://schema.org/",
"type": "Person",
"jobTitle": "Professor",
"name": "Jane Doe",
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com"
}
when this processing is done, the @context
is parsed for any IRIs which are fetched and then added to the overall context. you can also include context definitions inline, and the most recent definition is used.
yes, the separator for a namespace and its property is :
, and this is because it needs to be distinct from a URL. remember, name
= http://schema.org/name
in this example, because we are using the schema.org namespace. but you probably know that activitystreams also has a name
property with a different semantic meaning. what happens when we use two/multiple different contexts?
{
"@context": ["http://schema.org/", "https://www.w3.org/ns/activitystreams"],
"type": "Person",
"jobTitle": "Professor",
"name": "Jane Doe",
"telephone": "(425) 123-4567",
"url": "http://www.janedoe.com"
}
well, this is one possible compaction:
{
"@context": "http://schema.org/",
"type": "https://www.w3.org/ns/activitystreams#Person",
"jobTitle": "Professor",
"telephone": "(425) 123-4567",
"https://www.w3.org/ns/activitystreams#name": "Jane Doe",
"https://www.w3.org/ns/activitystreams#url": {
"id": "http://www.janedoe.com"
}
}
notice that name
andurl
are no longer in their short form. neither is the type value of Person
. this is because compaction is done against a developer-provided context, and the json-ld playground seems to just use the first value of the sample’s context. if it was compacted against the context array, then these IRIs would be transformed back to their short forms.
now, suppose you needed to use two properties with the same short name. you could do that with compact namespacing or expanded namespacing. we can use the already-defined schema
= https://schema.org/
and we can use the already-defined as
= https://www.w3.org/ns/activitystreams#
as the base URIs.
...
"@type": ["as:Person", "schema:Person"],
...
remember, the equivalent would be like so:
...
"@type": ["https://www.w3.org/ns/activitystreams#Person", "http://schema.org/Person"],
...
with respect to id assignment, ActivityPub specifies that ids must be assigned
with their authority belonging to that of their originating server
so no, it is not just a name, it is an unique identifier on your domain that is meant to be fetched later for verification or other purposes. if id is not provided or is null
, then it is an anonymous or transient object:
Identifiers MUST be provided for activities posted in server to server communication, unless the activity is intentionally transient […] in which case the id
MAY be omitted