It is considered best practice in the linked-data ecosystem to have IRIs be HTTPS URIs that resolve to a definition of the term being used, and it is desirable to define such terms in a JSON-LD context file that is referenced by its IRI rather than having the full @context object embedded in every single document. ActivityStreams 2.0 and ActivityPub do this with the normative context and namespace provided at https://www.w3.org/ns/activitystreams, but this namespace is not generally open to extensions or to experimental terms. This FEP therefore proposes using https://w3id.org/fep as a base IRI for the FEP process, allowing sub-namespaces for each FEP.
(This section is non-normative.)
The core idea behind this FEP is attributed to helge on SocialHub [1][1]. Specifically, the proposal to register fep at the W3ID service is adopted wholesale, with alterations made to the specifics of implementing the redirect mappings using .htaccess rules. These alterations are intended to allow easier sub-namespace allocation for each FEP.
The key words “MUST”, “SHOULD”, “MAY” are to be interpreted as described in [RFC-2119][RFC-2119].
(This section is non-normative.)
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][AS2-Core] provides and defines the [Activity Vocabulary][AS2-Vocab] 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][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][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 under which extension terms can be defined pursuant to the FEP process and the above problems can be reduced.
(This section is non-normative.)
Within the XMPP ecosystem, the core XMPP specification is defined within an RFC, and further functionality is afforded by the “eXtensible” nature of XMPP. The XMPP Standards Foundation (XSF) maintains the process for stewarding new extensions via XMPP Extension Protocols (XEPs). XML namespacing for such extensions is provided by urn:xmpp:, as the XML ecosystem generally prefers using URNs rather than using HTTPS URIs. Such URNs are fully location-independent and not vulnerable to DNS expiry, lapsing, or insolvency. Instead, they are assigned within the authority of the XSF. The XSF maintains an XMPP Registrar and allows XEPs to request and define sub-namespaces beneath urn:xmpp:. In exchange, these URNs are not generally dereferencable without a resolver that looks up the URN within the XEP database.
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 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.
Broad design goals for the redirect mapping include:
Accept: application/ld+json HTTP header, and SHOULD otherwise return human-friendly proposal documents or term definitions by default.At minimum, the following redirects SHOULD resolve as follows:
https://w3id.org/fep
Accept: * => the FEP repository or current home pagehttps://w3id.org/fep/(:id)
Accept: application/ld+json => a specific FEP’s context documentAccept: * => a specific FEP’s proposal documentAdditionally, the following MAY resolve:
https://w3id.org/fep/(:id)/(:term)
Accept: application/ld+json => a specific FEP’s specific term definition in JSON-LD ontology/schemaAccept: application/rdf+xml => a specific FEP’s specific term definition in RDF/XML ontology/schemaAccept: text/turtle => a specific FEP’s specific term definition in Turtle ontology/schemaAccept: * => a specific FEP’s specific term’s folderAt 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.
(This section is non-normative.)
An example .htaccess file is co-located with this FEP, and reproduced below for convenience:
RewriteEngine on
# catch root request
RewriteRule ^\/?$ https://codeberg.org/fediverse/fep [R=302,L]
# Catch FEP documents
## By content negotiation
### JSON-LD
RewriteCond %{HTTP_ACCEPT} application/ld\+json
RewriteRule ^([A-Za-z0-9]+)\/?$ https://raw.codeberg.page/fediverse/fep/fep/$1/fep-$1.jsonld [R=302,L]
### RDF+XML
RewriteCond %{HTTP_ACCEPT} application/rdf\+xml
RewriteRule ^([A-Za-z0-9]+)\/?$ https://fediverse.codeberg.page/fep/fep/$1/fep-$1.rdf [R=302,L]
### Turtle
RewriteCond %{HTTP_ACCEPT} text/turtle
RewriteRule ^([A-Za-z0-9]+)\/?$ https://fediverse.codeberg.page/fep/fep/$1/fep-$1.ttl [R=302,L]
## By URL hacking
RewriteRule ^([A-Za-z0-9]+).jsonld$ https://raw.codeberg.page/fediverse/fep/fep/$1/fep-$1.jsonld [R=302,L]
RewriteRule ^([A-Za-z0-9]+).rdf$ https://raw.codeberg.page/fediverse/fep/fep/$1/fep-$1.rdf [R=302,L]
RewriteRule ^([A-Za-z0-9]+).ttl$ https://raw.codeberg.page/fediverse/fep/fep/$1/fep-$1.ttl [R=302,L]
## By default, take you to the FEP document
RewriteRule ^([A-Za-z0-9]+)\/?$ https://codeberg.org/fediverse/fep/src/branch/main/fep/$1/fep-$1.md [R=302,L]
# Catch term definitions/schemas/ontologies
## By content negotiation
### JSON-LD
RewriteCond %{HTTP_ACCEPT} application/ld\+json
RewriteRule ^([A-Za-z0-9]+)\/(.*?)\/?$ https://raw.codeberg.page/fediverse/fep/fep/$1/$2/$2.jsonld [R=302,L]
### RDF+XML
RewriteCond %{HTTP_ACCEPT} application/rdf\+xml
RewriteRule ^([A-Za-z0-9]+)\/(.*?)\/?$ https://fediverse.codeberg.page/fep/fep/$1/$2/$2.rdf [R=302,L]
### Turtle
RewriteCond %{HTTP_ACCEPT} text/turtle
RewriteRule ^([A-Za-z0-9]+)\/(.*?)\/?$ https://fediverse.codeberg.page/fep/fep/$1/$2/$2.ttl [R=302,L]
### test html
RewriteCond %{HTTP_ACCEPT} ^text/html$
RewriteRule ^([A-Za-z0-9]+)\/(.*?)\/?$ https://fediverse.codeberg.page/fep/fep/$1/$2/$2.html [R=302,L]
## By URL hacking
RewriteRule ^([A-Za-z0-9]+)\/(.*?).jsonld$ https://raw.codeberg.page/fediverse/fep/fep/$1/$2/$2.jsonld [R=302,L]
RewriteRule ^([A-Za-z0-9]+)\/(.*?).rdf$ https://fediverse.codeberg.page/fep/fep/$1/$2/$2.rdf [R=302,L]
RewriteRule ^([A-Za-z0-9]+)\/(.*?).ttl$ https://fediverse.codeberg.page/fep/fep/$1/$2/$2.ttl [R=302,L]
RewriteRule ^([A-Za-z0-9]+)\/(.*?).html$ https://fediverse.codeberg.page/fep/fep/$1/$2/$2.html [R=302,L]
RewriteRule ^([A-Za-z0-9]+)\/(.*?).md$ https://fediverse.codeberg.page/fep/fep/$1/$2/README.md [R=302,L]
## By default, just take you to the term's folder
RewriteRule ^([A-Za-z0-9]+)\/(.*?)\/?$ https://codeberg.org/fediverse/fep/src/branch/main/fep/$1/$2 [R=302,L]
# a generic catch-all rule
RewriteRule ^(.*)\/?$ https://codeberg.org/fediverse/fep/raw/branch/main/fep/$1 [R=302,L]
FEPs that wish to define extension terms within the w3id.org/fep namespace MUST provide a JSON-LD document co-located within their FEP folder with a filename of the form fep-xxxx.jsonld, where xxxx is the FEP’s slug. This document MUST include at least a @context key, whose value is a JSON object containing term definitions. Simple term definitions map a term key to an IRI value. Expanded term definitions contain @id for each term, with @type of @id if the term links to another node on the graph. Refer to [LD-TERM-DFN][LD-TERM-DFN] for additional guidance on defining terms within JSON-LD.
The document MAY include additional metadata outside of the @context, such as schema or ontology definitions. If this is done, then you SHOULD NOT include any prefixes in your @context that are only used within the graph, as these can pollute the usage as a context document.
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.
(This section is non-normative.)
For example, say we wanted to define the following terms within the current FEP-888d:
SomeType is a term for some typeexampleA is a term for a property with some literal value (string, boolean, number)exampleB is a term for a property that links to another node on the graph (for example, another object)exampleC is a term for a property that is an ordered list of literal values that are specifically non-negative integersThe context document might look like this, at minimum:
{
"@context": {
"SomeType": "https://w3id.org/fep/888d/SomeType",
"exampleA": "https://w3id.org/fep/888d/exampleA",
"exampleB": {
"@id": "https://w3id.org/fep/888d/exampleB",
"@type": "@id"
},
"exampleC": {
"@id": "https://w3id.org/fep/888d/exampleC",
"@type": "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
"@container": "@list"
}
}
}
Refer to [LD-TERM-DFN][LD-TERM-DFN] for additional guidance on defining terms within JSON-LD.
A folder within the FEP’s directory should be used to provide additional documentation for the term, such as ontology or schema definitions via JSON-LD, RDF/XML, and/or Turtle.
(This section is non-normative.)
Depending on convenience or preference, the context document might instead look like this:
{
"@context": {
"SomeType": "https://w3id.org/fep/888d#SomeType",
"exampleA": "https://w3id.org/fep/888d#exampleA",
"exampleB": {
"@id": "https://w3id.org/fep/888d#exampleB",
"@type": "@id"
},
"exampleC": {
"@id": "https://w3id.org/fep/888d#exampleC",
"@type": "http://www.w3.org/2001/XMLSchema#nonNegativeInteger",
"@container": "@list"
}
}
}
Refer to [LD-TERM-DFN][LD-TERM-DFN] for additional guidance on defining terms within JSON-LD.
In such a case, the FEP document should include an element with an HTML identifier that exactly matches the term name, so that the IRI fragment resolves properly. In practice, this means one of the following:
summary, acknowledgements, requirements, references, copyright, and so on, including any headers that the FEP author includes for purposes other than explicitly defining the term.### h3 {#custom-identifier} and render <h3 id="custom-identifier">h3</h3>. 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][CM-ATTRS] for more discussion of this feature.id attributes exactly matching the term name. HTML within Markdown files is generally rendered as-is, although it may be sanitized, stripped, or disallowed for security purposes. In cases where it is allowed, however, it can be an effective way to express term definitions within an FEP document.(This section is non-normative.)
If terms are defined within HTML using RDFa, and this HTML is embedded in the Markdown contents of the FEP document, then these term definitions can be used to programmatically generate machine-readable term definitions, schemas, and ontologies in multiple formats. A Python script is provided within the FEP repository at scripts/make_definitions.py for convenience.
To make use of the script, it is necessary to structure term definitions in a specific way. We define a “term definition” to be any HTML element that adheres to the following requirements:
id attribute equal to the shorthand term name.resource attribute equal to the term’s full IRI.Generally, this HTML element should be a <section> tag, and it should contain a definition list (<dl></dl>) where each term (<dt></dt>) and definition (<dd></dd>) provide a key-value pair representing a property of that term definition. Examples may be provided within a preformatted code block (<pre><code></code></pre>), and multiple examples may be provided. Example code blocks can have a title attribute on the <pre> tag. It is generally recommended to put any term definitions below a heading called something like “Terms defined”.
For all term definitions regardless of type, it is recommended to include the following properties in your definition list:
rdfs:label is a natural language label that can replace the shorthand term. For example, a term that is normally expressed with the shorthand hasValue might be labelled has value in plain English.rdfs:comment is a natural language description that gives more detail about what the term means.rdfs:isDefinedBy is a reference pointing to where the term is defined. Usually this is the current FEP, but meta-FEPs that bundle other FEPs may use this property to refer to the original FEP that defined a term.For term definitions that define a class (such as rdfs:Class or owl:Class), it is recommended to include the following properties in your definition list if appropriate:
rdfs:seeAlso is a reference to some other resource that provides more information about the current term. Usually this can be used to link a class to the properties that instances of that class may have.rdfs:subClassOf is a property that declares the current class to inherit from the object. Logically, if something is an instance of the current class, it is also an instance of the superclass. For example, in [AS2-Vocab][AS2-Vocab], OrderedCollection is a subclass of Collection, so all OrderedCollection objects are also implied to have a type of Collection as well, even if not explicitly declared to be one.For term definitions that define a property (such as rdf:Property, owl:DatatypeProperty, or owl:ObjectProperty), it is recommended to include the following properties in your definition list if appropriate:
rdfs:domain is the Domain of the property. Logically, this implies that if a property p has a domain D, and a given resource has the property p, then that resource has a type of D. For example, in [AS2-Vocab][AS2-Vocab] the domain of actor is Activity, so anything that has an actor is implied to be an Activity even if not explicitly declared to be one.rdfs:range is the Range of the property. Logically, this implies that if a property p has a range R, and a given resource is the value of p, then that resource has a type of R. For example, in [AS2-Vocab][AS2-Vocab] the range of replies is Collection, so anything that is the value of replies is implied to be a Collection even if not explicitly declared to be one.property of owl:minCardinality has a content of 1 (with a datatype of xsd:nonNegativeInteger). In other words, a property with a minimum cardinality of 1 must have at least one value. If the property is not Required, then this statement can be amended to have a content of 0, or in other words, you are stating that this property must have at least 0 values (which allows having no values).property of owl:maxCardinality has a content of 1 (with a datatype of xsd:nonNegativeInteger). In other words, a property with a maximum cardinality of 1 can have at most one value. If the property is not Functional, then this statement can be omitted.rdfs:seeAlso is a reference to some other resource that provides more information about the current term. Usually this can be used to link a property to other related terms, such as term definitions that can be used as the value of this property.If the term definition contains JSON-LD keywords like @id, @vocab, @set, or @list within a <dd> element whose corresponding <dt> element’s inner text exactly matches Range, then these keywords can be used to automatically generate a context document. Set the attribute excluded on the term definition to a non-empty value to exclude it from auto-generated context term definitions.
Source code for the script is available in make_definition.py, currently co-located in the FEP-888d folder.
The script will operate according to the following logic:
@id, @vocab, @set, and @list.fep-$SLUG.jsonld co-located within the FEP folder). Failure to read this path as valid JSON will lead to an empty context mapping.id and resource. These are considered “term definitions”.s equal to the resource attribute of the element.term_type equal to the typeof attribute of the element.s rdf:type term_type.property attribute. These are considered “property definitions”.
p equal to the property attribute.o equal to the resource attribute. If not present, then set the object o equal to the href attribute. If not present, then set the object o equal to the content attribute. If not present, then set the object o equal to the inner text of the current element.lang equal to the lang attribute.datatype equal to the datatype attribute.s, p, o, lang, and datatype, making sure to expand any CURIEs according to the RDFa initial context.
datatype or lang, then the object o is a Literal.o is an IRI reference.excluded attribute, then extract JSON-LD keywords and automatically generate a context term definition.
term_name equal to the id attribute of the element.options mapping to keep track of extended term definitions.<dt> element with its corresponding child <dd> element.<dt> element whose inner text is exactly “Range”. [TODO: something less fragile?]<dd> element for a resource attribute. If there is one, extract this IRI as type_iri.
type_iri starts with xsd, then insert @type: type_iri into the options mapping.<dd> element for a substring @id. If found, then insert @type: @id into the options mapping.<dd> element for a substring @vocab. If found, then insert @type: @vocab into the options mapping.<dd> element for a substring @set. If found, then insert @container: @set into the options mapping.<dd> element for a substring @list. If found, then insert @container: @list into the options mapping.options mapping is not empty, then insert @id: s into the options mapping.options mapping is not empty, then map term_name to the options mapping. Otherwise, map term_name to the string s. This is considered a “context term definition”.s is not a fragment identifier, then for each alternate output format in OUTPUT_FORMATS, serialize the current term graph to that format and write it to a file within a co-located subfolder with the name term_name.
term_name set equal to the id attribute of the term definition.<dt> element with its corresponding child <dd> element.<dt> and <dd> element, write a definition list term and definition list definition.<pre>.Examples.title attribute is present, then write a paragraph with the text set to the value of title.lang attribute is present, then append its value immediately afterward.fep-$SLUG.$FORMAT. For example, if Turtle output is enabled, then fep-xxxx.ttl will be written. For JSON-LD output, use the current context mapping when serializing the FEP-wide graph. For HTML+RDFa or Markdown output, ignore these formats. (Outputting HTML can be done as part of a separate process of rendering the Markdown with a static site generator. Outputting the Markdown makes no sense since it is the source material and should not be overwritten.)
fep-xxxx.jsonld.markdown on PyPI)beautifulsoup4)rdflib)markdownify)python-frontmatter)uv run instead.python fep/888d/make_definitions.py $SLUG will read term definitions from the contents of fep/$SLUG/fep-$SLUG.md, then generate alternate formats for the FEP. If your terms are defined with fragment identifiers (of the form https://w3id.org/fep/xxxx#term), then only the FEP itself will be generated in alternate formats. If your terms are defined with absolute identifiers (of the form https://w3id.org/fep/xxxx/term), then co-located subdirectories will be created as well, and singular term definitions will be generated in chosen output formats. If a context.jsonld document is present in the FEP folder, then it will be copied into the JSON-LD alternate format output. The current default output formats are:
python fep/888d/make_definitions.py $SLUG -c will do everything in the above bullet point, except for copying context.jsonld. Instead, it will check for JSON-LD keywords and attempt to auto-generate a context document based on those keywords. If JSON-LD output is disabled, the script will generate only a context document instead of a combined context document and schema or ontology.(This section is non-normative.)
Using the same fictitious terms from the above examples:
SomeType is a term for some typeexampleA is a term for a property with some literal value (string, boolean, number)exampleB is a term for a property that links to another node on the graph (for example, another object)exampleC is a term for a property that is an ordered list of literal values that are specifically non-negative integersExcludedExample is a term for some class that is useful for ontology but not intended to be used for the context mappingWe can formulate the following machine-readable term definition blocks, which are intended to provide a range of examples of various RDFa syntactical constructs for demonstration purposes. Specifically, the following mechanisms are demonstrated:
resource with a typeof some classproperty with a specified lang
property has a value that is a resource
property where the object value is referred to by href instead of resource (for example, in an anchor link)property by including multiple tags@context, such as signaling that a property is required or functional
property has literal content instead of referring to a resource, and that this content can have its own datatype to which it can be coercedexcluded attributehttps://w3id.org/fep/888d/SomeType
{
"@context": "https://w3id.org/fep/888d",
"@type": "SomeType",
"exampleA": true,
"exampleB": "https://example.com/some-object",
"exampleC": [1, 1]
}
</section>
https://w3id.org/fep/888d/exampleA
{
"@context": "https://w3id.org/fep/888d",
"@type": "SomeType",
"exampleA": true,
"exampleB": "https://example.com/some-object",
"exampleC": [1, 1]
}
https://w3id.org/fep/888d/exampleB@id)
{
"@context": "https://w3id.org/fep/888d",
"@type": "SomeType",
"exampleA": true,
"exampleB": "https://example.com/some-object",
"exampleC": [1, 1]
}
https://w3id.org/fep/888d/exampleC
{
"@context": "https://w3id.org/fep/888d",
"@type": "SomeType",
"exampleA": true,
"exampleB": "https://example.com/some-object",
"exampleC": [1, 1]
}
https://w3id.org/fep/888d#ExcludedExample