iamcal / iamcal/oembed

How should a document with multiple authors be presented?

Open
#686 4 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

stale
Dominant language
PHP
Stars
1.4k
Forks
772
Avg merge
12h 54m
Merged PRs (30d)
16

Description

Many documents on the web are a product of joint authorship. How should they be presented?

The most-backwards-compatible way is to put the author names all in the author_name field, and then pick one author's URL for display:

{
  "version": "1.0",
  "provider_name": "largo.test",
  "provider_url": "https://largo.test",
  "author_name": "Alice Example and Bob Example",
  "author_url": "https://largo.test/author/alice-example/",
  "title": "This is a post by two authors",
  "type": "rich",

But that loses the link for Bob Example.

Could this spec be updated to support multiple authors, with a fallback for parsers that have not been updated?

{
  "version": "1.0",
  "provider_name": "largo.test",
  "provider_url": "https://largo.test",
  "authors": [
    {
      "author_name": "Alice Example",
      "author_url": "https://largo.test/author/alice-example/",
    },
    {
      "author_name": "Bob Example",
      "author_url": "https://largo.test/author/bob-example/",
    }
  ],
  "author_name": "Alice Example and Bob Example",
  "author_url": "https://largo.test/author/alice-example/",
  "title": "This is a post by two authors",
  "type": "rich",

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the oEmbed specification and the existing author_name and author_url fields. Compare the proposed authors array with the backwards-compatibility requirement, then document a decided schema and fallback behavior for multiple authors.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.