https://github.com/cpluspatch/pronouns-wellknown
Protocol draft for a well-known pronouns API
https://github.com/cpluspatch/pronouns-wellknown
Last synced: 3 months ago
JSON representation
Protocol draft for a well-known pronouns API
- Host: GitHub
- URL: https://github.com/cpluspatch/pronouns-wellknown
- Owner: CPlusPatch
- License: mpl-2.0
- Created: 2024-03-18T05:00:52.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-18T05:07:51.000Z (over 2 years ago)
- Last Synced: 2025-12-30T08:57:18.907Z (6 months ago)
- Size: 7.81 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pronouns in /.well-known Protocol
## 1. Introduction
The Pronouns in /.well-known protocol provides a standardized way for clients to retrieve pronoun information for users or resources. This protocol allows clients to request pronouns for a specific user or retrieve a default set of pronouns.
## 2. Protocol Specification
### 2.1 Request
Clients can send a GET request to the `/.well-known/pronouns` endpoint to retrieve pronoun information. The request can include an optional query parameter `resource` to specify a specific user or resource.
Example request:
```
GET /.well-known/pronouns HTTP/1.1
Host: example.com
```
For sites of multiple users, you can use an arbitrary string in the params to request a specific one. For example:
```
GET /.well-known/pronouns?resource=astrid%40example.com HTTP/1.1
Host: example.com
```
### 2.2 Response
The server responds with a JSON object containing pronoun information. The keys of the object are language codes and the values are arrays of pronouns.
ISO-639-1 language codes are used to specify the language of the pronouns. For example, the language code for English is `en`. The language code can be further refined with a region code, such as `en-us` for American English.
Example response:
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"en-us": ["she/her", "they/them", "it/its"]
}
```
For English pronouns outside of the usual set (which the protocol might include, but not be limited to: he/him, she/her, they/them, it/its), you can specify every position:
```
HTTP/1.1 200 OK
Content-Type: application/json
{
"en-us": [
{
"subject": "they",
"object": "them",
"dependent_possessive": "their",
"independent_possessive": "theirs",
"reflexive": "themself"
},
{
"subject": "xe",
"object": "xem",
"dependent_possessive": "xir",
"independent_possessive": "xirs",
"reflexive": "xirself"
}
]
}
```
### 2.3 Error Handling
Servers are allowed to respond with a 403 Forbidden status code for this endpoint if the client is not authorized to access the requested resource.
```
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": "Forbidden"
}
```
## 3. Security Considerations
As with any protocol that exposes user information, care must be taken to ensure that privacy is maintained. Servers should only provide pronoun information for users who have explicitly opted in to this feature. Additionally, servers should implement appropriate access controls to prevent unauthorized access to user information.