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 remote-tracking branch 'trwnh/w3id'

Browse Source
This commit is contained in:
Helge
2023-07-01 09:36:24 +02:00
parent caa6a24b67 1c00c71925
commit f00e3b82d5
3 changed files with 12 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1 -1
View File
@@ -30,7 +30,7 @@ The FEP Process is an initiative of the [SocialHub](https://socialhub.activitypu
| [FEP-7888: Demystifying the context property](./fep/7888/fep-7888.md) | `DRAFT` | [#68](https://codeberg.org/fediverse/fep/issues/68) | 2023-03-14 | - |
| [FEP-d767: Extend ActivityPub with Valueflows](./fep/d767/fep-d767.md) | `DRAFT` | [#76](https://codeberg.org/fediverse/fep/issues/76) | 2023-04-02 | - |
| [FEP-5bf0: Collection sorting and filtering](./fep/5bf0/fep-5bf0.md) | `DRAFT` | [#80](https://codeberg.org/fediverse/fep/issues/80) | 2023-04-10 | - |
| [FEP-9606: Using w3id.org/fep as a namespace for extension terms and for FEP documents](./fep/9606/fep-9606.md) | `DRAFT` | [#83](https://codeberg.org/fediverse/fep/issues/83) | 2023-04-11 | - |
| [FEP-888d: Using https://w3id.org/fep as a base for FEP-specific namespaces](./fep/888d/fep-888d.md) | `DRAFT` | [#83](https://codeberg.org/fediverse/fep/issues/83) | 2023-04-11 | - |
| [FEP-0ea0: Payment Links](./fep/0ea0/fep-0ea0.md) | `DRAFT` | [#88](https://codeberg.org/fediverse/fep/issues/88) | 2023-04-18 | - |
| [FEP-612d: Identifying ActivityPub Objects through DNS ](./fep/612d/fep-612d.md) | `DRAFT` | [#89](https://codeberg.org/fediverse/fep/issues/89) | 2023-04-18 | - |
| [FEP-fffd: Proxy Objects](./fep/fffd/fep-fffd.md) | `DRAFT` | [#95](https://codeberg.org/fediverse/fep/issues/95) | 2023-04-29 | - |
fep/9606/fep-9606.md → fep/888d/fep-888d.md
+10 -97
View File
@@ -1,11 +1,11 @@
---
slug: "9606"
slug: "888d"
authors: a <a@trwnh.com>
status: DRAFT
dateReceived: 2023-04-10
---
# FEP-9606: Using w3id.org/fep as a namespace for extension terms and for FEP documents
# FEP-888d: Using https://w3id.org/fep as a base for FEP-specific namespaces
## Summary
@@ -19,7 +19,7 @@ The core idea behind this FEP is attributed to helge on SocialHub [1]. Specifica
## Requirements
The key words "MUST", "SHOULD", "MAY" are to be interpreted as described in [RFC2119].
The key words "MUST", "SHOULD", "MAY" are to be interpreted as described in [RFC-2119].
## Introduction
@@ -27,13 +27,13 @@ The key words "MUST", "SHOULD", "MAY" are to be interpreted as described in [RFC
The Resource Description Framework (RDF), of which JSON-LD is a serialization, uses URIs to identify nodes on a graph, define properties of those nodes, and create relationships between those nodes. Each statement in RDF represents a fact that is constructed by linking a subject to an object with a predicate; for example, in the statement "Alice knows Bob", the subject `Alice` is related to the object `Bob` by the predicate `knows`. To avoid ambiguity, we can specify a URI for what it means to "know" someone. Such a URI represents a named property or named predicate, and it exists within a namespace, often associated with some ontology or vocabulary. ActivityStreams 2.0 provides and defines the Activity Vocabulary at `https://www.w3.org/ns/activitystreams`, and terms defined within may use either the base IRI `https://www.w3.org/ns/activitystreams#` or the compact IRI `as:`.
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`.
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`.
Historically, extension terms within early ActivityPub implementations assumed that those extension terms would be readily adopted within the ActivityStreams namespace, but this did not happen. Currently, terms such as `Hashtag`, `manuallyApprovesFollowers`, `movedTo`, and `sensitive` are manually defined with compact IRIs using the `as:` prefix, in effect making it so that any implementation that wishes to understand these properties and types must manually define those terms as well, in the exact same way.
Later extension terms were defined within vendor-specific namespaces such as `http://joinmastodon.org/ns` or `https://joinpeertube.org/ns`. With the increased adoption of ActivityPub by software projects and the diverse needs of such projects, each project will often define its own vendor-specific namespace to contain its own terms. This has led to a multitude of namespaces and extension terms, which must be cherry-picked as needed by JSON-LD consumers wishing to maintain compatibility. Additionally, some of these terms are defined incorrectly within `@context`, leading to the necessity of compatibility hacks on a per-project basis. Even terms defined correctly may overlap with other terms, and proposed new terms must be parented within a vendor namespace, creating the potential for conflict on which vendor should adopt which term.
The aim of this FEP is to provide a vendor-independent namespace for the entirety of the fediverse, under which extension terms can be defined pursuant to the FEP process and the above problems can be reduced.
The aim of this FEP is to provide a vendor-independent namespace under which extension terms can be defined pursuant to the FEP process and the above problems can be reduced.
## Prior art
@@ -43,7 +43,7 @@ Within the XMPP ecosystem, the core XMPP specification is defined within an RFC,
Within the RDF and linked-data ecosystems, there is a strong preference for HTTP or HTTPS URIs, as these can usually be dereferenced via the HTTP protocol for additional information about the subject of the URI. In cases where the URI does not resolve, the URI serves as an identifier not much different than a URN, but with its authority derived from DNS domain rather than from some organizational authority. The reliance on DNS domain creates an issue where the primary domain associated with a group or organization might change. If a previously-used domain is reassigned to a different party, then the new party can mint URIs that accidentally or intentionally conflict with previously-assigned URIs.
To mitigate the DNS authority reassignment issue, trusted intermediary services can maintain a "persistent URL" (PURL) service, which allows assigning identifiers on the intermediary domain that will redirect to some other URI. This layer of indirection allows changing the location of the resource by simply changing the redirect's target. W3ID is one such service, operated by the W3C Permanent Identifier Community Group and available at w3id.org. At the time of writing this FEP, top-level directory names can be claimed by individuals who submit pull requests to the w3id.org repository on GitHub, and .htaccess files allow redirection based on rewrite rules that transform incoming requests to some other target.
To mitigate the DNS authority reassignment issue, trusted intermediary services can maintain a "persistent URL" (PURL) service, which allows assigning identifiers on the intermediary domain that will redirect to some other URI. This layer of indirection allows changing the location of the resource by simply changing the redirect's target. W3ID is one such service, operated by the W3C Permanent Identifier Community Group and available at <https://w3id.org>. At the time of writing this FEP, top-level directory names can be claimed by individuals who submit pull requests to the w3id.org repository on GitHub, and .htaccess files allow redirection based on rewrite rules that transform incoming requests to some other target.
## Specification
@@ -58,7 +58,6 @@ Broad design goals for the redirect mapping include:
At minimum, the following redirects SHOULD resolve as follows:
- `https://w3id.org/fep`
- `Accept: application/ld+json` => the FEP common context document
- `Accept: *` => the FEP repository or current home page
- `https://w3id.org/fep/(:id)`
- `Accept: application/ld+json` => a specific FEP's context document
@@ -74,55 +73,34 @@ Additionally, the following redirects MAY resolve:
At the time of writing this FEP, the Codeberg repository at `https://codeberg.org/fediverse/fep` is used to host FEP-related files, and can similarly be used to host context documents.
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?]]
#### Example
(This section is non-normative.)
[[TODO: check the exact mapping depending on outcome of discussion and URI schemes agreed upon]]
```perl
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 top-level current JSON-LD context
RewriteCond %{HTTP_ACCEPT} application/ld\+json
RewriteRule ^$ https://codeberg.org/fediverse/fep/src/branch/main/contexts/fep.jsonld [R=302,L]
# catch top-level versioned contexts
RewriteRule ^context-([^/]*)\.jsonld$ https://codeberg.org/fediverse/fep/src/branch/main/contexts/fep-$1.jsonld [R=302,L]
# catch FEP-specific context requests
RewriteCond %{HTTP_ACCEPT} application/ld\+json
RewriteRule ^([^/\.]*)/?(.*?)?/?$ https://codeberg.org/fediverse/fep/src/branch/main/fep/$1/context.jsonld [R=302,L]
# Alternative routing: https://codeberg.org/fediverse/fep/src/branch/main/contexts/fep-$1/context.jsonld [R=302,L]
# Alternative 2: https://codeberg.org/fediverse/fep/src/branch/main/contexts/fep-$1.jsonld [R=302,L]
# catch FEP-specific context requests without content negotiation
RewriteRule ^([^/\.]*)/?(.*?)?.jsonld$ https://codeberg.org/fediverse/fep/src/branch/main/fep/$1/context.jsonld [R=302,L]
# Alternative routing: https://codeberg.org/fediverse/fep/src/branch/main/contexts/fep-$1/context.jsonld [R=302,L]
# catch FEP proposal documents
RewriteRule ^([^/\.]*)/?(.*?)?/?$ https://codeberg.org/fediverse/fep/src/branch/main/fep/$1 [R=302,L]
# Legacy routing: https://codeberg.org/fediverse/fep/src/branch/main/feps/fep-$1.md [R=302,L]
# Alternative routing: https://codeberg.org/fediverse/fep/src/branch/main/fep/$1/index.md [R=302,L]
RewriteRule ^([^/\.]*)/?(.*?)?/?$ 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]
# uncaught:
# - legacy route for assets, e.g. fep/xxxx/assets/file.ext => feps/assets/fep-xxxx/file.ext
```
### Defining terms associated with an FEP
FEPs that wish to define extension terms within the w3id.org/fep namespace MUST provide a context document containing all terms defined by that FEP. The context document MUST include at least an `@id` for each term, with `@type` of `@id` if the term links to another node. The context document MAY include additional metadata. Once the FEP is marked `FINAL`, the context document MAY be cached forever if referenced. FEPs that define extension terms MAY instead define extension terms within a vendor-specific namespace, but generally this SHOULD NOT be done.
Identifiers for each term MUST be of the form `https://w3id.org/fep/(:id)/(:term)`, and ideally SHOULD have their definitions placed in a dedicated term-specific file or page. If this is not done, then term IRIs will resolve to the FEP-specific documents.
#### Example
(This section is non-normative.)
@@ -152,78 +130,13 @@ The context document might look like this, at minimum:
}
```
However, it might alternatively look like this:
```json
{
"@context": {
"xsd": "http://www.w3.org/2001/XMLSchema#",
"rdf": "http://www.w3.org/2000/01/rdf-schema#",
"fep": "https://w3id.org/fep/",
"exampleA": {
"@id": "fep:9606/exampleA",
"rdf:comment": "A term with some literal value (string, boolean, number)"
},
"exampleB": {
"@id": "fep:9606/exampleB",
"@type": "@id",
"rdf:comment": "A term that links to another node"
},
"exampleC": {
"@id": "fep:9606/exampleC",
"@type": "xsd:nonNegativeInteger",
"@container": "@set",
"rdf:comment": "An unordered list of literal values that are specifically non-negative integers"
}
}
}
```
### Maintaining a top-level "fediverse" context document
FEPs that define extension terms MAY request elevation of certain terms to "common" status, and if the FEP reaches `FINAL` status, those terms can be added to a top-level context document that may be imported singularly by "fediverse" implementations. The top-level context document can be generated by merging the term definitions from FEP-specific context documents, and appending the ActivityStreams context.
#### Example
(This section is non-normative.)
If the `exampleC` term above was promoted, then the resulting top-level context document might look like this:
```json
{
"@context": [
{
"xsd": "http://www.w3.org/2001/XMLSchema#",
"rdf": "http://www.w3.org/2000/01/rdf-schema#",
"fep": "https://w3id.org/fep/",
"exampleC": {
"@id": "fep:9606/exampleC",
"@type": "xsd:nonNegativeInteger",
"@container": "@set",
"rdf:comment": "An unordered list of literal values that are specifically non-negative integers"
}
},
"https://www.w3.org/ns/activitystreams"
]
}
```
### Maintaining versioned top-level contexts
Each time the top-level context document is changed by promotion of a new common term, a versioned context SHOULD be generated and frozen. This allows downloading, caching, or otherwise embedding those versioned contexts forever in some software applications, avoiding unnecessary HTTP requests that arise from having to poll for changes to the latest unversioned context. The versioned context SHOULD also refer to [the latest versioned context document for ActivityStreams](https://www.w3.org/ns/activitystreams-history/). Versioned top-level contexts SHOULD be made available via URIs of the form `https://w3id.org/fep/context-(:version).jsonld`. [[TODO: is there a better uri schema here?]]
## Sample use-cases
(This section is non-normative.)
- A software developer wishes to adopt a specific FEP-xxxx and its terms. Their software project references `https://w3id.org/fep/xxxx` in their `@context`.
- A software developer wishes to adopt all "common" FEP extension terms. Their software project references `https://w3id.org/fep` in their `@context`.
- For stability, a software developer might instead reference `https://w3id.org/fep/context-v1.jsonld` to only depend on terms defined in version `v1`.
Refer to [LD-TERM-DFN] for additional guidance on defining terms within JSON-LD.
## References
- [RFC-2119] S. Bradner, [Key words for use in RFCs to Indicate Requirement Levels](https://tools.ietf.org/html/rfc2119.html)
- [ActivityPub] Christine Lemmer Webber, Jessica Tallon, [ActivityPub](https://www.w3.org/TR/activitypub/), 2018
- [LD-TERM-DFN] Gregg Kellogg, Pierre-Antoine Champin, Dave Longley, [JSON-LD 1.1 - Section 9.15.1 "Expanded term definition"](https://www.w3.org/TR/json-ld/#expanded-term-definition), 2020
- [RFC-2119] S. Bradner, [Key words for use in RFCs to Indicate Requirement Levels](https://tools.ietf.org/html/rfc2119.html)
- [1] helge, [FEP-1570: The FEP Ontology Process](https://socialhub.activitypub.rocks/t/fep-1570-the-fep-ontology-process/2972), 2023
## Copyright
feps/fep-9606.md
+1 -1
View File
@@ -1 +1 @@
[moved to /fep/9606](../fep/9606)
[moved to /fep/888d](../fep/888d)