FEP-888d: Using w3id.org/fep as a namespace for extension terms and for FEP documents

Standards Fediverse Enhancement Proposals
, , ,
1

Hello!

This is a discussion thread for the proposed FEP-888d: Using w3id.org/fep as a namespace for extension terms and for FEP documents. Please use this thread to discuss the proposed FEP and any potential problems or improvements that can be addressed.

Summary

In JSON-LD, @id is used to identify nodes. Each node obect should contain an @id, which MUST be an IRI or a compact IRI (including blank node identifiers). It is considered best practice in the linked-data ecosystem to have such IRIs be HTTPS URIs that resolve to a definition of the term being used, and it is desirable to define such terms in a JSON-LD context file that is referenced by its IRI rather than having the full @context object embedded in every single document. ActivityStreams 2.0 and ActivityPub do this with the normative context and namespace provided at https://www.w3.org/ns/activitystreams, but this namespace is not generally open to extensions or to experimental terms.

This FEP therefore proposes using https://w3id.org/fep as a base IRI for the FEP process, allowing sub-namespaces for each FEP, and allowing certain terms to be promoted to a default context once proven broadly useful.

2 Likes
2

I’m reading through it and collecting my comments.

For example, we can consider the definition of “Public” addressing within ActivityPub, represented by the “Public” magic collection. When the normative ActivityStreams 2.0 context is applied, the IRI for this collection may be equivalently expressed as Public, as:Public, or https://www.w3.org/ns/activitystreams#Public.

This statement is untrue, but often made. Due to Public missing from https://www.w3.org/ns/activitystream, only as:Public expands to https://www.w3.org/ns/activitystream#Public. See Public is missing from https://www.w3.org/ns/activitystreams HTML page · Issue #531 · w3c/activitystreams · GitHub.

So please use another example.

		"exampleA": {
			"@id": "fep:9606/exampleA",
			"rdf:comment": "A term with some literal value (string, boolean, number)"
		},

The rdf:comment is invalid. See

An expanded term definition MUST be a map composed of zero or more keys from @id, @reverse, @type, @language, @container, @context, @prefix, @propagate, or @protected. An expanded term definition SHOULD NOT contain any other keys.

in 9.15.1 Expanded term definition.

I would also like to see some rules on naming here. For example, nobody should introduce a term “Twitter” as we do not hold the trademark. I think I adapted from did-core.

Some more thoughts

I currently feel that it would be wise to require examples for each term in the new context and then run:

expanded = json_ld.expand(example)
recompacted = json_ld.compact(expanded, example["@context"]) 

assert recompacted == example

This would guarantee that the new context is valid. Furthermore, these examples will serve to explain the authors thinking. If one uses a build process for FEP documents, one can use this to include the examples in the FEP document.

I actually don’t have a strong preference of this FEP vs FEP-2e40: The FEP Vocabulary Extension Process. Now that I understand what is necessary. Of course, this means that all FEPs introducing Vocabulary terms need to be in the new folder format.

1 Like
3

that doesn’t sound right – the JSON-LD stuff works on the context document at https://www.w3.org/ns/activitystreams.jsonld which does contain Public being defined as as:Public which expands to the full https://www.w3.org/ns/activitystreams#Public

using the playground at JSON-LD Playground with the following document:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "to": "https://www.w3.org/ns/activitystreams#Public",
  "https://www.w3.org/ns/activitystreams#cc": "Public",
  "bcc": "Public",
  "https://www.w3.org/ns/activitystreams#bto": "https://www.w3.org/ns/activitystreams#Public"
}

if you look at the expanded form, you see that the IRI forms do not use the definition from context. they get parsed as a @value and not an @id in the expanded form. when they get compacted down against the same context, the as: is preserved but the actual definition is not. so for some reason, the reference JSON-LD parser being used on the playground does not equate a term with its IRI, neither the full IRI nor the compact IRI:

[
  {
    "https://www.w3.org/ns/activitystreams#bto": [
      {
        "@value": "https://www.w3.org/ns/activitystreams#Public"
      }
    ],
    "https://www.w3.org/ns/activitystreams#bcc": [
      {
        "@id": "Public"
      }
    ],
    "https://www.w3.org/ns/activitystreams#cc": [
      {
        "@value": "Public"
      }
    ],
    "https://www.w3.org/ns/activitystreams#to": [
      {
        "@id": "https://www.w3.org/ns/activitystreams#Public"
      }
    ]
  }
]

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "bcc": "Public", // linked node
  "as:bto": "https://www.w3.org/ns/activitystreams#Public", // string literal
  "as:cc": "Public", // string literal
  "to": "as:Public" // linked node
}

the activitypub spec gives this hint:

5.6 Note:
Compacting an ActivityStreams object using the ActivityStreams JSON-LD context might result in https://www.w3.org/ns/activitystreams#Public being represented as simply Public or as:Public which are valid representations of the Public collection. Implementations which treat ActivityStreams objects as simply JSON rather than converting an incoming activity over to a local context using JSON-LD tooling should be aware of this and should be prepared to accept all three representations.

it’s not invalid, it’s just not recommended by the JSON-LD spec. i’m not super invested in having this included though, so i can take it out. i can replace this bit with a link to 9.15.1 Expanded Term Definitions in JSON-LD 1.1 in the absence of any other perspectives.

i’m unsure this is necessary. i understand the reasoning behind it, but it can be useful to use such terms. for example, in the discussion around payment links, it came up that you may want to differentiate between Paypal, Cashapp, etc. without parsing every single href for a prefix. i am not sure what legal requirements may surround something like this

not necessarily. we could set up the redirect rules for the old format as present in the commented out lines. having the new folder format just makes it easier.

4

https://www.w3.org/ns/activitystreams#Public is completely broken

Click on the link and you get an HTML documentation. It’s pretending to be a linked data vocabulary, but actually it’s not. It’s just a documentation page.

Public is in the context but not in the human readable docs.

AFAIK was all done without change control, so the spec, the “vocab”, and context have diverged, due to human error, there’s no new version number of the spec, and not at all clear how to fix it.

The elephant in the room is that Activity Streams 2.0 is not a linked data vocab, and never has been.

5

@melvincarvalho What would be necessary to make it a “linked data vocab”? Is the context document at https://www.w3.org/ns/activitystreams(.jsonld) not enough?

6

Creating a Linked Data vocabulary involves defining a set of terms and their relationships in a machine-readable format, typically using RDF. This allows you to create a structured and interoperable way to represent information on the web.

The important thing is that the vocab (aka ontology) is both human and machine readable. Right now the AS Vocab is only human readable.

You can test this on unix systems with the command:

rapper -g https://www.w3.org/ns/activitystreams
7

A note on:

https://www.w3.org/ns/activitystreams.jsonld

This is a context, not a vocabulary. I think that is the thing that has confused everybody. They are different things. A context is syntactic sugar that goes in a JSON-LD file to help you save typing out of full urls and datatypes. Generally it can be inline, or linked.

Similarly

rapper -g https://www.w3.org/ns/activitystreams.jsonld

Thows an error

Compare with:

rapper -g http://www.w3.org/2000/01/rdf-schema

This gives back a vocabulary

8

You are right, I was misremembering details. I’ll reply to the other stuff later, once I have the energy to properly review it.

9

after playing around a bit more, i managed to get this:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "https://www.w3.org/ns/activitystreams#to": {"id": "https://www.w3.org/ns/activitystreams#Public"},
  "cc": "https://www.w3.org/ns/activitystreams#Public"
}

to compact to this:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "cc": "as:Public",
  "to": "as:Public"
}

further expansion or compaction doesn’t result in Public no matter what i do, only as:Public.

10

This FEP is incorrectly named. It should be 361d

See: Woodpecker

11

oh, huh, i must’ve renamed it at some point and forgotten to recalculate the slug. i don’t remember exactly what i did three months ago, so i’ll fix it when i next update the proposal.

speaking of updates: i am thinking of removing the bit about “promoting terms to a common FEP context”, as there was a good point brought up about the danger of such an “FEP context” becoming a second normative thing that people don’t fully understand but cargo-cult anyway. this can still be done as a separate dedicated FEP, but it is also a4ed-adjacent, so i’d rather leave it out of this one and move forward with the immediately-useful parts. i’d also rather have such “common contexts” be handled by dedicated FEPs that define conformance profiles, not as something pushed for by the FEP process itself, as i do not believe there is one contiguous “fediverse” that would benefit from having more authority or normativity.

also, the following paragraph:

To facilitate ease of mapping, any files related to FEPs SHOULD be placed within an fep directory within the repository, and FEP-specific files SHOULD be placed within an FEP-specific subdirectory created according to the FEP identifier. [[TODO: is this language necessary to explicitly include?]]

is no longer necessary given that the described procedure was already adopted outside of this FEP.

similarly:

# uncaught:
# - legacy route for assets, e.g. fep/xxxx/assets/file.ext => feps/assets/fep-xxxx/file.ext

is no longer a concern, as the asset colocation adopted should allow resolving such assets naturally. likewise, the alternative routings are no longer necessary or valid, so the whole .htaccess example code block can be simplified significantly.

finally, the bits about extra metadata like rdf:comment in context documents can probably be removed.

EDIT: #116 - update 9606 -> 888d - fep - Codeberg.org contains these changes.

2 Likes
12

What can be done to move this FEP forward? What to do with alternative proposals (FEP-cb76, FEP-2e40)?

The directory structure has stabilized and some FEPs now provide the context file (e.g. FEP-c390 context).

(Aside: I just updated the top-level post and the topic name with the new slug)

13

For FEP-888d I would like to request any comments on blockers, objections, etc. – for example, are there any mappings that one would expect to work, that don’t currently work?

The .htaccess is below for convenience (some changes as I test them):

Header set Access-Control-Allow-Origin *
Header set Access-Control-Allow-Headers DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified$
Options +FollowSymLinks
RewriteEngine on

# catch FEP-specific context requests
RewriteCond %{HTTP_ACCEPT} application/ld\+json
RewriteRule ^([A-Za-z0-9]+)\/?(.*?)?$ https://codeberg.org/fediverse/fep/src/branch/main/fep/$1/context.jsonld [R=302,L]

# catch FEP-specific context requests without content negotiation
RewriteRule ^([A-Za-z0-9]+).jsonld$ https://codeberg.org/fediverse/fep/src/branch/main/fep/$1/context.jsonld [R=302,L]

# catch FEP proposal documents
RewriteRule ^([A-Za-z0-9]+)\/?$ https://codeberg.org/fediverse/fep/src/branch/main/fep/$1/fep-$1.md [R=302,L]

# a generic catch-all rule
RewriteRule ^(.*)\/?$ https://codeberg.org/fediverse/fep/src/branch/main/fep/$1 [R=302,L]

I’m currently trying to put together some test cases in Python and have the following mappings:

{
  "fep": "http://localhost/fep/",  # this redirects twice basically, due to a quirk of apache
  "fep/": "https://codeberg.org/fediverse/fep/src/branch/main/fep/",
  "fep/xxxx": "https://codeberg.org/fediverse/fep/src/branch/main/fep/xxxx/fep-xxxx.md",
  "fep/xxxx/": "https://codeberg.org/fediverse/fep/src/branch/main/fep/xxxx/fep-xxxx.md",
  "fep/xxxx.jsonld": "https://codeberg.org/fediverse/fep/src/branch/main/fep/xxxx/context.jsonld",
  "fep/xxxx/asset.jpg": "https://codeberg.org/fediverse/fep/src/branch/main/fep/xxxx/asset.jpg"
}

This should support both IRIs of the form https://w3id.org/fep/xxxx/someTerm (to be defined in a plaintext file/asset, ideally) as well as IRIs of the form https://w3id.org/fep/xxxx#someTerm (to be defined ideally under a section of the FEP’s markdown file given an anchor of #someTerm). Furthermore, it supports importing FEPs singularly, as well as submitting an FEP that imports from other FEPs into its own context.jsonld

If there are no comments, changes, objections, etc. then I will update the FEP with the final .htaccess and request finalization. If/when the FEP goes FINAL, I will submit the PR to the w3id PURL service’s Github repo.

The intended way to define context.jsonld is explained in this FEP but if there are any clarifications or points of confusion, I can clarify those as well. See FEP-bad1 or FEP-a070 for examples

The option also remains open for anyone to use their own namespaces – see for example FEP-c648 which uses https://purl.archive.org/socialweb/blocked#blocked but could also potentially provide its own context.jsonld which would allow using https://w3id.org/fep/c648 to resolve and define like so:

{
  "@context": {
    "blocked": {
      "@id": "https://purl.archive.org/socialweb/blocked#blocked",
      "@type": "@id"
  }
}
14

The URL in this rule points to a HTML page. For example:

https://codeberg.org/fediverse/fep/src/branch/main/fep/bad1/context.jsonld

Shouldn’t it point to “raw” file instead?

https://codeberg.org/fediverse/fep/raw/branch/main/fep/bad1/context.jsonld

There’s a section called “Defining terms associated with an FEP”, but it doesn’t specify the file name (I assume FEP authors should always use context.jsonld ?)

The subsequent section “Example” still uses 9606 in context example and accompanying text.

The context example itself looks clear enough to me. I will update FEP-c390 context.jsonld accordingly.

exampleB is a term that links to another node

Is it acceptable to say “object” here instead of “node”? I think this will make it more accessible to people who are not familiar with JSON-LD.

15

#158 - WIP: Update FEP-888d - fep - Codeberg.org addresses the points you raised. Good catches!

PR still marked as draft because I am not 100% confident in my regex, so if anyone has a better grasp of regex than me, feel free to try to break them or otherwise simplify the .htaccess rewrite rules. If not, I will remove the WIP from it.

1 Like