jf2 vs. AS 2.0

There has been some discussion of whether an alternative JSON
serialization should be considered by this WG. The proposal that has
been put on the table is currently being called "jf2". The current
draft can be found here:
https://github.com/w3c-social/Social-Syntax-Brainstorming/wiki/jf2

I cannot speak to the motivations for why folks feel this second draft
would be necessary or even remotely beneficial to the WG's efforts but
I can do a side by side comparison with the syntax spec we already
have.

Going through the current draft of the jf2 draft on the wiki:
https://github.com/w3c-social/Social-Syntax-Brainstorming/wiki/jf2...

1. Post object ..

   a. effectively the same as Object in AS2. Calling it something else is not a
      worthwhile "improvement"

   b. "type" is essentially the same function as AS2's "type". No real benefit
      gained. The write up proposes using the Microformats list as the "full"
      list but doesn't indicate anything about extensibility.

   c. Overall, doesn't seem to buy us anything different than current
      AS2 Object definition.

jf2 example:
```json
{
  "type": "entry",
}
```
AS 2.0 example:
```json
{
  "@context": "http://www.w3.org/ns/activitystreams",
  "type": "Note"
}
```

2. URL values

   a. "Every value that is a URL is in an object with a property of url" ...
      This statement is not clear.

   b. This is generally equivalent to the most common case in AS2. AS2 does
      have the additional bit that "url" can specify multiple urls

   c. Overall, doesn't seem to buy us anything different than current
      AS2 "url" definition.

jf2 example:
```json
{
  "type": "image",
  "url": "http://example.org/foo.png"
}
```
AS 2.0 example:
```json
{
  "@context": "http://www.w3.org/ns/activitystreams",
  "type": "Image",
  "url": "http://example.org/foo.png"
}
```

jf2 example:
```json
{
  "type": "entry",
  "video": [
    {
      "type": "video",
      "content-type": "video/mp4",
      "url": "sample_h264.mov"
    },
    {
      "type": "video",
      "content-type": "video/ogg",
      "url": "sample_ogg.ogg"
    },
    {
      "type": "video",
      "content-type": "video/webm",
      "url": "sample_webm.webm"
    }
  ]
}
```
AS 2.0 Example:
```json
{
  "@context": "http://www.w3.org/ns/activitystreams",
  "type": "Video",
  "url": [
    {
      "mediaType": "video/mp4",
      "href": "sample_h264.mov"
    },
    {
      "mediaType": "video/ogg",
      "href": "sample_ogg.ogg"
    },
    {
      "mediatype": "video/webm",
      "href": "sample_webm.webm"
    }
  ]
}
```

3. Post properties

   "The list of valid post properties is defined by vocabularies. This allows
   new vocabularies to be developed outside the development of the syntax"

   This is equivalent to AS 2.0's existing extensibility model.

js2 example
```json
{
  "type": "entry",
  "published": "2015-10-20T15:49:00-0700",
  "url": "http://example.com/post/fsjeuu8372",
  "author": {
    "type": "card",
    "name": "Alice",
    "url": "http://alice.example.com",
    "photo": {
      "type": "image",
      "url": "http://alice.example.com/photo.jpg"
    }
  },
  "name": "Hello World",
  "content": "This is a blog post"
}
```
AS 2.0 example:
```json
{
  "@context": "http://www.w3.org/ns/activitystreams",
  "type": "Note",
  "published": "2015-10-20T15:49:00-0700",
  "url": "http://example.com/post/fsjeuu8372",
  "attributedto": {
    "type": "Person",
    "displayName": "Alice",
    "url": "http://alice.example.com",
    "image": {
      "type": "Image",
      "url": "http://alice.example.com/photo.jpg"
    }
  },
  "displayName": "Hello World",
  "content": "This is a blog post"
}
```
The examples are essentially equivalent. jf2 gives provides nothing new.

jf2 example:
```json
{
  "type": "entry",
  "published": "2015-10-20T15:49:00-0700",
  "url": "http://example.com/like/r23eugi02c",
  "author": {
    "type": "card",
    "name": "Alice",
    "url": "http://alice.example.com",
    "photo": {
      "type": "image",
      "url": "http://alice.example.com/photo.jpg"
    }
  },
  "like-of": {
    "url": "http://bob.example.com/post/100"
  }
}
```
AS 2.0 Example:
```json
{
  "@context": "http://www.w3.org/ns/activitystreams",
  "type": "Like",
  "published": "2015-10-20T15:49:00-0700",
  "url": "http://example.com/like/r23eugi02c",
  "actor": {
    "type": "Person",
    "displayName": "Alice",
    "url": "http://alice.example.com",
    "image": {
      "type": "Image",
      "url": "http://alice.example.com/photo.jpg"
    }
  },
  "object": "http://bob.example.com/post/100"
}
```
The examples are essentially equivalent. jf2 gives provides nothing new.

4. Author

   "An author is represented by the h-card vocabulary"

   AS 2.0 refers to the standardized hcard vocabulary. jf2 is offering
nothing new.

jf2 example:
```json
{
  "type": "card",
  "name": "Aaron Parecki",
  "photo": {
    "type": "image",
    "url": "http://aaronparecki.com/photo.jpg"
  },
  "url": "http://aaronparecki.com/"
}
```
AS 2.0 Example:
```json
{
  "@context": "http://www.w3.org/ns/activitystreams",
  "type": "Person",
  "displayName": "Aaron Parecki",
  "image": {
    "type": "Image",
    "url": "http://aaronparecki.com/photo.jpg"
  },
  "url": "http://aaronparecki.com/"
}
```

5. HTML Content

jf2 example:
```json
{
  "type": "entry",
  "content": {
    "content-type": "text/html",
    "value": "<b>Hello World</b>"
  }
}
```
AS 2.0 Example:
```json
{
  "@context": "http://www.w3.org/ns/activitystreams",
  "type": "Note",
  "mediaType": "text/html",
  "content": "<b>Hello World</b>"
}
```

6. Collections

   jf2 does not offer anything distinctly different from AS 2.0 collections

jf2 example:
```json
{
  "type": "feed",
  "url": "http://alice.example.com/collectionurl",
  "name": "Alice's Home Page",
  "author": {
    "type": "card",
    "name": "Alice",
    "url": "http://alice.example.com",
    "photo": {
      "type": "image",
      "url": "http://alice.example.com/photo"
    }
  },
  "children": [
    { ... },
    { ... }
  ]
}
```
AS 2.0 Example:
```json
{
  "@context": "http://www.w3.org/ns/activitystreams",
  "type": "Collection",
  "url": "http://alice.example.com/collectionurl",
  "displayName": "Alice's Home Page",
  "attributedTo": {
    "type": "Person",
    "displayName": "Alice",
    "url": "http://alice.example.com",
    "image": {
      "type": "Image",
      "url": "http://alice.example.com/photo"
    }
  },
  "items": [
    { ... },
    { ... }
  ]
}
```
the only difference between these is that I renamed fields, added the
@context, and used different values for "type". jf2 offers nothing
different from what's currently in AS 2.0.

7. Summary

    So far, jf2 offers nothing that isn't already covered by AS 2.0.
At best, it represents an exercise in bikeshedding over property names
and a handful of values. AS 2.0 does cover a broader range of use
cases than jf2 so an argument can be made that jf2 is "less
complicated". jf2 attempts to defer the complexity of that by
referencing out to individual microformats vocabularies. I would argue
that doing so actually does not reduce the complexity for
implementers, it simply shifts the problem do a different set of
specs.

I would note that jf2 does not currently handle internationalization
concerns. Addressing such concerns would lead jf2 to duplicate more of
what is already in AS 2.0 today.

Obviously, I'm leading in to this review with an obvious bias towards
the spec we've already been working on for the past year, that already
does everything we need, and that folks have already implemented. I'd
encourage the proponents and authors of jf2 to make specific change
proposals against AS 2.0 if they really feel that things can be
simplified further.

- James

Received on Wednesday, 4 November 2015 00:30:40 UTC