.well-known/avatars

• Server files statically in order to open access to as many people as possilbe (e.g. folks that can't afford a server with dynamic processing should not be left out of the feature).

• Provide .well-known/avatars for both DOMAINS and ACCOUNTS. (e.g. so RSS readers can benefit from the feature as well)

• Default images must be square .jpg files and go to these locations for the DOMAIN and ACCOUNTS respectively.

    /.well-known/avatars/default.jpg
    and
    /.well-known/avatars/UUID/default.jpg
  

• manifest.json files list other avatars that are available. They reside at:

    /.well-known/avatars/manifest.json
    and
    /.well-known/avatars/UUID/manifest.json
  

• MANIFEST FILES include two categories of avatars: default and custom.

  The default avatars are intended to be used generically. The custom avatars are to provide the ability for folks to maintain multiple avatars in their own centralized location if they want to use more than one (e.g. so folks don't have to use the same avatar on LinkedIn that they use on Mastodon.)

• Tags are used to communicate intent for which images go where beyond the defaults.

• Don't use image sizes, just use ratios.

• Add a field for Alt Text

• Provide for animated avatars as well

• My site is twenty-five years old. I approach this kind of exercise by thinking about the next twenty-five. It's a fools errand. A prime opportunity for premature optimization. It's also an important part of my process. It boils down to the idea that "Temporary ain't^^tmp^^". The more folks involved in a thing, the more likely it is we'll only get one shot at it.

• I'm using SHOULD/MUST/MAY style, but only loosely as a framework to help writing and to have something to react to. Coming up with a conforming spec/RFC is an exercise for a later time.

• I'm specifying the default images should be ".jpg" files. The format is a placeholder to make the doc easier to read. I'm not concern with the actual format that's used, just that there's only one so the URL is the same 100% of the time.

  I realize that points to a potential situation like /favicon.ico still hanging around. My position is that we've had enough experience with image formats now that we can safely pick a default that will be useful for at least a few decades.

• I'm dropping a UUID in for a namespace identifier. It's as good as any, but should not be considered official in any way at this point.

• "ACCOUNT" - what/whoever's avatars are being served.

• "CLIENT" - sites/networks/apps/RSS readers, etc... that display the avatars.

• "DOMAIN" - the domain/subdomain hosting the AVATAR SET assets.

• "AVATAR SET" - A DEFAULT IMAGE and a MANIFEST FILE. Notably, this DOES NOT include other image assets as those may be hosted in entirely different locations.

• "DEFAULT IMAGE" - a JPEG encoded file that MUST BE named default.jpg

• "MANIFEST FILE" - a JSON file that MUST BE named manifest.json and MUST comply with the SCHEMA.

• "MANIFEST SCHEMA" - The JSON Schema for the MANIFEST FILE. (This will be versioned, but details on that are for a future iteration).

  (I'm not sure where the schema would be hosted, but there will be an explicit URL for it)

NOTE: I've only filled in a few avatars in the `default/static` section. The same format would be used for the other sections if folks have them. They would, of coruse, be opt-in. So, this could be a full example as well

{
  "accountDomain": "www.example.com",
  "accountUUID": "6fdc-etc...",
  "customAvatars": {
    "animated": [],
    "static": []
  },
  "defaultAvatars": {
    "animated": [],
    "static": [
      {
        "altText": "a black and white portrait...",
        "tags": [],
        "url": "/.well-known/avatars/default.jpg",
        "ratio": [1, 1]
      },
      {
        "altText": "lorem ipsum...",
        "tags": ["mastodon"],
        "url": "/images/16x9-example.png",
        "ratio": [1.77, 1]
      },
      {
        "altText": "lorem ipsum...",
        "tags": [],
        "url": "https://well-known-avatars.alanwsmith.com/images/another-1x1.jpg",
        "ratio": [1.77, 1]
      }
    ]
  },
  "manifestSchemaVersion": [0, 1, 0]
}

• Using /.well-known/avatars instead of /.well-known/avatar makes it clear that multiple accounts may be available (and possibly the DOMAIN) are potentially included.

• Using a directory based appraoch like:

    /.well-known/avatars/UUID/default.jpg
    and
    /.well-known/avatars/UUID/manifest.json
  

  instead of a query string appraoch like:

    /.well-known/avatar?resource=acct:username@example.com
  

  allow for the entire feature to be served statically. My position is that this lowers the barrier of entry to gaining access to the avatars significantly. If server side processing is required an entire category of free services is taken off the board.

• Email address should never be sent in cleartext. Even if the requests themselves go over an encrypted channel, it's entirely to easy for a service leak URLs (e.g. a naive developer might call the URL with email address directly from public pages). The system should be set up so that leaking either through intention or mistake is eliminated wherever possible.

  I'm pitching UUID v5 here, but that's very much open for discussion. Those decisions are securty based and I'd look for help from experts in the field on that front.

  The thing I'd want to keep in mind is that whatever approach is used that it be desgined to be portable. Specifcially, you should be able to move your UUID to different DOMAINs without losing the UUID.

• I like having the DOMAIN version included for two reasons. First, it would let folks who have domains use them without having to submit any other token or PII. Second, it feels like a nice way to expand the tools that RSS readers have available as well.

• The idea of using an Accept header to determine which content to reply with is very cool. My push back against it is that it requires server side processing. That introduces the same issue of limiting the availabity to folks who have accesss to server site processing.

  That's what leads me to the independent, explict paths for the .json and .jpg files.

• Thiking about the user interface on CLIENT sides, there would have to be two fields to enter: 1. the email address (or other account token), and 2. the DOMAIN responsible for provding the AVATAR SET.

  Otherwise, there's no way for folks with accounts on domains they don't own to participage.

• A metadata tag should be defined as well. something like:

    <link rel="avatars" href="/.well-known/avatars/UUID/manifest.json" />
  

  I don't know enough about the process to know if that would be handled in a sepearate proposal or not. That could do things like signal RSS readers to use ACCOUNT specific AVATAR SETS instead of DOMAIN ones.

• It's clear a big impetus for using a .well-known address is so a single set of images can be used across multiple services.

  That's awesome, but I don't want to have to use the same image everywhere. The easiest example is that I don't want to use the same image on Mastodon as LinkedIn.

  The desirability of the feature goes up an order of magnitude if I can manage my avatars in a central location but not be limited to one. That's what led to the idea of the default and alternate image collections.

• Square images are the way of the world these days. I don't like the idea of locking into that over a decades long timeline. Different CLIENTS are gonna have designs that call for different image sizes. Frankly, I wouldn't have it any other way. That's what lead to the idea of the different apect ratios.

  Indiivdual CLIENTS can choose whatever best fits their system. They can also publish guidlies for what the most optimail ratios would be. Thouse guidelines would likely include minimal size recommendations. It feels like that's where those recommendations make the most sense intead of trying to define it at the spec level.

  The approch should give some nice flexibilty without getting into the XKCD Standards problem ^^xkcd^^

• CLIENTS can publish a list of TAGS they look for.

  I need to think about this more, but I can see a path to setting up guildelines like:

  CLIENTS CAN utilize any image from the default array.

  CLIENTS SHOULD NOT utilize any images in the alternate array unless they contain a tag matching one the CLIENT makes known they are useing etc...

  Basic idea is that individual who manage an ACCOUNT/DOMAIN AVATAR SET can make DEFAULT images avilable without any extra overhead. But, anyone who's intersted in distributing differeng images to different CLIENTS will have the capability of doing so if they want to put in the effort.

  (And for anyone thinking about yet, you're right, there's not a security envelope around this. Every image listed in a manifest.json could be used by anyone at any point. That's a feature of the system not an oversight. The only way to prevent an image from being used is by not publishing it at all.)

• Tagging also offers some other possabilities. For example CLIENTS could publish that one of the image tags they look for is banner with a ration of 16:9.

  I wouldn't try to standardize those tags but if big services adopt some they'd likely become de facto standards on their own.

• None of this discusses cache handling/proxying etc... That's all worthy of discussion but beyond the scope of this document.

This is, obviously, way more complex than the original idea. My position is that the flexibility is worth the trade-off and that flexibility will have an outsized increase in bring usage into a default move.

I see it as a binary complexity switch. It's either dead simple, or you get a fiddle with a bunch of things.

If you're making your own avatar and don't want to have to deal with the complexity just throw a square image in the default path and be done with it:

-- path/

/.well-known/avatars/SOME_OBFUSCATED_ID/default.jpg

-- /path

-- aside -- title: aside

We'd want to make a tool that generates the IDs for folks so it's easy to do. Ideally, that would get backed into site building apps, but we should make sure there are tools/sites that make it easy to do independently.

-- p

If you're a service/app/RSS reader using the images you can also just pull the default if you want to show an image but don't want to devote the resources to go all-out.

For those people and projects that do want to go father, all the tools are there. From simply using a horizontal image all the way to having multiple animated images for every day of the week for your favorite RSS reader, you can take things as far as the collaboration between the makers and the displayers wants to go.

-- list/

• For users, if you don't want to mess with shit, just throw a square image in:

• If you want to play with all the options start chucking more images into the manifest.jpg at whatever level you want.

• Same goes for services that use the images. Need to get up and running quickly? Grab default.jpg.

• If you're a service that wants more you can grab the horizontal or vertical images.

• Even more? publish a tag you'll back up with recommended sizes. Slurp them up if you find them.

-- /list

Footnotes

-- footnote -- id: tmp

I don't remember who I heard the phrase "Temporary ain't" from. It was years ago, but it's a front-of-mind idea for me.

The best example I have is the "Temporary" process I wrote for grabbing weather data from an API and showing in the PGA TOUR leaderboard during my career there.

It wasn't supposed to be my job, but the team that was theoretically responsible for it couldn't meed a sales deadline. I threw together a script that did the thing until they could get to it. It got used for for ten years.

-- footnote -- id: xkcd -- title: XKCD: Standards -- url: https://xkcd.com/927/

Start with N, end up with N+1.

-- ref -- title: Mastodon Thread -- url: https://hachyderm.io/@Edent@mastodon.social/115424378257516254

-- ref -- title: example -- url: https://shkspr.mobi/.well-known/avatar/?resource=acct:whatever@shkspr.mobi

-- ref -- title: Key Discovery -- url: https://datatracker.ietf.org/doc/html/draft-koch-openpgp-webkey-service-20#name-key-discovery

Something interesting that was referenced in the thread.