.
1359 [responses]
1360 Snell, J., "Responses for Activity Streams", March 2012,
1361 .
1363 Appendix A. Acknowledgements
1365 The author wishes to thank the Activity Streams community and
1366 implementers for their support, encouragement, and enthusiasm
1367 including but not limited to: Abdul Qabiz, Adina Levin, Adrian Chan,
1368 Adriana Javier, Alan Hoffman, Alex Kessinger, Alexander Ovchinnikov,
1369 Alexander Zhuravlev, Alexandre Loureiro Solleiro, Amy Walgenbach,
1370 Andres Vidal, Angel Robert Marquez, Ari Steinberg, Arjan
1371 Scherpenisse, Arne Roomann-Kurrik, Beau Lebens, Ben Hedrington, Ben
1372 Metcalfe, Ben Werdmuller, Benjamin Goering, Bill de hOra, Bo Xing,
1373 Bob Aman, Bob Wyman, Brett Slatkin, Brian Walsh, Brynn Evans, Charlie
1374 Cauthen, Chris Chabot, Chris Messina, Chris Toomey, Christian
1375 Crumlish, Dan Brickley, Dan Scott, Daniel Chapman, Danny Ayers, Dare
1376 Obasanjo, Darren Bounds, David Cramer, David Nelson, David Recordon,
1377 DeWitt Clinton, Douglas Pearce, Ed Summers, Elias Bizannes, Elisabeth
1378 Norris, Eric Marcoullier, Eric Woods, Evan Prodromou, Gee-Hsien
1379 Chuang, Greg Biggers, Gregory Foster, Henry Saputra, Hillary Madsen,
1380 Howard Liptzin, Hung Tran, Ian Kennedy, Ian Mulvany, Ivan Pulleyn,
1381 Jacob Kim, James Falkner, James Pike, James Walker, Jason Kahn, Jason
1382 Kantz, Jeff Kunins, Jeff Martin, Jian Lin, Johannes Ernst, John
1383 Panzer, Jon Lebkowsky, Jon Paul Davies, Jonathan Coffman, Jonathan
1384 Dugan, Joseph Boyle, Joseph Holsten, Joseph Smarr, Josh Brewer, Jud
1385 Valeski, Julien Chaumond, Julien Genestoux, Jyri Engestroem, Kaliya
1386 Hamlin, Kevin Marks, Laurent Eschenauer, Laurie Voss, Leah Culver,
1387 Libby Miller, Manu Mukerji, Mark Weitzel, Marko Degenkolb, Marshall
1388 Kirkpatrick, Martin Atkins, Martin Svensson, Marty Alchin, Mary
1389 Hoder, Matt Leventi, Matt Wilkinson, Matthias Mueller-Prove, Max
1390 Engel, Max Wegmueller, Melvin Carvalho, Michael Buckbee, Michael
1391 Chan, Michael Richardson, Michael Sullivan, Mike Macgirvin, Mislav
1392 Marohnić, Mo Jangda, Monica Wilkinson, Nate Benes, NeilFred
1393 Picciotto, Nick Howard, Nick Lothian, Nissan Dookeran, Nitya
1394 Narasimhan, Pablo Martin, Padraic Brady, Pat G. Cappalaere, Patrick
1395 Aljord, Peter Ferne, Peter Reiser, Peter Saint-Andre, Phil Wolff,
1396 Philip (flip) Kromer, Richard Cunningham, Richard Zhao, Rick
1397 Severson, Robert Hall, Robert Langbert, Robert Dolin, Robin Cover,
1398 Ryan Boyd, Sam Sethi, Scott Raymond, Scott Seely, Simon Grant, Simon
1399 Wistow, Stephen Garcia, Stephen Sisk, Stephen Paul Weber, Steve Ivy,
1400 Steve Midgley, Steven Livingstone-Perez, Sylvain Carle, Sylvain
1401 Hellegouarch, Tantek Celik, Tatu Saloranta, Tim Moore, Timothy Young,
1402 Todd Barnard, Tosh Meston, Tyler Gillies, Will Norris, Zach Copley,
1403 and Zach Shepherd.
1405 Appendix B. Processing as JSON-LD
1407 While the Activity Streams 2.0 syntax is designed to be compatible
1408 with JSON-LD, in order to successfully process an Activity Streams
1409 document as JSON-LD, a "@context" description needs to be provided.
1410 The following example illustrates an Activity Streams document that
1411 can be processed as JSON-LD containing Schema.org defined metadata
1412 elements.
1414 {
1415 "@context": {
1416 "@vocab": "http://activitystrea.ms/spec/2.0/",
1417 "verb": "@type",
1418 "objectType": "@type",
1419 "id": "@id",
1420 "actor": "http://schema.org/Action/performedBy",
1421 "object": "http://schema.org/BuyAction/bought",
1422 "purchase": "http://schema.org/BuyAction",
1423 "person": "http://schema.org/Person",
1424 "book": "http://schema.org/Book"
1425 },
1426 "verb" : "purchase",
1427 "id" : "urn:example:purchase:123/abc",
1428 "displayName": "John purchased 'A Tale of Two Cities'",
1429 "startTime" : "2013-04-02T12:31Z",
1430 "endTime" : "2013-04-02T12:31Z",
1431 "actor": {
1432 "objectType": "person",
1433 "displayName": "John Doe"
1435 },
1436 "object": {
1437 "objectType": "book",
1438 "displayName": "A Tale of Two Cities"
1439 }
1440 }
1442 Appendix C. Motivational Use Cases
1444 This specification defines a number of syntax changes relative to the
1445 JSON Activity Streams 1.0 specification. The sections that follow
1446 describe some of the general motivations for these changes with
1447 illustrative examples.
1449 C.1. Internationalization (i18n)
1451 The JSON Activity Streams 1.0 syntax has no inherent notion of a
1452 "language context". That is, the core syntax has no internal
1453 mechanism a publisher can use to identify the language used when
1454 constructing the Activity Streams document. Nor are there any
1455 existing mechanisms at the JSON syntax level that an Activity Streams
1456 implementation can inherit. This specification introduces the
1457 "language" property and Natural Language Value concepts to fill this
1458 gap.
1460 Imagine a scenario with a service that receives Activity objects from
1461 users and republishes those to a distributed audience of interested
1462 parties. This service spans international boundaries and the users
1463 speak a multitude of different languages. Within this system, a
1464 native English speaker might subscribe to notifications about
1465 activities posted by a native French speaker.
1467 For instance, let's suppose that our native French speaker posts the
1468 following activity to this system:
1470 POST /activity/feed HTTP/1.1
1471 Content-Type: application/activity+xml
1473 {
1474 "verb": "post",
1475 "language": "fr",
1476 "object": {
1477 "objectType": "article",
1478 "displayName": "Un exemple basique",
1479 ...
1480 }
1481 }
1483 The system receives this activity post and prepares to notify our
1484 native English speaking user. Knowing that this user prefers English
1485 and does not speak a word of French, the system can inspect the
1486 Activity and detect automatically that a translation ought to be
1487 provided. Rather than replacing the original French text, however,
1488 the service can simply add in the English translation along side it.
1490 {
1491 "verb": "post",
1492 "language": "fr",
1493 "actor": {
1494 "id": "urn:example:person:abc",
1495 "displayName": "Jean Valjean"
1496 },
1497 "object": {
1498 "type": "article",
1499 "displayName": {
1500 "fr": "Un exemple basique",
1501 "en": "A basic example"
1502 }
1503 ...
1504 }
1505 }
1507 It is also possible for a Natural Language Value to express
1508 alternative same-language representations of a string that utilize
1509 different writing systems or regions. For instance, it is common for
1510 Japanese translations to provide equivalent ideographic (kanji) and
1511 phonetic (katakana or hiragana) alternatives:
1513 {
1514 "title": {
1515 "ja-Hani": "...",
1516 "ja-Kana": "..."
1517 }
1518 }
1520 C.2. Extensibility (e11y)
1522 Arguably, the two most important extensibility points in the Activity
1523 Streams format are the object type and verb properties.
1524 Implementations are free to come up with their own types and verbs at
1525 any point. While such extensibility is extremely powerful, it comes
1526 with a cost. Namely, implementations that encounter previously
1527 unknown verbs and object types may not have enough to knowledge about
1528 those to do anything significant with them.
1530 For instance, the most common use case for Activity Streams today is
1531 the generation of a human-readable "activity feed" that translates
1532 Activity objects into sentences just as "John uploaded a new photo"
1533 or "Jane checked in at a hotel", etc. Given an extension verb such
1534 as "http://example.org/whatever", an implementation might not have
1535 sufficient information about that verb to generate a readable
1536 sentence describing the activity that occurred.
1538 With Activity Streams 1.0, a number of different approaches have been
1539 tried to address this problem, but all of the solutions essentially
1540 deal with the need to provide additional metadata about extension
1541 verbs and object types so that an implementation can dynamically
1542 learn and adapt. The notion of "type values" is added by this
1543 specification to specifically deal with this issue.
1545 For example, suppose I have an implementation that generates Activity
1546 objects that use a new extension verb "urn:example:verbs:upload".
1547 Knowing that consumers of these objects might not have encountered
1548 this verb before, I want to make it possible for those
1549 implementations to automatically discover metadata about the new
1550 verb. To do so, I can use a type value to provide some basic
1551 information.
1553 {
1554 "verb": {
1555 "id": "urn:example:verbs:upload",
1556 "url": "http://example.org/verbs.json",
1557 "mediaType": "application/ld+json",
1558 "displayName": {
1559 "en": "upload",
1560 "fr": "televersement"
1561 },
1562 "alias": "post"
1564 },
1565 "actor": {
1566 "type": "person",
1567 "displayName": "John"
1568 },
1569 "object": {
1570 "type": "photo",
1571 "displayName": "cats.jpg"
1572 }
1573 }
1575 An implementation receiving this has several choices. It could
1576 choose to ignore everything other than the verb's identifier,
1577 treating it generically as one would have to today using the 1.0
1578 syntax; or, it could inspect the metadata provided and notice that
1579 the extension verb can be treated generally as an alias of "post" or
1580 displayed in English as "upload" and in French as "televersement";
1581 or, it can choose to attempt discovering more information about the
1582 verb by dereferencing the provided URL.
1584 The point is, these options are built into the core syntax, making
1585 extension verbs and object types significantly more usable,
1586 particularly when combined with the new language context features.
1588 C.2.1. Publishing Extension objectType and verb Libraries
1590 By treating extension objectTypes and verbs as objects in their own
1591 right, it becomes trivially possible to use the Activity Streams
1592 format as a means of publishing metadata about extension verbs.
1594 For example:
1596 {
1597 "displayName": "My object types and verbs",
1598 "items": [
1599 {
1600 "objectType": "verb",
1601 "id": "urn:example:verbs:create",
1602 "alias": "post",
1603 "displayName": "Create"
1604 },
1605 {
1606 "objectType": "objectType",
1607 "id": "urn:example:types:article",
1608 "displayName": "Article"
1609 }
1610 ]
1612 }
1614 Implementations could use such documents to dynamically learn about
1615 new verbs and objectTypes.
1617 C.3. First Class Links
1619 Linking in the 1.0 syntax is largely undefined and inconsistent.
1620 There is a general notion of Media Link objects that are used for
1621 some things like images and videos, along with a "url" property that
1622 in some cases is used to always point to HTML represenations while in
1623 other cases might point to JSON documents or image files, and there
1624 is no reusable concept of a generic link provided for extensions to
1625 leverage which has led to inconsistent implementation. The 2.0
1626 syntax introduced here deals with these issues by introducing a
1627 clear, consistent, reusable first class linking model.
1629 For instance, using the 2.0 syntax, an "image" object type can be
1630 represented simply as:
1632 {
1633 "objectType": "image",
1634 "url": "http://example.org/cats.jpg",
1635 "mediaType": "image/jpeg",
1636 "displayName": "A picture of my cats",
1637 "alternate": {
1638 "url": "http://example.org/gallery?i=cats.jpg",
1639 "mediaType": "text/html"
1640 }
1641 "preview": "http://example.org/thumbnails/cats.jpg"
1642 }
1644 Essentially, any 2.0 object that contains a "url" property can be
1645 interpreted as a link. That "url" property points to a
1646 representation of the object, while the "mediaType" property
1647 identifies the content type of that linked resource. RFC 5988 Link
1648 Relations can be used directly within the 2.0 syntax to provide
1649 additional data -- in this case, an alternative HTML representation
1650 of the image as well as a thumbnail preview.
1652 Another case that the more flexible linking approach allows us to
1653 address is providing multiple links for a single property. For
1654 instance, it is not uncommon for there to be several alternative
1655 versions of an image resource offered at various resolutions to
1656 support multiple types of devices. With the 2.0 syntax, multiple
1657 choices for a single link can be easily provided.
1659 {
1660 "objectType": "application",
1661 "displayName": "My application",
1662 "icon": [
1663 {
1664 "url": "http://example.org/sd/icon.png",
1665 "width": 57,
1666 "height": 57
1667 },
1668 {
1669 "url": "http://example.org/hd/icon.png",
1670 "width": 114,
1671 "height": 114
1672 }
1673 ],
1674 "preview": [
1675 "http://www.example.org/screenshots/1.jpg",
1676 "http://www.example.org/screenshots/2.jpg",
1677 "http://www.example.org/screenshots/3.jpg"
1678 ]
1679 }
1681 C.4. Use of External Vocabularies
1683 Use of an "external vocabulary" within Activity Streams means using
1684 object types, verbs and properties that are not defined by the core
1685 Activity Streams specification. An example would be using concepts
1686 defined within a microdata vocabulary such as that defined by
1687 Schema.org (http://schema.org).
1689 Implementations that wish to use a Activity Streams with such
1690 external vocabularies face the challenge that, often times, identical
1691 or overlapping concepts can be expressed in a multitude of ways
1692 depending on which vocabulary is selected. This can make it
1693 difficult to map abstract data models into a specific JSON
1694 serialization.
1696 For instance, suppose an application uses the Schema.org model to
1697 represent an article, described here: http://schema.org/Article.
1698 Within this model, there are several properties defined that directly
1699 overlap properties defined by the core Activity Streams syntax. Such
1700 properties include "name", "contentLocation", and "articleBody". In
1701 order to encode the abstact model of a Schema.org/Article into the
1702 JSON Activity Streams model, the application needs to determine
1703 precisely how to map the abstract properties to the serialized
1704 format. In Activity Streams 1.0, no guidance was given on how to
1705 achieve such a mapping, within the 2.0 syntax, the JSON Serialization
1706 for Linked Data (JSON-LD) provides a foundation.
1708 Using JSON-LD I can maintain basic Activity Streams 2.0 syntax while
1709 mapping the physical serialization to the abstract model inline.
1711 {
1712 "objectType": "article",
1713 "displayName": "My article about things",
1714 "content": "This is my article",
1715 "@context": {
1716 "objectType": "@type",
1717 "article": "http://schema.org/Article",
1718 "displayName": "http://schema.org/name",
1719 "content": "http://schema.org/Article/articleBody"
1720 }
1721 }
1723 For any non-JSON-LD aware implementation, this can be processed just
1724 as if it were an ordinary Activity Streams object, without any
1725 additional consideration given. For a JSON-Ld aware implementation,
1726 however, the addition of the "@context" property allows the
1727 serialized JSON to be unambiguously mapped to the Schema.org concept
1728 of an "Article". The fact that we can support such a mapping allows
1729 the Activity Streams format to extend to a broader range of scenarios
1730 without requiring alternative, incompatible vocabulary specific
1731 models of "actions" or "activities" to be developed.
1733 C.5. Embedded Actions
1735 Every Activity Streams object represents a discreet modular component
1736 that can be distributed, shared, or acted upon in a variety of ways.
1737 The 2.0 syntax allows these components to not only express
1738 information about the content but also about the specific types of
1739 actions that can be performed with the object.
1741 For example, an email that is automatically generated by an expense
1742 reporting system could embed a structured Activity Stream object that
1743 contains a listing of the possible actions the recipient of the email
1744 can take. An intelligent email agent can interpret this embedded
1745 metadata and provide a tailored, in-context UI experience:
1747
1748
1749
1760
1761 Your employee, John Doe, has submitted a new expense
1762 report for "John's trip to San Francisco"....
1763
1764
1766 Author's Address
1768 James M Snell (editor)
1769 IBM
1771 Email: jasnell@gmail.com