Re: Structural validation with JSON-schema and JSON-LD Framing

Fun! I was just looking at some JSON that I wanted to write JSON-LD for and
I turned to a JavaScript Developer wondering what "$ref: "Relationship""
meant. It turned out that he thought I was reading JSON Schema. Maybe we'll
intersect someday. FWIW it was here (
https://github.com/openvocab/ovn/blob/master/vocab/Agent.js).

-Brent Shambaugh

Website: bshambaugh.org

On Mon, Mar 9, 2015 at 5:16 PM, Nate Otto <nate@ottonomy.net> wrote:

> 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
>