| images | ||
| spec | ||
| DIRECTORIES.md | ||
| LICENSE | ||
| README.md | ||
SODAP: Simple Online Directory Access Protocol
| Author(s) | Reese Armstrong |
| Version | main |
| Drafted | 2024-07-14 |
Caution
This is still actively being drafted and is a work-in-progress.
Abstract
The Simple Online Directory Access Protocol, or SODAP, is a specification for exposing a directory of people over the web through Webfinger and JSON-LD.
Compliant directories
1. Introduction
It is the goal of this specification to describe a way to discover Actors and their associated details located at an online Directory.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", " SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
"JRD" shall be defined as JSON Resource Descriptor as defined in RFC 7033.
Phrases wrapped in brackets like [This] in this document are to be interpreted as templates where the value inside the brackets should be replaced with the term's value in your environment.
2. Directory
A Directory SHALL be an HTTP web server which hosts one or more Actors.
"Directory URI" shall be defined as the URI resolving to the location on the web of the Directory.
2.1. Index
A Directory MAY provide an index (the Index) of all Actors it hosts, which SHALL be located at /.well-known/actors. The Index, if provided, SHALL consist of an array of JRDs for each Actor:
[{
"subject": "[Account URI]",
"links": [{
"rel": "[Actor Type URI]",
"href": "[Actor URI]"
}]
}]
2.1. Authorization
A Directory MAY place authorization requirements for accessing and/or discovering Actors.
Requestor authentication to determine Directory authorization SHOULD use pre-shared Client Identifiers and Client Secrets issued by the Directory over HTTP Basic Auth. Directories SHOULD use TLS security to ensure that the credentials are not intercepted by an attacker.
3. Actor
An Actor SHALL be a JSON-LD representation of a person available over HTTP pursuant to the Actor Type.
3.1. Actor Type
The Actor Type is the JSON-LD type definition for Actors which is a compliant Schema.org Person.
It is located at http://purl.org/sodap/spec/main/actor.
3.1.1 URI
"Actor Type URI" shall be defined as the URI resolving to the location on the web of the Actor Type without a trailing slash.
3.1.2. Context
The Context SHALL consist of a general inclusion of Schema.org, as well as the following mappings:
| Mapped | Source |
|---|---|
actor |
[Actor Type URI]/ |
Actor |
[Actor Type URI] |
id |
@id |
type |
@type |
preferredUsername |
actor:preferredUsername |
valid |
actor:valid |
3.1.3. Graph
The Graph SHALL consist of the following definitions:
3.1.4. Type
The Type SHALL consist of both Actor as well as Person.
3.2. Properties
Actors SHALL contain an @context property equal to the Actor Type URI.
Actors SHALL contain a type property equal to Actor.
Actors SHALL contain an id property equal to the Actor URI.
Actors SHALL contain a preferredUsername property which SHOULD be the preferred username selected by the person referenced, and SHALL be unique among all Actors at a Directory ("Preferred Username"). Requestors SHOULD NOT expect Preferred Usernames to be globally unique and SHOULD use Account URIs to distinguish Actors instead.
Actors SHALL include a webfinger property equal to the Account URI. (More non-normative information is available at FEP-2c59.)
Actors MAY contain a valid value which SHALL be interpreted as whether the Actor is a valid entry in the Directory. If this value is absent, it SHALL be assumed to be true. For example, this may be used to notate whether a membership is expired or not.
Actors MAY contain additionalProperties value which SHALL be interpreted as an unordered array of various properties set by the Directory. Properties are RECOMMENDED to include an rdfs:comment and rdfs:label. Properties SHOULD be set as elements in the graph of the Actor as follows:
"@graph": [
{
"@id": "[Actor URI]/PropertyName",
"@type": "Text",
"rdfs:comment": "Property Name is for XYZ",
"rdfs:label": "Property Name"
}
]
Actors then use items in the additionalProperties value to refer to these new graph elements:
"additionalProperties": [
{
"@type": "[Actor URI]/PropertyName",
"@value": "Property Value"
}
]
All other properties are optional (e.g. Schema.org Person properties).
3.3. Account URI
"Account URI" SHALL be an acct URI as described in RFC7565 referencing an Actor's canonical WebFinger address.
The userpart of the Account URI SHALL consist of the Actor's Preferred Username.
The host of the Account URI SHALL consist of the host portion of the Directory URI where the Actor is located.
3.4. Actor URI
"Actor URI" shall be defined as the URI resolving to the location on the web of the Actor at the Directory.
3.5. Example
An example compliant Actor is as follows:
{
"@context": "http://purl.org/sodap/spec/main/actor",
"type": "Actor",
"id": "https://example.com/actors/reesericci",
"webfinger": "acct:reesericci@example.com",
"preferredUsername": "reesericci",
"name": "Reese Armstrong",
"email": "me@reeseric.ci"
}
3.6. Relationship to OpenID Connect
This section is non-normative
A Directory may provide an OpenID Connect issuer which authenticates their actors with third-party services.
If so, it can be discovered at the WebFinger endpoint but is not directly present in the Actor. This is due to OpenID Connect subjects and Actors being only linked by their shared Account URI.
Additionally, the WebFinger endpoint where an Actor is discovered may reference an OpenID Connect endpoint not provided by the Directory but still corresponding to Actors. Requestors should trust the WebFinger response for the correct location of the OpenID Connect endpoint for an Actor.
4. Discovery
Actors SHALL be listed as a JRD link to the Actor URI verbatim, without redirects or aliases, with rel equalling the Actor Type URI, for the Account URI at a WebFinger endpoint, as defined in RFC7033.
{
"rel": "[Actor Type URI]",
"href": "[Actor URI]",
}