mirrors/fep
1
0
Fork 0
mirror of https://codeberg.org/fediverse/fep.git synced 2026-08-05 19:55:46 +00:00
Code Packages Wiki Activity

Update to FEP-1570 (#63)

Browse Source 
Reworked the draft to take into account some comments from

https://socialhub.activitypub.rocks/t/fep-1570-the-fep-ontology-process/2972

In particular, the FEP has been renamed from "The FEP Ontology Process"
to "The FEP Vocabulary Extension Process". A new format for the
introduced terms has been used with "fep-xxxx/term". Finally,
the process of secondary Vocabularies has been modified.

The FIXME in the document can currently be best resolved via community input; one is even seeking a volunteer.

Co-authored-by: Helge <helge.krueger@gmail.com>
Reviewed-on: https://codeberg.org/fediverse/fep/pulls/63
Co-authored-by: helge <helge@noreply.codeberg.org>
Co-committed-by: helge <helge@noreply.codeberg.org>
This commit is contained in:
helge
2023-02-19 20:41:44 +00:00
committed by David Sterry
parent 5fd67b3bc1
commit 89c1f92c6f
5 changed files with 220 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1 -1
View File
@@ -24,7 +24,7 @@ A Fediverse Enhancement Proposal (FEP) is a document that provides information t
| [FEP-cb76: Content Addressed Vocabulary](./feps/fep-cb76.md) | `DRAFT` | [#41](https://codeberg.org/fediverse/fep/issues/41) | 2022-11-29 | - |
| [FEP-fb2a: Actor metadata](./feps/fep-fb2a.md) | `DRAFT` | [#45](https://codeberg.org/fediverse/fep/issues/45) | 2022-12-09 | - |
| [FEP-c118: Content licensing support](./feps/fep-c118.md) | `DRAFT` | [#57](https://codeberg.org/fediverse/fep/issues/57) | 2023-01-16 | - |
| [FEP-1570: The FEP Ontology Process](./feps/fep-1570.md) | `DRAFT` | [#62](https://codeberg.org/fediverse/fep/issues/62) | 2023-02-13 | - |
| [FEP-2e40: The FEP Vocabulary Extension Process](./feps/fep-2e40.md) | `DRAFT` | [#62](https://codeberg.org/fediverse/fep/issues/62) | 2023-02-13 | - |
# Submitting a FEP
feps/fep-1570.md
-170
View File
@@ -1,170 +0,0 @@
---
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.
feps/fep-2e40.md
+198
View File
@@ -0,0 +1,198 @@
---
authors: Helge Krueger <helge.krueger@gmail.com>
status: DRAFT
dateReceived: 2023-02-13
---
# FEP-2e40: The FEP Vocabulary Extension 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
- Create a FEP Vocabulary based on identified best practices
- Define a process to add new entries to this FEP Vocabulary without a risk of Term collision
- Define a process to elevate Terms to be common
- Define a process to create specialized Vocabularies
- Using [FEP-61CE] as an example how this process can be used.
## Background and Terminology
The JSON-LD context is introduced in [3.1 The Context](https://www.w3.org/TR/json-ld/#the-context) of [JSON-LD]. The context of an object is specified by its `@context` property.
One can think of the context as defining certain strings to be equivalent. For example `Note`, `as:Note`, and `https://www.w3.org/ns/activitystreams#Note` all represent the same thing. More details can be found in [3.2. IRIs](https://www.w3.org/TR/json-ld/#iris). Following [JSON-LD], we will refer to all three strings mentioned above as a __Term__.
The second useful aspect of this is that one can define the used terms through the provided URL: [https://www.w3.org/ns/activitystreams#Note](https://www.w3.org/ns/activitystreams#Note). Clicking on it will let you easily find the definiton of the [Note Type](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-note).
We will refer to the combination of Context and easily accessible documentations for the terms a __Vocabulary__.
## 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].
## The FEP Vocabulary
This FEP creates the file `/namespace/fep.json` with content
```json
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"fep": "https://w3id.org/fep#"
}
]
}
```
A description of this context is contained in `/namespace/fep.md`. The goal of inclusion of the ActivityStreams context is to increase the chances of most objects having the simple form
```json
{
"@context": "https://w3id.org/fep",
...
}
```
which is as close as one can get to pure JSON with JSON-LD. These two files fill form the __FEP Vocabulary__. Through a pull-request to [W3-ID], these two files will be made available at `https://w3id.org/fep`.
## Process to add a new Term to the FEP Vocabulary
The authors of FEP-xxxx following [FEP-a3ed] MAY include a section or sections titled "Create FEP Term: $TERM". The $TERM MUST follow points 2-5 of [3. The Registration Process](https://www.w3.org/TR/did-spec-registries/#the-registration-process) in [DID-Reg].
__FIXME__: Include the rules here.
Furthermore, the author MAY perform the following action
1. Add a new term of the form `fep-xxxx/$TERM` to `/namespace/fep.json`.
2. Add a description for this term to `/namespace/fep.md`.
The changes to the two files MUST be described in the FEP, and they may only add new content or change content added by the FEP.
An example is provided in the next section. While these actions are optional at the DRAFT stage of a FEP, they MUST be performed before a FEP can reach its FINAL stage. We will refer to a term introduced by this process as a __FEP term__.
Instead of having many sections with similar names, the author of a FEP MAY combine them.
__FIXME__: Check the following actually is valid JSON-LD:
__FIXME__: Document requirements on new documentation vs reusing existing documentation.
Instead of defining a new Term, the author of a FEP MAY decide to include terms from another namespace as a FEP Term. For example, we decide to introduce `conversation` as follows
```json
"fep:fep-xxxx/conversation": {
"@id": "http://ostatus.org#conversation",
"@type": "@id"
},
"fep-xxxx/conversation": "fep:fep-xxxx/conversation"
```
This has the advantage that terms, which are currently used but not properly documented, can be given a proper definition. Furthermore, this will help keep the `@context` block small.
__FIXME__: Find volunteer to do this. An incomplete list of terms to include `as:Public`, `as:senstive`, `ostatus:conversation`.
## Example "Create FEP term: serverSentEvents"
In [FEP-61ce], I plan to introduce the term `serverSentEvents`. As this will most likely be the first FEP using the herein defined procces, this will lead to `/namespace/fep.json` being changed to
```json
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"fep": "https://www.w3id.org/fep#",
"fep-61ce/serverSentEvents": {
"@id": "fep:fep-61ce/serverSentEvents",
"@type": "@id"
}
}
]
}
```
with usage information
> The term `serverSentEvents` 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 a different collection can be specified to retrieve push notifications from.
>
> Example usage:
>
> ```json
> {
> "@context": ["https://www.w3id.org/fep",
> {"serverSentEvents": "fep-61ce/serverSentEvents"}
> ],
> "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",
> "serverSentEvents": "https://example.com/client_actor/serverSentEvents"
> }
> }
> ```
>
## Promotion to common terms
While the above example is already nice looking, it still has the uglyness of needing to define `serverSentEvents` as `fep-61ce/serverSentEvents`. We will call the process of adding the line
```json
"serverSentEvents": "fep-61ce/serverSentEvents"
```
to `/namespace/fep.json` a __promotion to common term__.
In order to be elligible for promotion, a term MUST NOT conflict with any term currently in the vocabulary. For example, if the term `visualization` was already introduced in a previous FEP, it is not acceptable to introduce `visualisation` and expect promotion of this term.
Any term elligible for promotion CAN be promoted to a common term by the author of the FEP after the FEP has been declared FINAL. If an author does not seek to promotion of a term, it SHOULD be noted in the section introducing this term.
## Secondary FEP Vocabularies
We have now introduced a process for the common or primary vocabulary with context in `/namespace/fep.json` and documentation in `/namespace/fep.md`. We will now introduce _secondary vocabularies_. These are meant to be an option to introduce many domain specific terms without having to add them to the primary vocabulary.
An author of a FEP MAY include a section titled "Introducing Secondary FEP Vocubalary fep-DOMAIN". Here DOMAIN is a short name representing the domain. Then files `/namespace/fep-domain.json` and `/namespace/fep-domain.md` can be created. These should only differ from the primary files in the list of promoted terms.
__FIXME__: Find a technical solution to avoid duplication in the markdown.
## Example: The barber vocabulary
The barber community in the FediVerse has decided that, they need a marker if people shave themself. So they have introduce FEP-ba1b and defined the term `shavesHimself`. It was decided not to promote this term to the primary vocabulary. Instead the barber community has decided to introduce FEP-ba2b, in which they introduce the secondary FEP vocabulary `fep-barber`. The context of this vocabulary then takes the form:
```json
{
"@context": [
"https://www.w3id.org/fep",
{
"shavesHimself": "fep-ba1b/shavesHimself"
}
]
}
```
By including the primary FEP vocabulary, it is ensured that changes to the primary vocabulary carry over to the secondary `fep-barber` vocabulary. Furthermore, by the promotion of `shavesHimself` taking place after the inclusion of the primary vocabulary, it is ensure that the primary vocabulary cannot override it.
## 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
- [AS-Git] M. Sporny [Add alsoKnownAs property to AS vocabulary #511](https://github.com/w3c/activitystreams/issues/511), 2020
- [DID Reg] Orie Steele, Manu Sporny [DID Specification Registries](https://www.w3.org/TR/did-spec-registries), 2023
- [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)
- [W3-ID] Contibutors [Permanent Identifiers for the Web](https://github.com/perma-id/w3id.org)
## 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.
namespace/fep.json
+6 -4
View File
@@ -1,6 +1,8 @@
{
"@context": {
"@vocab": "_:",
"fep": "https://www.w3id.org/fep#"
}
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"fep": "https://w3id.org/fep#"
}
]
}
namespace/fep.md
+15 -2
View File
@@ -1,3 +1,16 @@
# fep
# The FEP Vocabulary
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.
This file contains the description of Terms of the FEP Vocabulary. The FEP Vocabulary is defined according to [FEP-2e40]. The FEP Vocabulary is an extension of [Activity Streams 2.0](https://www.w3.org/ns/activitystreams), which is described in [AS-NS].
## Promoted terms
The following terms have been elevated to be usable without their fep prefix.
## Definitions of Terms
This section contains the definition of terms separated by FEP.
## References
- [AS-NS] Amy Guy [ActivityStreams 2.0 Terms](https://www.w3.org/ns/activitystreams), 2018
- [FEP-2e40] Helge Krueger [FEP-2e40: The FEP Vocabulary Extension Process](https://codeberg.org/fediverse/fep/src/branch/main/feps/fep-2e40.md), 2023