Consider defining use of value key in nested microformats for fallback

[barnabywalters]

When consuming microformats 2 data, it’s quite common to encounter a structure when you might have been expecting a plain string value (e.g. expecting a string URL in-reply-to property in a reply h-entry, but getting a nested h-cite, or expecting a plaintext string but getting an embedded HTML structure). In all of these cases, these structures have a top-level value key which can be used as a fallback value. This value property fallback is well-established and familiar to anyone working with mf2 data.

The same pattern could make sense for micropub, if both clients and servers were 1) required to include value keys when sending data containing embedded microformats, and 2) encouraged to make use of them as fallback when encountering a structure which they don’t understand, either in micropub requests containing JSON bodies, or in the responses to source queries.

Example: plaintext value as client fallback for server-expanded h-cite in-reply-to

Say a reply post is created with the following data:

{
  "type": ["h-entry"]
  "properties": {
    "in-reply-to": ["https://example.com/posts/1"],
    "content": ["Ha ha wow cool psot"]
  }
}

The server, on creating the post, might expand the in-reply-to URL into a h-cite with various properties e.g. name, content, photo, author (which could in turn be an embedded h-card).

Say the user then uses the same app to try to edit the post they made (to correct the typo, for example), and the server includes the nested microformat in the "in-reply-to" property rather than the plain string sent by the client. If the app has a UI for customising h-cite previews, it can present the user with that. However, if it doesn’t, it’d be confusing to simply not show anything in a reply-to field for the user to edit. If the source query included a value key in the nested microformat, as follows:

{
  "type": ["h-entry"]
  "properties": {
    "in-reply-to": [{
      "type": ["h-cite"],
      "properties": {•••},
      "value": "https://example.com/posts/1"
    }],
    "content": ["Ha ha wow cool post"]
  }
}

Then the client app, without knowing anything about the structure of an h-cite, can fill a text field with the value key of the in-reply-to property, allowing the user to edit it as expected. On receiving an update, the server would then re-create the link preview based on the new URL.

Example: client sending an unrecognised embedded microformat to a server

Taking the same example in reverse: say a MP client has a UI for customising the link previews of in-reply-to h-cite properties, so the user can decide where to truncate text, or correct formatting issues. The client would then send a MF structure with embedded h-cite to the server. If the server supports the in-reply-to property, but doesn’t understand nested h-cite structures, it can use the value property (which should be the u-url of the h-cite as per the nested value key parsing rules) as a plaintext fallback. This case loses some data (any customisations to the link preview which the user made) but at least results in a successful post, rather than either an error or a post with no reply.

Proposal

The concrete proposal would be the following two additions to the spec:

• When transferring JSON-formatted data with embedded microformats structures, the embedded structures MUST contain a valid value key containing a single string
• When encountering an unsupported JSON structure where they only support a plaintext string value, servers and clients SHOULD fall back to using the value key. When doing this, clients MAY warn the user that they’re not editing the full object, which could result in loss of data.

Additionally, the JSON-formatted examples should be updated to include the value key on nested microformats.