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

Merge branch 'tmp2'

Browse Source
This commit is contained in:
Helge
2023-03-01 10:51:26 +01:00
parent 1ed5cc7c6c baaf50325f
commit 3b47627a38
3 changed files with 38 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
namespace/fep.json → feps/assets/fep-2e40/namespace.json
View File
namespace/fep.md → feps/assets/fep-2e40/namespace.md
View File
feps/fep-2e40.md
+38 -38
View File
@@ -23,9 +23,9 @@ This FEP will
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__.
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 focus here is on having a format that is _machine-readable_. Having a standardized format allows various algorithms to be applicable see [Canon] and [LD-API].
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).
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). This format is _human-readable_.
We will refer to the combination of Context and easily accessible documentations for the terms a __Vocabulary__.
@@ -35,7 +35,9 @@ The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL
## The FEP Vocabulary
This FEP creates the file `/namespace/fep.json` with content
We now formalize the process of creating an adding to the FEP Vocabulary. This section formalizes the location of the two files containing the _machine readable_ json-ld context and _human readable_ markdown description. How to add new terms will be discussed in the next section.
This FEP creates the file `/feps/assets/fep-2e40/namespace.json` with content
```json
{
@@ -48,7 +50,7 @@ This FEP creates the file `/namespace/fep.json` with content
}
```
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
A description of this context is contained in `/feps/assets/fep-2e40/namespace.md`. The goal of inclusion of the ActivityStreams context is to increase the chances of most objects having the simple form
```json
{
@@ -57,45 +59,40 @@ A description of this context is contained in `/namespace/fep.md`. The goal of i
}
```
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`.
which is as close as one can get to pure JSON with JSON-LD. These two files 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].
The authors of a new FEP-xxxx following [FEP-a3ed] MAY include a section or sections titled "Create FEP Term: $TERM". The $TERM MUST follow the following rules inspired by 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.
1. The $TERM MUST be indicative of its function. Avoid generic terms such as "myProperty" or "foo".
2. If there are copyright, trademark, or any intellectual property rights concerns, the addition and use MUST be authorized in writing by the intellectual property rights holder under a F/RAND license. Examples include terms that use trademarked brand names, property names that utilize the titles of copyrighted works, and patented technology that would cause the use of the extension to require licensing a patent.
3. Any addition MUST NOT create unreasonable legal, security, moral, or privacy issues that will result in direct harm to others. Examples of unacceptable additions include any containing racist language, technologies used to persecute minority populations, and unconsented pervasive tracking.
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`.
1. Add a new term of the form `fep-xxxx-$TERM` to `/feps/assets/fep-2e40/namespace.json`.
2. Add a description for this term to `/feps/assets/fep-2e40/namespace.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.
The changes to the two files MUST be described in the FEP, and they MUST 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
Instead of defining a new _FEP 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": {
"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.
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. When doing so, the author MUST either provide a reference to the current definition of the object OR write a new definition of the object. If a reference is provided, it should be considered best pratice to quote the reference.
__FIXME__: Find volunteer to do this. An incomplete list of terms to include `as:Public`, `as:senstive`, `ostatus:conversation`.
## Example "Create FEP term: eventSource"
## 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
In [FEP-61ce], I plan to introduce the term `eventSource`. As this will most likely be the first FEP using the herein defined procces, this will lead to `/feps/assets/fep-2e40/namespace.json` being changed to
```json
{
@@ -103,8 +100,8 @@ In [FEP-61ce], I plan to introduce the term `serverSentEvents`. As this will mos
"https://www.w3.org/ns/activitystreams",
{
"fep": "https://www.w3id.org/fep#",
"fep-61ce/serverSentEvents": {
"@id": "fep:fep-61ce/serverSentEvents",
"fep-61ce-eventSource": {
"@id": "fep:fep-61ce-eventSource",
"@type": "@id"
}
}
@@ -114,14 +111,14 @@ In [FEP-61ce], I plan to introduce the term `serverSentEvents`. As this will mos
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.
> The term `eventSource` 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"}
> {"eventSource": "fep-61ce-eventSource"}
> ],
> "type": "Person",
> "id": "https://example.com/client_actor",
@@ -130,7 +127,7 @@ with usage information
> "preferredUsername": "actor",
> "endpoints": {
> "proxyUrl": "https://example.com/client_actor/proxyUrl",
> "serverSentEvents": "https://example.com/client_actor/serverSentEvents"
> "eventSource": "https://example.com/client_actor/eventSource"
> }
> }
> ```
@@ -138,13 +135,13 @@ with usage information
## 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
While the above example is already nice looking, it still has the uglyness of needing to define `eventSource` as `fep-61ce/eventSource`. We will call the process of adding the line
```json
"serverSentEvents": "fep-61ce/serverSentEvents"
"eventSource": "fep-61ce-eventSource"
```
to `/namespace/fep.json` a __promotion to common term__.
to `/feps/assets/fep-2e40/namespace.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.
@@ -152,11 +149,11 @@ Any term elligible for promotion CAN be promoted to a common term by the author
## 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.
We have now introduced a process for the common or primary vocabulary with context in `/feps/assets/fep-2e40/namespace.json` and documentation in `/feps/assets/fep-2e40/namespace.json`. 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.
An author of a FEP MAY include a section titled "Introducing Secondary FEP Vocabulary fep-DOMAIN". Here DOMAIN is a short name representing the domain. Then files `/feps/fep-xxxx/namespace.json` and `/feps/fep-xxxx/namespace.md` can be created. An example of a file of the `@context` file is given below. By including the original `fep` context, one can keep duplication to a minimum. Similarly, the documentation file should only explain the namespace and which additional terms are promoted or overridden. For the documentation of the _fep terms_, one should refer back to the original documentation.
__FIXME__: Find a technical solution to avoid duplication in the markdown.
Furthermore, the author MAY adjust the configuration of [W3-ID] to reflect his changes. All obligations that are MAY during the draft stage will turn into MUST before the FEP can be finalized.
## Example: The barber vocabulary
@@ -167,7 +164,7 @@ The barber community in the FediVerse has decided that, they need a marker if pe
"@context": [
"https://www.w3id.org/fep",
{
"shavesHimself": "fep-ba1b/shavesHimself"
"shavesHimself": "fep-ba1b-shavesHimself"
}
]
}
@@ -175,18 +172,21 @@ The barber community in the FediVerse has decided that, they need a marker if pe
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.
## Acknowledgements
The comments by _aschrijver_ and _trwnh_ on SocialHub have helped me greatly in clarifying and formulating the concepts discussed in this FEP.
## 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
- [Canon] A. Rundgren, B. Jordan, S. Erdtman [RFC 8785 JSON Canonicalization Scheme (JCS)](https://www.rfc-editor.org/rfc/rfc8785), 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
- [JSON-LD] Gregg Kellogg, Pierre-Antoine Champin, Dave Longley [JSON-LD](https://www.w3.org/TR/json-ld/), 2020
- [LD-API] Gregg Kellogg, Pierre-Antoine Champin, Dave Longley [JSON-LD-API](https://www.w3.org/TR/json-ld-api/), 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)