clarifying the scope of JSON Activities spec

[Will Norris]

Besides some back-channel one-to-one correspondance I've had with a few folks, I haven't said much on the list lately about Google signing the OWFa for the JSON Activity Streams spec.  I actually have been working with our lawyers pretty consistently since before the spec was finalized, and I think we're getting close to the finish line.  

I'm pretty sure this is the first OWFa 1.0 that Google has looked at signing (I think we may have signed the OWFa 0.9 for something in the past), so our lawyers have been understandably cautious about it.  That, plus the general climate in the entire industry around patents over the last year or two, has certainly made this a challenging road.

After reviewing the OWFa 1.0 closely, as well as the language in the JSON Activity Streams spec itself, I think the only remaining issue that our lawyers have is regarding the stated scope of the spec.  From the very beginning, the Activity Streams spec has been pretty squarely focused on establishing a common data format for representing activities, not so much on how they are transmitted.  At one point, we even had a separate "Activities API" draft spec (https://github.com/activitystreams/activity-api) to handle that, since it was very explicitly not covered in the core spec.  Our lawyers have asked that the scope of the spec (the fact that it covers the data format, not transmission) be clarified in the text of the spec.  Fortunately, this only requires a minor tweak to the Abstract at the very beginning of the spec.  For reference, it currently reads:

This specification details the serialization of a stream of social activities using the JSON format. Activities are important in that they allow individuals to process the latest news of people and things they care about.

I'm proposing that this be updated to read:

Social activity data is important in that it allows individuals to process the latest news of people and things they care about.  This specification details the serialization of a stream of social activity data using the JSON format.  As this specification only describes that serialization format, the methods used to transmit, receive, or process that data are outside the scope of this specification.

This is still completely consistent with how we always intended the spec to be interpreted, it's just now a little more explicit.  But I think this would remove any remaining uncertainty our lawyers have around the spec.  Given how the OWFa works, I'm fairly certain that this change would require revving the spec to a v1.1 (or v1.0a if we wanted to take the OAuth approach).

Thoughts?

-will

[James Snell]

Hmm... at first blush this is actually rather disconcerting to me on
several levels but I'll focus on the text change suggestion for now...
quite honestly, I don't think a change should be necessary. The
current text clearly states that the "specification details the
*serialization* of a stream of social activities" (emphasis added) and
the spec never discusses any detail of how those serializations are
passed around. Hell, the spec doesn't even show a single example of an
Activity Stream being served up over HTTP and does not list any
normative dependencies on transport mechanisms. The scope of a
specification cannot be considered to cover an area the spec itself
does not address in any way, shape or form. I'm going to have to -1
this proposal.

- James

[Martin Atkins]

On 01/25/2012 08:58 AM, James Snell wrote:
> Hmm... at first blush this is actually rather disconcerting to me on
> several levels but I'll focus on the text change suggestion for now...
> quite honestly, I don't think a change should be necessary. The
> current text clearly states that the "specification details the
> *serialization* of a stream of social activities" (emphasis added) and
> the spec never discusses any detail of how those serializations are
> passed around. Hell, the spec doesn't even show a single example of an
> Activity Stream being served up over HTTP and does not list any
> normative dependencies on transport mechanisms. The scope of a
> specification cannot be considered to cover an area the spec itself
> does not address in any way, shape or form. I'm going to have to -1
> this proposal.
>

Right. The normative text of the specification is an unambiguous
description of its scope; anything the spec doesn't define is out of
scope by definition. The abstract is only there as a brief,
non-normative summary to someone browsing specifications to figure out
if this is even something worth reading.

If we wanted to grow the scope of the spec then that would necessarily
be a new version and thus a completely different OWFa agreement, so I
don't see any reason why the OWFa agreement would be signed in terms of
the abstract rather than the normative prose.

Therefore I'm not sure I can get on board with creating a new version
just to change the abstract, especially since that would technically
invalidate the four OWFa agreements that have already been submitted.

[Will Norris]

In many ways, I agree that such a change *shouldn't* have to be necessary... that common sense would state that anything not mentioned in the spec is, by definition, outside the scope of the spec.  

I believe the root question actually has more to do with the scope of the patent provision in the OWFa.  One thing that we talked about (and may still look into) was whether the OWFa itself could be updated to make that portion of the agreement clearer.  In the meantime, making the spec itself clearer in terms of its scope helps alleviate many of the concerns.  If any of this ever ends up having to be tested in court, having the spec more explicit is certainly safer.

With regards to the existing agreements, it wouldn't invalidate them.  They're still valid for the specific version of the spec that they were signed against.  For people implementing the spec, this change would be superficial so having some companies sign against a different version shouldn't be a problem.

All of this said, I am not a lawyer, so take it all with a grain of salt :)

[Martin Atkins]

On 01/25/2012 02:02 PM, Will Norris wrote:
>
> With regards to the existing agreements, it wouldn't invalidate them.
> They're still valid for the specific version of the spec that they
> were signed against. For people implementing the spec, this change
> would be superficial so having some companies sign against a different
> version shouldn't be a problem.
>

Common sense would dictate that this change is minor enough that the
existing agreements are still valid, but common sense would also dictate
that the scope of a spec would be a function of its normative prose
rather than its abstract.

So with that said, I think it's clear that we can't really predict how a
court case around this would play out in either case, so I don't see
this as a compelling reason to move forward with the abstract change.

[James Snell]

Will,

I'm sorry but going back and reading through the OWFa agreement again,
I still fail to see the issue.

From the OWFa 1.0 Agreement:

"8.4. Granted Claims. "Granted Claims" are those patent claims that
I own or control, including those patent claims I acquire or control
after the Date below, that are infringed by Permitted Uses. Granted
Claims include only those patent claims that are infringed by the
implementation of any portions of the Specification where the
Specification describes the functionality causing the infringement in
detail and does not merely reference the functionality causing the
infringement."

and

"8.6. Permitted Uses. “Permitted Uses” means making, using, selling,
offering for sale, importing or distributing any implementation of the
Specification 1) only to the extent it implements the Specification
and 2) so long as all required portions of the Specification are
implemented. Permitted Uses do not extend to any portion of an
implementation that is not included in the Specification."

To me, that's pretty damn clear. The scope of the OWFa only covers
exactly only those things the specification explicitly defines, no
more no less. In this case, the specification deals ONLY with the
Activity Streams data format. Therefore there is no way in which a
signed OWFa covering the Activity Streams specification could ever be
interpreted to apply to anything but the data format.

If the change truly is superficial, then it's absolutely pointless.

- James

[Will Norris]

sorry, I didn't actually complete that thought.  I meant that for most small developers, it's a superficial change.  For courts, it is a potentially meaningful change (or so my lawyers tell me). 

[Evan Prodromou]

On 01/25/2012 11:35 AM, Will Norris wrote:

I'm pretty sure this is the first OWFa 1.0 that Google has looked at signing (I think we may have signed the OWFa 0.9 for something in the past), so our lawyers have been understandably cautious about it.  That, plus the general climate in the entire industry around patents over the last year or two, has certainly made this a challenging road.

Are you sure? There's a whole list of Google-supported IP here:

http://www.openwebfoundation.org/announcements/introducingtheopenwebfoundationagreement

Am I misinterpreting something?

-Evan

[Evan Prodromou]

On 01/25/2012 11:58 AM, James Snell wrote:
> Hmm... at first blush this is actually rather disconcerting to me on
> several levels but I'll focus on the text change suggestion for now...
> quite honestly, I don't think a change should be necessary. The
> current text clearly states that the "specification details the
> *serialization* of a stream of social activities" (emphasis added) and
> the spec never discusses any detail of how those serializations are
> passed around. Hell, the spec doesn't even show a single example of an
> Activity Stream being served up over HTTP and does not list any
> normative dependencies on transport mechanisms. The scope of a
> specification cannot be considered to cover an area the spec itself
> does not address in any way, shape or form. I'm going to have to -1
> this proposal.

Yikes! Are we really going to endanger the future of this standard based
on the principle that lawyers are ridiculous?

My experience has been that when you get a bureaucrat or lawyer to say,
"We won't approve it unless you do meaningless task X, Y, and Z," the
best course of action is to do X, Y, and Z as fast as humanly possible
before they change their minds.

If the Google legal team has signed off on particular wording, I suggest
we run with it.

+1 on the change. StatusNet will re-sign if we need to.

-Evan

[Martin Atkins]

On 01/25/2012 03:01 PM, Evan Prodromou wrote:
>
> +1 on the change. StatusNet will re-sign if we need to.
>

It's the re-signing that concerns me, so if we can get everyone who
already signed on board with that then I'd revoke my objection although
it may add a small speed bump to my effort to get my employer to sign.

[Will Norris]

as far as I know, those were all under the OWFa 0.9.  The language is different enough with OWFa 1.0 to have raised some question with our lawyers.  As I mentioned, we're looking into that separately, so that we don't run into this with every spec Google participates in.

[James Snell]

Will... question: all specs could potentially have errata associated
with them (a la http://www.rfc-editor.org/errata.php ) ...
documentation of errata can be done without requiring publication of a
new version of the spec, and without requiring re-signing of the OWFa
agreements, etc. So the question is: if we simply documented the
abstract change as errata, would that be sufficient to deal with the
concern?

[Will Norris]

that's a really good question.  I'll look into it.

[Will Norris]

How are errata typically published?  Is it a separate document?  A new section added to the bottom of the existing document?  I believe different standards bodies do it differently (most of my interaction has been with OASIS, but we never published errata for the specs I worked on).  Given that we're not going through a standards body, I guess we have some flexibility in this regard.

Our lawyers are okay with adding this in an errata, particularly so that others don't have to re-sign the OWFa, but would prefer that it be part of the main document if possible.

-will

[Tantek Çelik]

W3C typically publishes errata as a separate (growing/live) document (see the status part of any popular/older spec for a link to its respective errata document).

Eventually if enough substantial errata are found, a working group may publish a "revised edition" (same version # but 2nd ed., 3rd ed.) for trivial errata (e.g. See XHTML 1.0), or a ".0.1 release" for non-trivial (functional changes that may affect implementations), e.g. see HTML 4.0.1. New features would require a full ".1" revision at a minimum, with last call, candidate rec phases of its own (e.g. see CSS 2.1).

For AS I suggest a separate errata document, especially as long as it is only non-normative changes, and adding a link from the AS 1.0 spec to the errata doc. When enough normative errata show up (expect it), we may want to consider a ".0.1" at some point.

Tantek

---

From: Will Norris <wi...@willnorris.com>

Sender: activity...@googlegroups.com

Date: Fri, 27 Jan 2012 14:19:52 -0800

To: James Snell<jas...@gmail.com>

ReplyTo: activity...@googlegroups.com

Cc: Evan Prodromou<ev...@status.net>; <activity...@googlegroups.com>; Chris Messina<chris....@gmail.com>; Monica Wilkinson<monica...@gmail.com>; Martin Atkins<ma...@degeneration.co.uk>; Rob Dolin<robd...@microsoft.com>

Subject: Re: clarifying the scope of JSON Activities spec

--
You received this message because you are subscribed to the Google Groups "Activity Streams" group.
To post to this group, send email to activity...@googlegroups.com.
To unsubscribe from this group, send email to activity-strea...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/activity-streams?hl=en.

[Will Norris]

The W3C model will work (thanks Tantek).  I'll put together a patch against the current spec that folks can look at.

[Will Norris]

hmm... given that Activity Streams doesn't have a Status section, thoughts on the best place to put the link to the errata?  At the end of the Abstract?  End of the Introduction?

[Tantek Çelik]

On Tue, Jan 31, 2012 at 06:41, Will Norris <wi...@willnorris.com> wrote:
> hmm... given that Activity Streams doesn't have a Status section, thoughts
> on the best place to put the link to the errata? At the end of the
> Abstract? End of the Introduction?

Suggestion: between the title, and before the abstract, put a line
like in CSS 2.1 <http://www.w3.org/TR/CSS21/>

Please refer to the errata for this document.

where "errata" is linked to the errata document.

e.g. here in the markup:

<h1><br />JSON Activity Streams 1.0</h1>
<p>Please refer to the <a href="errata.html">errata</a> for this document. </p>
<h3>Abstract</h3>

(withholding semantic commentary about an h3 following an h1 without
an intervening h2, ahem)

And then for errata.html, take a look at:

http://www.w3.org/Style/css2-updates/REC-CSS2-20110607-errata.html

and feel free to copy/update markup/styling accordingly.

Thanks,

Tantek

--
http://tantek.com/ - I made an HTML5 tutorial! http://tantek.com/html5

[Will Norris]

On Tue, Jan 31, 2012 at 12:07 AM, Tantek Çelik <tan...@cs.stanford.edu> wrote:

On Tue, Jan 31, 2012 at 06:41, Will Norris <wi...@willnorris.com> wrote:
> hmm... given that Activity Streams doesn't have a Status section, thoughts
> on the best place to put the link to the errata?  At the end of the
> Abstract?  End of the Introduction?

Suggestion: between the title, and before the abstract, put a line
like in CSS 2.1 <http://www.w3.org/TR/CSS21/>

 Please refer to the errata for this document.

where "errata" is linked to the errata document.

e.g. here in the markup:

<h1><br />JSON Activity Streams 1.0</h1>
<p>Please refer to the <a href="errata.html">errata</a> for this document. </p>
<h3>Abstract</h3>

unfortunately, xml2rfc doesn't allow us to add arbitrary text here.  The only thing I can figure is to add a paragraph to one of the existing sections (abstract, introduction?), or add a new section entirely as James suggested.

[Evan Prodromou]

So, where are we on this?

-Evan

[Will Norris]

sorry, I was out of town last week.  Since there's not an easy way with xml2rfc to add an errata section near the top of the document, I'll add one near the bottom. I'll ping the thread with the pull request once I have it so that folks can look at the exact changes.

On Tue, Feb 7, 2012 at 12:04 PM, Evan Prodromou <evan.pr...@gmail.com> wrote:

So, where are we on this?

-Evan

[Will Norris]

I've submitted a standard pull request so people can see the exact changes and comment on them: https://github.com/activitystreams/json-activity/pull/17

GitHub seems to be having some issues tonight, so if you can't see the diff there, you should be able to see the commit at https://github.com/willnorris/json-activity/commit/07f277fbb543fe99ba85c621549077858c7bf9bc

Previews of the generated docs with these changes:

  http://code.willnorris.com/json-activity/json-activity.html

  http://code.willnorris.com/json-activity/errata.html

[Will Norris]

no feedback on this before I submit it?  This basically implements everything we discussed, but would love a +1 from a few folks to make sure this is agreeable.  Then we should be one with this discussion.

-will

[James M Snell]

Looks fine. Still think it's rather silly, lol... But gotta love lawyers. +1

[Will Norris]

published:

http://activitystrea.ms/specs/json/1.0/#errata

http://activitystrea.ms/specs/json/1.0/errata