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

[tesaguri]

@trwnh

Off the top of my head, this seems to be what application/ld+json; profile="http://www.w3.org/ns/json-ld#context" is intended to solve… but I am unsure of how the wider JSON-LD ecosystem handles or fails to handle that profile parameter. It feels like potentially fragile behavior to say that the requester must specifically request the context profile and not just jsonld. But I could be wrong, this might actually be the correct intended solution.

Is your idea to return a context document when requested the http://www.w3.org/ns/json-ld#context profile and return an ontology document otherwise? If so, I think that works if the top-level @context of the ontology is a superset of the context document, since the JSON-LD Processing Algorithms set the loaded context value to the top-level @context value of the loaded document and ignores the rest of it when dereferencing remote context documents IIUC, so that it would only result in a slight waste of network bandwidth even when the client forgets to include the http://www.w3.org/ns/json-ld#context profile in the Accept request header.

But the situation might get subtler if the @context of the ontology has a term definition that’s not in the context document and that term overrides a term from another context document fetched by the client. To avoid such a conflict, the top-level @context of the ontology should be identical to that of the context document, but that means that you wouldn’t be able to use short-hand terms for ontology-specific vocabularies (at least at the top-level map), leading to less human-readable ontologies.

[trwnh]

@tesaguri

the JSON-LD Processing Algorithms set the loaded context value to the top-level @context value of the loaded document and ignores the rest of it when dereferencing remote context documents IIUC

I think this implies that you could serve a JSON-LD document with two keys, @context containing the intended context document for people who want to just to use the context definitions, and @graph containing the schema/ontology… but with the caveat that the @graph probably ends up having to use full IRIs. Which doesn’t seem like a real issue, considering that anyone intending to do schema/ontology stuff probably is LD-aware and knows what they’re getting themselves into.

For example, in an in-progress update to FEP-0499 I have the following contents included in a file fep-0499.jsonld which is a combination of context.jsonld as well as the RDF Schema converted into JSON-LD:

{
  "@context": {
    "multibox": {
      "@id": "https://w3id.org/fep/0499/multibox",
      "@type": "@id"
    }
  },
  "@graph": [
    {
      "@id": "https://w3id.org/fep/0499/multibox",
      "@type": "http://www.w3.org/1999/02/22-rdf-syntax-ns#Property",
      "http://www.w3.org/2000/01/rdf-schema#comment": {
        "@language": "en",
        "@value": "An optional endpoint used for wide delivery of activities to multiple inboxes."
      },
      "http://www.w3.org/2000/01/rdf-schema#isDefinedBy": {
        "@id": "https://w3id.org/fep/0499/multibox"
      },
      "http://www.w3.org/2000/01/rdf-schema#label": {
        "@language": "en",
        "@value": "multibox"
      },
      "http://www.w3.org/2000/01/rdf-schema#seeAlso": {
        "@id": "https://w3id.org/fep/0499"
      }
    }
  ]
}

And the other caveat is that if there are any terms used in your schema @graph that are also present in @context then those will end up compacted/term-mapped. But again, this should be fine and not cause any issues?

I think this would allow fetching like so

GET /fep/xxxx HTTP/1.1
Host: w3id.org
Accept: application/ld+json

No profile parameter required. Actually I think most JSON-LD processors seem to behave this way and will actually not provide the profile param when fetching, so this might end up being the safest approach.

The only thing I have to think about now is how to deal with existing FEPs that already define a context.jsonld and not a fep-xxxx.jsonld. This might end up necessitating some duplication where at minimum, fep-xxxx.jsonld MUST contain at least the exact same @context as context.jsonld

[trwnh]

One other thing I’ve been working on is that I wrote a Python script to auto-generate term definition files based on RDFa embedded directly in the FEP-xxxx.md file. I still need to figure out how to incorporate that into the general FEP workflow, and provide guidance around it.

it doesn’t limit itself to the standard library, is the challenge. it imports markdown, bs4, rdflib and json (and only the last of those is in the standard library i think?)

[codenamedmitri]

Oof, the Solid spec does this (embedded RDFa in the specs). It’s clever and labor saving in one sense… But the tradeoff is that the diffs (and the code itself) is way less readable as a result.

[trwnh]

It’s not a requirement to define your terms with RDFa markup, but I can’t think of a better alternative for anyone who cares about generating schema or ontology stuff. Parsing the Markdown is not feasible without mandating exact heading names, figuring out a way to somehow extract an entire section instead of a loose bundle of h2/h3 and p tags in the rendered Markdown, and a lot more that I haven’t even begun to consider.

If you don’t care about the RDF stuff then you can continue to define your terms in the Markdown without any additional markup. In that case I’d recommend following the existing guidance of having either a header or an HTML element with the given id and then using fragment identifiers for your terms. But I want to make it as easy as possible for people to do that extra work, and “authoring all metadata once” is a very big advantage to RDFa that I can’t overlook.

Regarding readability, it looks something like this for now:

<div id="multibox" resource="https://w3id.org/fep/0499/multibox" typeof="rdf:Property">
<h3>multibox</h3>
<dl>
<dt>URI</dt>
<dd><code>https://w3id.org/fep/0499/multibox</code></dd>
<dt>Label</dt>
<dd property="rdfs:label" lang="en">multibox endpoint</dd>
<dt>Comment</dt>
<dd property="rdfs:comment" lang="en">An optional endpoint used for wide delivery of activities to multiple inboxes. POST an Add activity where the object is at least one activity to be delivered, and the target is at least one inbox to deliver to.</dd>
<dt>Domain</dt>
<dd property="rdfs:domain" resource="https://w3id.org/fep/caca/EndpointMapping">EndpointMapping</dd>
<dt>Range</dt>
<dd property="rdfs:range" resource="rdfs:Resource">The endpoint (@id)</dd>
<dt>Functional</dt>
<dd property="owl:maxCardinality" content="1" datatype="xsd:nonNegativeInteger">Yes</dd>
<dt>Is defined by</dt>
<dd><a property="rdfs:isDefinedBy" href="https://w3id.org/fep/0499">FEP-0499</a></dd>
</dl>
</div>

EDIT: for more about this see this part of the FEP

Markdown specifications such as CommonMark currently do not support custom attributes, but some Markdown processors such as Goldmark support custom attributes on headers (but not on arbitrary elements). See [CM-ATTRS] for more discussion of this feature.

Consistent attribute syntax

If this ever got added (and there’s no timeline for adding it, unfortunately), then you could maybe do something like

## Terms defined

### multibox

<div resource="https://w3id.org/fep/0499/multibox" typeof="rdf:Property">

URI
: `https://w3id.org/fep/0499/multibox`

Label
: multibox endpoint
{property="rdfs:label" lang="en"}

Comment
: An optional endpoint used for wide delivery of activities to multiple inboxes. POST an Add activity where the object is at least one activity to be delivered, and the target is at least one inbox to deliver to.
{property="rdfs:comment" lang="en"}

Domain
: [EndpointMapping](https://w3id.org/fep/caca/EndpointMapping){property="rdfs:domain" }

Range
: The endpoint (`@id`)
{property="rdfs:range" resource="rdfs:Resource"}

Functional
: Yes
{property="owl:maxCardinality" content="1" datatype="xsd:nonNegativeInteger"}

Is defined by
: [FEP-0499](https://w3id.org/fep/0499){property="rdfs:isDefinedBy"}

</div>

This is of course non-standard and will not work. Also the div is still necessary because Markdown renderers generally don’t wrap sections in <section>, which would probably be preferable to a plain old div, or as Markdown defaults to, nothing at all whatsoever.

[trwnh]

@trwnh

The only thing I have to think about now is how to deal with existing FEPs that already define a context.jsonld and not a fep-xxxx.jsonld. This might end up necessitating some duplication where at minimum, fep-xxxx.jsonld MUST contain at least the exact same @context as context.jsonld

[888d] Support machine-readable term definitions, URL hacking, and alternate...

I have concluded that the duplication is indeed necessary for now. Part of this PR involves copying all existing context.jsonld to fep-xxxx.jsonld in preparation for a PR to perma-id/w3id.org on github. After that PR is made and merged, JSON-LD conneg will no longer redirect to context.jsonld, but instead will redirect to fep-xxxx.jsonld.