Micropub-extensions

From IndieWeb
Jump to: navigation, search

This page is for documenting extensions to Micropub. Please use this page to document the list of current and proposed extensions, as well as document implementations of them. Development and discussion of the extensions should happen in a GitHub issue.

Please open a new issue here if you would like to propose a new extension, then you can add a new section in the Proposed Extensions section to document your implementation of it here.

Approval of Extensions

The core Micropub spec isn't expected to change, however additional specifications built to extend the Micropub spec are possible. In order to ensure that extensions have diverse implementations there is a three stage process for extensions.

Proposed

Anyone can create a proposed extension. A proposed extension should have an issue in the Micropub Extensions GitHub Repo and a stub under the Proposed Extensions section on this page.

Stable

A stable extension is when a proposed extension has gotten multiple implementations from various people and/or organizations and is considered complete in functionality. This ensures that Micropub extensions work for a variety of use-cases and not just for a single project or company. The general rule of thumb is that there should be a minimum of 3 server implementations and 3 client implementations.

When an extension becomes a stable extension, it should be moved under Stable Extensions section and there should be clear technical specifications for how a client and server would utilize this extension. All brainstorming under this extension should either be finished and cleared out, or logged under a different proposed extension.

Official

An extension only becomes an official Micropub extension when it has been published as part of a broader ranged official Spec extension for Micropub. Currently there are no official extensions.


Official Extensions

There are not currently any Official Extensions

Stable Extensions

Query for Supported Vocabulary

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/1

This is an extension for returning what properties a Micropub server supports, so that a client like Quill or Indigenous could know to hide or rename the common choices in the UI. This is essentially using reverse Post Type Discovery.

This extension adds additional data to the Micropub Configuration query that allows the server to tell the client what types of posts it can receive as well as what those post types should be called in the UI.

When a Micropub client retrieves the Micropub Configuration query, a server supporting this extension should return an array of objects inside the post-types attribute. Each object should represent a post type and have a type attribute that matches the PTD post type and a name that is a string that should represent the post type in the UI.

An example response is below:

  "post-types": [
    {
      "type": "note",
      "name": "Note"
    },
    {
      "type": "article",
      "name": "Blog Post"
    },
    {
      "type": "photo",
      "name": "Photo"
    },
    {
      "type": "reply",
      "name": "Reply"
    },
    {
      "type": "bookmark",
      "name": "Bookmark"
    }
  ]

If a Micropub client checks the Micropub Configuration query for a post-types array and it doesn't exist or it is empty, the client should assume the server does not support this extension and just default to its regular post types and names. However, if at least one object exists in the post-types array, the Micropub client should only display features related to the post types found in the array, and any text in the UI should reflect the name presented in the post-types array.

Implementations

Proposed Extensions

Server Commands

The Micropub spec reserves the mp- prefix in the form-encoded syntax as a mechanism for clients to give commands to servers. This section is for brainstorming additional uses of the mp- functionality.

Slug

Issues and discussion:
https://github.com/indieweb/micropub-extensions/projects/1

Many posting UIs provide an option for the user to choose a slug for the post that will be created.

wordpress-customize-slug.png

This proposal is for a new mp- command for the client to suggest a slug to the Micropub endpoint.

  • mp-slug=

The server may or may not decide to respect the requested slug, based on whether it would cause conflicts with other URLs on the site. For example, some URL structures are {year}/{slug}, so the server may decide to modify the slug to avoid conflicting with an existing one.

Implementations

Destination

Issues and discussion:
https://github.com/indieweb/micropub-extensions/projects/4

Specify a destination to create a new post on a web site other than the default. The value of mp-destination should be a uid from the array of destinations returned from q=config. See an example query response here.

Implementations
  • Clients
    • Monocle - Monocle will check if your Micropub server returns a list of destinations and will then provide an account chooser UI in the footer when viewing a timeline. Selecting an account will cause any of the response buttons to be sent with the corresponding mp-destination value.
  • Servers

New Properties

Post Status

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/19

This is currently under consideration for becoming a "stable" extension. Please see the GitHub issue above to help resolve the remaining issues holding it up from becoming a stable extension.

  • post-status=published (or no post-status set) - The post is published, or when the published date is in the future, the post is scheduled.
  • post-status=draft - The post is a draft, and should not be shown in lists. (Of course it's up to the implementation whether it wants to use a capability URL for draft posts or actually restrict it to logged-in users.)
Implementations

Visibility

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/11

This extension proposed a new property for use in Micropub requests called visibility that informs a server whether a post should be public, private or unlisted. If no visibility is set, a server should assume the visibility is meant to be public. If the visibility is set to unlisted, a server has flexibility to treat that how it wants, however this typically means the post wouldn't appear in feeds such as galleries, timelines or streams. If the visibility is set to private, that means this post should not be accessible unless the user is authenticated.

  • visibility=public (or no visibility set)
  • visibility=private
  • visibility=unlisted

Beyond the scope of this discussion is how a user authenticates for a private post, and if they are authenticated how the access control is managed for said post. But this means depending on the server a private post could be viewable by a single person, or it could allow a group of authorized people to view it as long as they are authenticated.

Implementations

Location Visibility

Proposal by David Shanske

  • location-visibility=public (or no visibility set)
  • location-visibility=private
  • location-visibility=protected

This is based on David Shanske's implementation in Simple Location, an Indieweb friendly location plugin, of the WordPress Geodata unofficial guidelines. It states a single property which can be set to public or private, with the absence of the property being considered to be public. Proposing the third property, which will allow for a less specific text only display, but no actual coordinates.

Implementations

Audience

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/12

This is a proposed extension that allows a Micropub client to tell a server who should be able to access a private post. This is specifically useful with the draft of AutoAuth and the idea of sending private webmentions or creating posts that can be read by only a small group of people.

Implementations
  • Clients
    • ...
  • Servers

Query

Micropub supports making a GET request to a Micropub endpoint with a q= parameter, in order to query aspects of the endpoint or for retrieving the original source content of posts. This section is for brainstorming additional uses of the query functionality. See also Micropub-brainstorming#Query_for_other_information

Query for Post List

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/4

This is a possible extension to the q=source query on my micropub endpoint, if no url is provided it returns a list of posts. This makes the url part of the query really into more of a filter. This would be super handy for clients wanting to present a list of posts to edit/delete/undelete.

Another advantage of this extension is that your micropub server is just responsible for storing and listing posts as microformats, rendering posts can be another bit of software's responsibility

{
 "items": [
  {
    "type": [
      "h-entry"
    ],
    "properties": {
      "like-of": [
        "https:\/\/en.m.wikipedia.org\/wiki\/Poka-yoke"
      ],
      "uid": [
        "20170820131258_59998adae54d0"
      ],
      "published": [
        "2017-08-20T13:12:58+00:00"
      ]
    }
  },
  {
    "type": [
      "h-entry"
    ],
    "properties": {
      "photo": [
        "https:\/\/media.j4y.co\/2017\/cfd007ec-c819-47da-99a2-daec2e91a41e.jpg"
      ],
      "published": [
        "2017-08-19T18:30:40+00:00"
      ],
      "content": [
        ""
      ],
      "category": [
        ""
      ],
      "uid": [
        "20170819175715_59987bfb72c4f"
      ]
    }
  }
}
Implementations

Query for Category/Tag List

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/5

This is an extension for returning categories that a Micropub server has received in the past, so that a client like Quill or Indigenous could present a list of existing categories to choose from when creating a new post. This also incorporates the possibility of being able to search for categories that would match an auto-complete.

The following example would be returned as part of the ?q=category query.

{
  "categories": [
    "tag1",
    "tag2",
    "tag3",
    "tag4",
    "tag5",
  ]
}

The follow example would be returned as part of the ?q=category&search=indie query.

{
  "categories": [
    "indieweb",
    "indieweb-goals",
    "indienews"
  ]
}
Implementations
Brainstorming

category - suggestion to get all existing tags/categories in the client. Expectation is client would cache and do autocomplete


Query for Supported Properties/Queries

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/7
https://github.com/indieweb/micropub-extensions/issues/8

These are two extensions for returning queries that a Micropub server will respond to and properties that a server knows about, so that a client like Quill or Indigenous could present only options appropriate to that server. It is similar to the idea about querying for supported vocabulary, except that proposal only covers properties that are part of post-type discovery. Like with the other proposal, the absence of this instruction would show everything.

The following example would be returned as part of the ?q=config query for supported queries.

{
  "q": [
    "config",
    "syndicate-to",
    "category",
    "source",
    "geo",
  ]
}

The following would be returned as part of the ?q=config query for supported experimental properties unrelated to post-types. These are experimental properties that would require a field within the UI.

{
  "properties": [
    "location-visibility",
    "visibility",
    "post-status",
  ]
}
Implementations


Query for Location/Venue

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/6

Jonny Barnes originally added Query for Places in 2015. His implementation was for /micopub?q=geo=lat.lng;u=XX, returning a JSON response for each place containing a display name, lat/lng value, and a URL that could be used as the location value in a subsequent request.

David Shanske expanded on that to be consistent with the current thinking that returns should be inside a property and to allow for a geo URI or the individual parameters. The geo=lat.lng;u=xx is close to the geo URI format of geo:37.786971,-122.399677;u=35 but in the interest of consistency should actually be a GEO URI and a separate property. Therefore, the query for a request with a Geo URI should be ?q=geo&uri=geo:37.786971,-122.399677;u=35 or optionally, each variable individually... q=geo&lat=x&lon=y&u=z

The following example would be returned as part of the ?q=geo&lat=x&lon=y query. Return would contain two properties, 'venues' and 'geo'. Geo would be a suggestion for the queried location perhaps returned using reverse geolocation, and venues would be one or more venues. The lack of either property assumes nothing could be found about the location.

All returns would follow the common properties of an h-adr object with only label and latitude/longitude being mandatory. There is one optional extra parameter, following the proposed Location Visibility property which would allow the query to suggest whether this location should be publicly displayed, allowing for private venues.

{
  "geo": [
    "label" : "123 Main Street",
    "latitude": "18.1123",
    "longitude": "-72.1933",
    "visibility": "public",
  ],
  "venues": [
   { 
     "label" : "Main Street Apothecary",
     "latitude": "18.1123",
     "longitude": "-72.1931",
     "url": "https://example.com/venues/apothecary",
   },
   { 
     "label" : "Main Street Market",
     "latitude": "18.1123",
     "longitude": "-72.1931",
     "url": "https://example.com/venues/market",
   },
  ]
}
Implementations
Brainstorming

Ideas for other types of queries

  • mp-config
  • extended markup formats โ€“ right now it is relatively dependent on the server implementation how text content is treated (1:1, basic processing like linking URLs, Markdown, ...). A query could expose information about this (and maybe even be part of a way to choose for the user)
  • media endpoint history โ€“ query recent uploads to the media endpoint, e.g. the last X photos uploaded from a phone

Questions

  • According to the current spec (2017-01), a GET ?q=config should also include the syndicate-to property. If the collection of supported properties grows, is this still a thing to hold on to? Venues and tags can make the response potentially large. Sebastiaan Andeweg
    • Agreed, I think the empty GET ?q=config should be very limited, and clients should reqest things with potentially large responses separately. Aaron Parecki 11:40, 11 April 2018 (PDT)

Other

Dealing with Expiring Tokens

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/17

Currently IndieAuth and Micropub don't talk about how to deal with expired tokens, whether auto-expiring tokens or revoked tokens. To get a new token, most Micropub clients will make you log out and back in. However in the new Micropub client era with native apps and Reader web apps, you might not want to have to log out and back in just to refresh your token. (more details for brainstorming available in GitHub issue)

Dealing with Expiring Configuration

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/18

There are instances where the configuration of a Micropub endpoint can change. Currently both the Media Endpont url and the syndication values are in the Micropub's config query. Because the Media Endpoint is an external service it makes sense that at times this url may change, and the user shouldn't have to log out and back in to update that value. (more details for brainstorming available in GitHub issue)

Location checkin information

Indigenous for Android has a checkin post type which passes the checkin information as additional parameters in the Geo URI. The payload property is 'checkin'. It's not doing a JSON post, so you can also immediately upload pictures as well. Additional properties for the venue/location can be added later. The same technique is used to post my geocache logs, see https://indieweb.org/geocaching

geo:51.5258325,-0.1359825,0.0;name=london;url=https://hwclondon.co.uk

This is supported by:

Media Endpoint Extensions

Last Uploaded Query

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/10

This is a proposed extension to the Media Endpoint section of the Micropub spec, where the Media Endpoint will return the last uploaded media element.

Implementations

See Also