mirror of
https://codeberg.org/fediverse/fep.git
synced 2026-08-05 19:55:46 +00:00
FEP-1570: The FEP Ontology Process (#61)
Regarding: > It is the task of the editors of the FEP process to ensure that the W3ID repository is configured properly to deliver this file on a request with accept type application/ld+json to https://www.w3id.org/fep. I plan on opening an appropriate pull request to the repository https://github.com/perma-id/w3id.org/ myself. I however want to mention that questions in the future should be directed to the Editors listed on https://codeberg.org/fediverse/fep/src/branch/main/EDITORS.md. Co-authored-by: Helge <helge.krueger@gmail.com> Reviewed-on: https://codeberg.org/fediverse/fep/pulls/61 Tracking-issue: https://codeberg.org/fediverse/fep/issues/62 Co-authored-by: helge <helge@noreply.codeberg.org> Co-committed-by: helge <helge@noreply.codeberg.org>
This commit is contained in:
helge
Arnold Schrijver
@@ -0,0 +1,170 @@
|
||||
---
|
||||
authors: Helge Krueger <helge.krueger@gmail.com>
|
||||
status: DRAFT
|
||||
dateReceived: 2023-02-XX
|
||||
---
|
||||
# FEP-1570: The FEP Ontology Process
|
||||
|
||||
## Summary
|
||||
|
||||
Current usage of ActivityPub relies on the ActivityStreams namespace [AS NS]
|
||||
combined with custom extensions [Mastodon NS]. As far as I can tell, no
|
||||
best practices exist or a formal process to add new namespaces.
|
||||
|
||||
This FEP will remedy this by
|
||||
|
||||
- Defining a process to create new FEP namespaces
|
||||
- Defining a process to add new entries to these FEP namespaces
|
||||
- Using this process to create a new FEP namespace
|
||||
- Using [FEP-61CE] as an example how the second process can be used.
|
||||
|
||||
## Background and Terminology
|
||||
|
||||
The JSON-LD context is introduced in [Section 3.1](https://www.w3.org/TR/json-ld/#the-context) of [JSON-LD]. The context of an object is specified by its `@context` property. This context is used to give semantic meaning to the other properties of the object.
|
||||
|
||||
[ActivityPub] relies on the JSON-LD context defined in [AS NS]. This means that ActivityPub objects usually have either the form:
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://www.w3.org/ns/activitystreams",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
if the ontology provided by [AS NS] is sufficient. Alternatively a construction such as
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": [
|
||||
"https://www.w3.org/ns/activitystreams",
|
||||
{
|
||||
"toot": "http://joinmastodon.org/ns#",
|
||||
"featured": {
|
||||
"@id": "toot:featured",
|
||||
"@type": "@id"
|
||||
}
|
||||
}
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
from [Mastodon NS] is used. This document will provide a way to centralize the `@context` objects corresponding to new entries created via [FEP-a4ed]. The goal is that enhancements using the FEP process lead to the simple `@context`
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": [
|
||||
"https://www.w3.org/ns/activitystreams",
|
||||
"https://www.w3id.org/fep",
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
if general terms are used or
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": [
|
||||
"https://www.w3.org/ns/activitystreams",
|
||||
"https://www.w3id.org/fep",
|
||||
"https://www.w3id.org/fep-special",
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
if the terms are only applicable in special cases.
|
||||
|
||||
## Requirements
|
||||
|
||||
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this specification are to be interpreted as described in [RFC-2119].
|
||||
|
||||
## Process to create a new FEP namespace
|
||||
|
||||
The authors of a FEP following [FEP-a3ed] MAY include a section titled "Create FEP namespace: $NAMESPACE_NAME". The variable $NAMESPACE_NAME MUST either be
|
||||
|
||||
- the string "fep"
|
||||
- a string starting with "fep-"
|
||||
|
||||
The section "Create FEP namespace: ..." MUST contain a description of the usage of this new namespace. See Section "Create FEP namespace: fep" for an example.
|
||||
|
||||
The pull request for the FEP SHOULD include a namespace file in the `/namespace` folder of the code repository. For this document this will be
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": {
|
||||
"@vocab": "_:",
|
||||
"fep": "https://www.w3id.org/fep#"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
in `/namespace/fep.json`. It is the task of the editors of the FEP process to ensure that the W3ID repository is configured properly to deliver this file on a request with accept type `application/ld+json` to `https://www.w3id.org/fep`.
|
||||
|
||||
Furthermore, the description of the namespace SHOULD be added as a file `/namespace/fep.md`, which is used to answer queries to `https://www.w3id.org/fep` with a text accept type.
|
||||
|
||||
## Process to add a new term to a FEP namespace
|
||||
|
||||
The authors of a FEP following [FEP-a3ed] MAY include a section or sections titled "Create FEP namespace term: $TERM" or "Create FEP namespace terms: $TERMS". The terms must be strings starting with a valid FEP namespace identifier followed by a colon.
|
||||
|
||||
For each introduced term, the section MUST provide a definition of the term and a description of its use. These definitions SHOULD then be included in the approbriate JSON and Markdown files in the namespace directory.
|
||||
|
||||
To keep the naming consistent with [ActivityPub] terms describing a property should be named using camel case starting with a lowercase letter. The names of types should be in camel case, starting with an uppercase letter.
|
||||
|
||||
## Create FEP namespace: fep
|
||||
|
||||
The namespace `fep` is to be used as a common namespace accross FEPs. It SHOULD be used for properties that are expected to be used by a wider variety of Fediverse applications and not for domain specific terms.
|
||||
|
||||
## Example "Create FEP namespace term: fep:serverSentEvents"
|
||||
|
||||
In [FEP-61ce], I plan to introduce the term `fep:serverSendEvents` with the definition
|
||||
|
||||
```json
|
||||
"serverSideEvents": {
|
||||
"@id": "fep:serverSideEvents",
|
||||
"@type": "@id"
|
||||
}
|
||||
```
|
||||
|
||||
with usage information
|
||||
|
||||
> The term `serverSideEvents` is to be as part of the `endpoints` of an [ActivityPub] Actor. It specifies an endpoint, where the Client can receive push notifications using the Server Side Events protocol of activities being added to collections on the server. By default the inbox collection of the Actor is used. By specifying the `X-ActivityPub-Collection` header once or multiple times a custom list of collections can be set to receive push notifications from.
|
||||
>
|
||||
> Example usage:
|
||||
>
|
||||
> ```json
|
||||
> {
|
||||
> "@context": ["https://www.w3.org/ns/activitystreams",
|
||||
> "https://www.w3id.org/fep"],
|
||||
> "type": "Person",
|
||||
> "id": "https://example.com/client_actor",
|
||||
> "inbox": "https://example.com/client_actor/inbox",
|
||||
> "outbox": "https://example.com/client_actor/outbox",
|
||||
> "preferredUsername": "actor",
|
||||
> "endpoints": {
|
||||
> "proxyUrl": "https://example.com/client_actor/proxyUrl",
|
||||
> "serverSideEvents": "https://example.com/client_actor/serverSideEvents"
|
||||
> }
|
||||
> }
|
||||
> ```
|
||||
>
|
||||
|
||||
## References
|
||||
|
||||
- [ActivityPub] Christine Lemmer Webber, Jessica Tallon, [ActivityPub](https://www.w3.org/TR/activitypub/), 2018
|
||||
- [AS NS] Amy Guy [ActivityStreams 2.0 Terms](https://www.w3.org/ns/activitystreams), 2018
|
||||
- [FEP-a4ed] pukkamustard [FEP-a4ed: The Fediverse Enhancement Proposal Process](https://codeberg.org/fediverse/fep/src/branch/main/feps/fep-a4ed.md)
|
||||
- [FEP-61ce] Helge Krueger [FEP-61CE: Server Sent Events for Actor], in preparation
|
||||
- [JSON-LD] Gregg Kellogg,
|
||||
Pierre-Antoine Champin,
|
||||
Dave Longley
|
||||
[JSON-LD](https://www.w3.org/TR/json-ld/), 2020
|
||||
- [Mastodon NS] Eugen Rochko et al [JSON-LD Namespacing](https://docs.joinmastodon.org/spec/activitypub/#namespaces)
|
||||
- [RFC-2119] S. Bradner, [Key words for use in RFCs to Indicate Requirement Levels](https://tools.ietf.org/html/rfc2119.html)
|
||||
|
||||
## Copyright
|
||||
|
||||
CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
|
||||
|
||||
To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"@context": {
|
||||
"@vocab": "_:",
|
||||
"fep": "https://www.w3id.org/fep#"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
# fep
|
||||
|
||||
The namespace fep is to be used as a common namespace accross FEPs. It SHOULD be used for properties that are expected to be used by a wider variety of Fediverse applications and not for domain specific terms.
|
||||
Reference in New Issue
Block a user