Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: c1b0861125
James M Snell May 09, 2012
file 560 lines (349 sloc) 18.521 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560



Activity Streams Working Group J. Snell
                                                                     IBM
                                                             May 9, 2012


                 Verb Definitions for Activity Streams

Abstract

   TBD


Table of Contents

   1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
   2. The "verb" Object Type . . . . . . . . . . . . . . . . . . . . 2
     2.1. Object Combinations . . . . . . . . . . . . . . . . . . . . 2
     2.2. Templates . . . . . . . . . . . . . . . . . . . . . . . . . 5
     2.3. A Complete Example . . . . . . . . . . . . . . . . . . . . 7
     2.4. Verb Collections . . . . . . . . . . . . . . . . . . . . . 7
   3. Security Considerations . . . . . . . . . . . . . . . . . . . . 8
   4. License . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
   5. Normative References . . . . . . . . . . . . . . . . . . . . . 9
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9



























Snell [Page 1]

                            Verb Definitions May 2012


1. Introduction

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].


2. The "verb" Object Type

   The "verb" object is a special type Activity Streams Object used to
   describe verbs that can be used within the Activity Streams format.

   At a minimum, "verb" objects consist of the following properties:

   +-------------+---------------+-------------------------------------+
   | Name | Type | Description |
   +-------------+---------------+-------------------------------------+
   | displayName | String | A natural-language, human-readable |
   | | | and plain-text display name for the |
   | | | verb. |
   | hypernyms | Array of | An array of zero or more other |
   | | Strings | known verbs for which this verb can |
   | | | be considered a hyponym. |
   | id | String | The unique identifier for the verb |
   | | | object. |
   | objects | Array of | An array of Object Combinations |
   | | Object | that generally describes the most |
   | | Combinations | common combinations of actor, |
   | | (Section 2.1) | object and target object types |
   | | | expected to be used with this verb. |
   | | | Object combinations are discussed |
   | | | in detail within Section 2.1. |
   | synonyms | Array of | An array of zero or more other |
   | | Strings | known verbs for which this verb can |
   | | | be considered to be a synonym or |
   | | | alias. |
   | value | String | The specific String that is to be |
   | | | used for the "verb" property within |
   | | | an Activity object. |
   +-------------+---------------+-------------------------------------+

2.1. Object Combinations

   An "Object Combination" a description of what types of actor, object
   and target objects are typically expected to be used with a
   particular verb. Each possible combination is represented as
   distinct objects that consist of the following properties:




Snell [Page 2]

                            Verb Definitions May 2012


   +----------------+---------------+----------------------------------+
   | Name | Type | Description |
   +----------------+---------------+----------------------------------+
   | actor | String | A specific actor objectType or |
   | | | the literal character "*" to |
   | | | indicate any objectType. |
   | object | String | A specific object objectType or |
   | | | the literal character "*" to |
   | | | indicate any objectType. |
   | target | String | A specific target objectType or |
   | | | the literal character "*" to |
   | | | indicate any objectType. If the |
   | | | target property is not specified |
   | | | as part of the combination, the |
   | | | assumption is that no target |
   | | | property is expected to be |
   | | | significant within activities |
   | | | that utilize this combination of |
   | | | object types. |
   | targetRequired | Boolean | A boolean that indicates whether |
   | | | a target property is considered |
   | | | to be a required for this object |
   | | | type combination. If not |
   | | | specified, the value is assumed |
   | | | to be false, indicating that the |
   | | | target object is optional. |
   | templates | Templates | An object that generally |
   | | Object | describes how instances of |
   | | (Section 2.2) | activities using this Object |
   | | | Combination can be expressed in |
   | | | human-readable language. |
   | | | Templates are discussed in |
   | | | detail within Section 2.2. |
   +----------------+---------------+----------------------------------+

   For instance, to indicate that a verb is typically associated with
   "person" actors, "note" objects and any kind of target, the Object
   Combination representation would be:

     {
       "actor": "person",
       "object": "note",
       "target": "*",
       "targetRequired": true,
       "templates": {...}
     }

   The value of the "objects" property on the "verb" object consists of



Snell [Page 3]

                            Verb Definitions May 2012


   zero or more Object Combinations within a JSON Array:

     {
       "objectType": "verb",
       "id": "http://example.org/foo/verb",
       "value": "http://example.org/foo/verb",
       ...,
       "objects": [
         {
           "actor": "person",
           "object": "note",
           "target": "*",
           "targetRequired": true,
           "templates": { ... }
         },
         {
           "actor": "person",
           "object": "comment",
           "target": "*",
           "templates": { ... }
         }
       ]
     }

   Note that, to avoid possible ambiguity in a verb's definition, when
   multiple overlapping object combinations are specified, the most
   specific combination matching the actual instance of an activity will
   take precedence. For example, given the following set of
   combinations:

    {
       ...,
       "objects": [
         {
           "actor": "person",
           "object": "*",
           "target": "*",
           "targetRequired": false
         },
         {
           "actor": "person",
           "object": "comment",
           "target": "service",
           "targetRequired": true
         }
       ]
     }




Snell [Page 4]

                            Verb Definitions May 2012


   When an activity using the verb specifies an "actor" objectType of
   "person", an "object" objectType of "comment" and a "target"
   objectType of "service", the second Object Combination will be
   considered to apply. For all other combinations using an "actor"
   objectType of "person", the first Object Combination will be
   considered to apply.

   Note that Object Combinations are considered to be informative in
   nature only and do not represent every possible combination of object
   types for which the verb can be used. The sole intent of describing
   Object Combinations is to communicate information about how the
   described verb was originally intended to be used.

2.2. Templates

   Activity Objects are intended to provide a machine-readable
   representation of an event that has occurred. Often, however,
   systems require the ability to generate human-readable, localized
   descriptions of Activities. When working with a finite set of known
   verbs and objects with well defined semantics, generating such
   statements is relatively straightforward. However, because the
   Activity Streams format allows verbs and objectTypes to be extended
   in a completely decentralized manner, it becomes difficult for
   implementations to generate appopriate readable descriptions of all
   types of activities.

   To address this, "verb" objects can provide a collection of template
   strings organized both by Object Combination and Language that can be
   processed to generate appropriately localized and generally readable
   descriptive statements about the activity.

   Templates are expressed within a JSON Object whose property names are
   Language Ranges [RFC4647] and whose values are Strings of characters
   consisting of a mixture of localized literal values and specific
   replacement tokens wrapped in ASCII curly bracket characters ("{" and
   "}").















Snell [Page 5]

                            Verb Definitions May 2012


   For example:

     {
       "actor": "person",
       "object": "note",
       "target": "*",
       "targetRequired": true,
       "templates": {
         "*": "{actor} sent {object} to {target}",
         "de-*": "{actor} geschickt {target} das {object}",
       }
     }

   Implementations select an appropriate template to use by matching the
   Language Ranges provided to the appropriate target language for which
   the readable statement is to be generated. If multiple matching
   Language Ranges are provided, the most specific Range and associated
   template is selected.

   An implementation processing a template would replace each of the
   specific replacement tokens with a value adequately representing the
   referenced object. Typically, given no additional information about
   the object type in question, implementations SHOULD use the value of
   the "displayName" property, if present. The specific replacement
   tokens defined by this version of the specification are:

   +----------+--------------------------------------------------------+
   | Token | Description |
   +----------+--------------------------------------------------------+
   | {actor} | Replaced with a String value that describes the actor |
   | | object specified within the Activity. |
   | {object} | Replaced with a String value that describes the object |
   | | specified within the Activity. |
   | {target} | Replaced with a String value that describes the target |
   | | specified within the Activity. If a target object is |
   | | not specified within the activity, the {target} token |
   | | MUST be ignored and left unreplaced in the final |
   | | generated String value. |
   +----------+--------------------------------------------------------+

   Implementations are free to introduce additional replacement tokens
   so long as the label for each is an absolute URI reference. When an
   implementation encounters a template that uses a replacement token
   that it is unable to understand or replace with an appropriate value,
   the token SHOULD be ignored and left unreplaced in the final
   generated String value.

   Replacement tokens MUST NOT be processed recursively.



Snell [Page 6]

                            Verb Definitions May 2012


   The Strings generated by a template MUST be considered to be plain
   text and SHOULD NOT contain markup of any kind.

   If any given verb is known to be a hyponym or synonym of another verb
   for which a "verb" object definition is available, implementations
   MAY choose to utilize any templates defined within the definitions of
   those hypernyms and synonyms.

2.3. A Complete Example

   The following illustrates a complete example of a "verb" object
   definition:

     {
       "objectType": "verb",
       "displayName": "Send",
       "id": "http://example.org/verbs/send",
       "value": "http://example.org/verbs/send",
       "synonyms": ["http://example.org/verbs/deliver"],
       "hypernyms": ["give"],
       "objects": [
         {
           "actor": "person",
           "object": "note",
           "target": "person",
           "targetRequired": true,
           "templates": {
             "*": "{actor} sent {object} to {target}",
             "de-*": "{actor} geschickt {target} das {object}",
           }
         },
         {
           "actor": "person",
           "object": "note",
           "templates": {
             "*": "{actor} sent {object}",
             "de-*": "{actor} geschickt {object}",
           }
         },

       ]
     }

2.4. Verb Collections

   Collections of "verb" object definitions can be represented using the
   basic Activity Streams Collection serialization defined in Section
   3.5 of The JSON Activity Streams specification.



Snell [Page 7]

                            Verb Definitions May 2012


   For example:

     {
       "totalItems": 2,
       "items": [
         {"objectType": "verb", ...},
         {"objectType": "verb", ...}
       ]
     }

   When an individual "verb" object is considered to be part of a larger
   collection of verbs, it can include a special extension property
   named "$collection" whose value is the absolute IRI of a JSON
   document containing the full collection of verbs. This follows the
   conventions and requirements specified by the Links for Activity
   Streams specification. [links]

   Likewise, the special extension property "$self" can be used to
   specify the absolute IRI of a JSON document containing only the verb
   definition.

   For example:

     {
       "objectType": "verb",
       "$collection": "http://example.org/verbs/all",
       "$self": "http://example.org/verbs/send",
       "displayName": "Send",
       "id": "http://example.org/verbs/send",
       "value": "http://example.org/verbs/send",
       "synonyms": ["http://example.org/verbs/deliver"],
       "hypernyms": ["give"],
       "objects": [ ... ]
     }


3. Security Considerations

   There are no additional security considerations introduced by this
   specification.


4. License

   This Specification is made available under the Open Web Foundation
   Agreement Version 1.0, which is available at
   http://www.openwebfoundation.org/legal/.




Snell [Page 8]

                            Verb Definitions May 2012


   You can review the signed copies of the Open Web Foundation Agreement
   Version 1.0 for this Specification at
   http://activitystrea.ms/licensing/, which may also include additional
   parties to the authors.

   Your use of this Specification may be subject to other third party
   rights. THIS SPECIFICATION IS PROVIDED "AS IS." The contributors
   expressly disclaim any warranties (express, implied, or otherwise),
   including implied warranties of merchantability, non-infringement,
   fitness for a particular purpose, or title, related to the
   Specification. The entire risk as to implementing or otherwise using
   the Specification is assumed by the Specification implementer and
   user. IN NO EVENT WILL ANY PARTY BE LIABLE TO ANY OTHER PARTY FOR
   LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR
   CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF
   ANY KIND WITH RESPECT TO THIS SPECIFICATION OR ITS GOVERNING
   AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING
   NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS
   BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


5. Normative References

   [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, January 2005.

   [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
              Identifiers (IRIs)", RFC 3987, January 2005.

   [RFC4647] Phillips, A. and M. Davis, "Matching of Language Tags",
              BCP 47, RFC 4647, September 2006.

   [activitystreams]
              Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson,
              M., and R. Dolin, "JSON Activity Streams 1.0", May 2011.

   [links] Snell, J., "Links for Activity Streams", April 2012.










Snell [Page 9]

                            Verb Definitions May 2012


Author's Address

   James M Snell
   IBM















































Snell [Page 10]

Something went wrong with that request. Please try again.