Structural validation with JSON-schema and JSON-LD Framing

JSON-LD community,
(CC Credentials Community Group & Badge Alliance)

In the Badge Alliance, we've been preparing a new draft of our Open Badges
spec that uses JSON-LD. We are experimenting with the idea of "extensions",
where badge issuers may collaborate on sets of additional properties to add
to badges. An extension is more than just adding new linked data properties
to a badge; it's about making sure that many issuers can add the same type
of data to a badge for a purpose, in a consistent manner, to make it more
likely that consumers would implement understanding those additions in
their products. See our draft here:
http://specification.openbadges.org/#Extensions

For example, a badge assertion itself would have a context at the top, and
an issuer may add an extension as an embedded JSON object (blank node) with
its own context link:

{
  "@context": "http://specification.openbadges.org/1.1/context.json",

  .... badges properties ....

  "extension:exampleExtension": {
    "@context":"
http://standard.openbadges.org/extensions/exampleExtension/context.json",
    "@type": ["extension", "extension:ExampleExtension"],
    "exampleProperty": "I'm a property, short and sweet."
  }
}

We wanted to be able to answer the question "did the issuer implement the
extension how the extension author intended?" For that, we turned to
JSON-schema (http://json-schema.org/), which allows authors to set out what
the structure of an extension should be so that implementers know what
properties must be includes, what data types are permitted, and have a
built-in validation method to ensure that they have correctly implemented
the specification.

Within the context for an extension, there is a obi:validation array that
contains references to different JSON-schema validators relevant to
documents that use the context.

{
  "@context": {
    "obi": "http://standard.openbadges.org/",
    "exampleProperty": "http://schema.org/text"
  },
  "obi:validation": [
    {
      "obi:validatesType": "obi:extensions/#ExampleExtension",
      "obi:validationSchema":
"http://standard.openbadges.org/extensions/exampleExtension/schema.json"
    }
  ]
}

The obi:validatesType property provides a key to what objects within an
Open Badge the obi:validationSchema applies to. Processors who want to take
advantage of the optional JSON-schema features would be instructed to
extract the JSON object(s) corresponding to the type from the input badge
object and process them against the schema.

The current approach (not finalized) instructed extension authors to write
JSON-schema based on the compact JSON input they expected to see. Manu
Sporny provided us some feedback that I'd like to discuss a little more
here, that we should use a JSON-LD frame to process the input JSON into a
compact form to be used as input to a JSON-schema validation process.

JSON-LD framing is powerful for a case like this. A simple frame like:

{
"@context:" "http://appropriatecontext.com",
  "@type":"extension:ExampleExtension"
}

...could pull out just the extensions that apply and test them.

The downsides of this approach are mostly around the difficulty of learning
JSON-LD and JSON-LD framing for developers. Without adding a JSON-LD
framing step to the validation process, implementations don't necessarily
need a JSON-LD processor as part of their Open Badges processing stack, but
if we add Framing, they will be required to include JSON-LD processing. In
addition, extension authors will need to learn Framing in order to write
validation features of extensions, and there are precious few examples of
JSON-LD frames in the wild, most from late 2011, and I don't know if they
are up-to-date. I've struggled to write any frame more complex than the
above, for instance, after 7 months of casually studying JSON-LD. While
some of the core Badge Alliance members may be able to provide some support
to extension authors, I don't want this to become a major impediment to the
growth of the specification.

However, what is more important is that we find a beautiful combination of
technologies that gives Open Badges and open credentials a productive long
future life. I'd love some feedback on connecting JSON-LD with JSON-schema,
and particularly about whether Framing should be included as a step in this
process.

*Nate Otto, Developer*
concentricsky.com