Re: Review of OBI Badges vocabulary

Thanks for this detailed review, Manu. I'll go through it point by point,
but as the weekly call is coming right up, let me just touch on a couple
larger points.

>  The vocabulary should be extracted out into a separate document.

> Everything else should go into an OBI spec (hosted, structure of
   badges, extensions, etc.)

This sounds agreeable to me and workable from a Badge Alliance perspective.
I'd love to spend a little time on today's call discussing how to factor
out pieces of this to reference from the Open Badges specification. For
example, should there be two separate context documents?

> Signing could just re-use the Linked Data Signatures specification.

One of the goals of the 1.1 Open Badges spec (the present document) was
backwards compatibility with the 1.0 specification, requiring JWS.
Simultaneously, we want to look forward to potential breaking changes that
are important to move open credentials forward. A good hard review of the
digital signing stack has got to be part of this, and the
JWS-with-revocation-list is up for criticism.

> JSON-LD context (v1.1)

> Lots of thoughts on the context, but don't have time to delve into all
> of them right now. Maybe that'll be a separate review. In general it
> looks like class names (words starting w/ caps) are intermixed with
> property names (lowercased names).

> The definition of 'type' is slightly
> confusing, unless the OBI type subclasses rdf:type.

The definition of type here is again for backwards compatibility with the
1.0 OBI spec (which was not intended to be JSON-LD) and was the only method
proposed to handle the different places in the 1.0 spec where "type"
appeared as a key. Most existing software that deals in badges is designed
to handle the raw JSON, not (yet) Linked Data. So, this definitely is is a
dirty component of this context. Identity type and verification type meant
slightly different things by the term. As the OBI moves toward a possible
breaking-change version, this would be the sort of thing I hope gets
cleaned up. Any feedback on how to handle a property that is
confusing/dirty now but could get adjusted later when there isn't a
commitment to backwards compatibility?

> obi:validation seems
> like it might need to use JSON-LD framing to work for non-trivial
> examples.
Would love to see a couple examples written out to talk about. I could help
contribute, but I'm not sure what the dividing line between cases that need
LD framing is. Diving into the framing documentation was a deep dive
indeed, one that the BA wasn't prepared to make extension developers do.

Thanks again,
 talk soon.

Nate

On 20 January 2015 at 06:27, Manu Sporny <msporny@digitalbazaar.com> wrote:
>>
>>> I took an action[1] last week to review the OpenBadges spec at:
>>>
>>> http://standard.openbadges.org/
>>>
>>> Here's the first rough review:
>>>
>>> > Open Badges Standard
>>>
>>> I don't think we should be calling this a standard yet. I know the BA
>>> wants to call it a standard, but that word means something special at
>>> the W3C, IETF, ISO, OASIS, etc. I think we'll get significant and
>>> unnecessary push-back from W3C comms and legal about this if we proceed
>>> w/ any language that positions this document as a standard. I know there
>>> is a disclaimer in the doc, but I don't think that'll convince W3C that
>>> people will understand the nuance that statement is drawing.
>>>
>>> > Portable digital credentials
>>>
>>> Badges, credentials, microcredentials - we need to get our terminology
>>> straight between the groups.
>>>
>>> > embedding it into portable image files as digital badges
>>>
>>> The image file thing is a non-goal for Digital Bazaar, maybe we can
>>> reword it to "optionally embedding"? The important bit is the data
>>> format, not where you can stuff the data format, no?
>>>
>>> > JSON-LD context (v1.1)
>>>
>>> Lots of thoughts on the context, but don't have time to delve into all
>>> of them right now. Maybe that'll be a separate review. In general it
>>> looks like class names (words starting w/ caps) are intermixed with
>>> property names (lowercased names). The definition of 'type' is slightly
>>> confusing, unless the OBI type subclasses rdf:type. obi:validation seems
>>> like it might need to use JSON-LD framing to work for non-trivial
>>> examples.
>>>
>>> > They are published as JSON for interoperability.
>>>
>>> Why not as JSON-LD?
>>>
>>> > Badge Baking Hosted Verification Signed Verification
>>>
>>> This sort of content isn't usually found in a vocabulary document. It's
>>> a part of a spec, like the Identity Credentials spec. I suggest moving
>>> this stuff out to a separate document.
>>>
>>> > Hosted Verification
>>>
>>> I think we should be focusing solely on digital signatures for
>>> verification. The whole hosted model is very problematic when you start
>>> working with credentials that are mission critical.
>>>
>>> > Signed Verification
>>>
>>> -1 to JWS:
>>>
>>> http://manu.sporny.org/2013/sm-vs-jose/
>>>
>>> > Assertion
>>>
>>> > uid
>>>
>>> You don't need a UID if you follow Web Architecture principles. There is
>>> just an identifier, which is a URL. That is both globally unique and the
>>> identifier can be generated locally.
>>>
>>> The question is whether to map this to @id, or to have a new 'id' value
>>> that is a URL and relegate uid to "legacy" status.
>>>
>>> > recipient
>>>
>>> +1 for this language over credentialee
>>>
>>> > badge
>>>
>>> The fact that both recipient, badge, and a few other properties are both
>>> machine-readable and change is bad news for deep validation of badges.
>>> This is going to cause a huge problem for digital signatures on badges.
>>>
>>> We're either going to need both 'badge' and 'badgeHash', or you're going
>>> to need to deep nest the IdentityObject, BadgeClass, and
>>> VerificationObject. If you don't do that, for example, the BadgeClass
>>> could vary wildly over time w/o invalidating the digital signature
>>> (which it should).
>>>
>>> > verify
>>>
>>> Again, I disagree with this approach to verification. The Hosted model
>>> is not something that Digital Bazaar would be interested in supporting
>>> in any other way than legacy support.
>>>
>>> > issuedOn - DateTime - Either an ISO 8601 date or a standard 10-digit
>>> >  Unix  timestamp.
>>>
>>> no unix timestamps, they're incredibly difficult to read/debug and don't
>>> really provide any benefit these days. Make the dates and times human
>>> readable.
>>>
>>> > This must be a PNG or SVG image, and should be prepared via the
>>> > Baking specification.
>>>
>>> -1 to Badge Baking being in the vocabulary document, or a core
>>> specification.
>>>
>>> > IdentityObject
>>>
>>> > identity
>>>
>>> This should be an IRI or URL. Assigning badges to people's names is fine
>>> for low-value badges, but again, Digital Bazaar doesn't really have an
>>> interest in low-value badges.
>>>
>>> > type
>>>
>>> Could be confused with rdf:type and JSON-LD's @type. E-mail addresses
>>> make bad long-term identifiers.
>>>
>>> > hashed
>>>
>>> -1 to hashed identifiers. Identifiers, especially in Linked Data, need
>>> to be dereference-able.
>>>
>>> > VerificationObject
>>>
>>> Verification should be digital-signatures based. We could still support
>>> this for legacy purposes.
>>>
>>> > BadgeClass
>>>
>>> +1 to the content of a BadgeClass, but why not move most of this up into
>>> the top-level badge object? Doing so saves a great deal of headache wrt.
>>> verifying the digital signature because you push developers to include
>>> all of the important information in the badge itself (without requiring
>>> an external dereference to figure out if the badge is valid).
>>>
>>> > IssuerOrganization
>>>
>>> > image
>>>
>>> markup looks malformed.
>>>
>>> > revocationList
>>>
>>> If we used URLs to identify badges, just dereferencing the badge URL
>>> would enable you to see if it was revoked or not.
>>>
>>> > For example, if the issuer at example.org wants to add a foo
>>> > property to the assertion, the property name should be example:foo,
>>> > or preferably a dereferencable IRI describing the property, such as
>>> > http://example.org/foo.
>>>
>>> "example:foo" would be dropped by a JSON-LD processor that doesn't have
>>> "example:" mapped. The digital signature wouldn't cover the property. In
>>> fact, things that don't map to the JSON-LD context are not going to be
>>> signed and are thus not protected from tampering. This bit looks like it
>>> needs more work as I think it creates a security hole in the spec.
>>>
>>> > Signed Badges
>>>
>>> Agree that signed badges are very important, disagree that JWS is the
>>> best path forward.
>>>
>>> In general I think the following changes need to be made to the
>>> specification:
>>>
>>> 1. The vocabulary should be extracted out into a separate document.
>>> 2. Signing could just re-use the Linked Data Signatures specification.
>>> 3. Everything else should go into an OBI spec (hosted, structure of
>>>    badges, extensions, etc.)
>>>
>>> Unfortunately, there are a number of contradicting opinions above, so
>>> we'll need some discussion to tease out where the group wants to go with
>>> things like flat badges vs. nested information wrt. digital signatures.
>>> Whether or not extensions need JSON-LD framing, or if we just require
>>> extensions to do shallow nesting + JSON Schema checking against
>>> compacted JSON-LD data for now. We may also want to talk about freezing
>>> 1.1 and ensuring that the entirety can be expressed in an Identity
>>> Credential and then move to the Identity Credentials format for OBI 2.0?
>>> Just some food for thought, talk w/ everyone on the call tomorrow.
>>>
>>
>> +1 to everything
>>
>> Though I can see why you would want hosted badges.  Some badges may not
>> have the need for portability and just live on a (COOL) URI.  Hosting some
>> static content is easy for most publishers.  They can always be made
>> portable later with a signature.
>>
>>
>>>
>>> -- manu
>>>
>>> [1] http://opencreds.org/minutes/2015-01-13/#88
>>>
>>> --
>>> Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
>>> Founder/CEO - Digital Bazaar, Inc.
>>> blog: The Marathonic Dawn of Web Payments
>>> http://manu.sporny.org/2014/dawn-of-web-payments/
>>>
>>>
>>
>