defines badgeClass in JSON-schema, sample extension, & sample badgeClass

[ottonomy]

I started with a sample badgeClass, including a simple badgeClassExtension that allows issuers to define an age target in years or US standard grades (as human readable strings like "6-12" or "P-20").

Initially I used @kayaelle's example from /issues/8 but I made a couple small changes that I think might help the extensions work better with JSON-schema.

I made each extension, as included in the badgeClass, be an object with two properties ("badgeSpecification" and "content") rather than just a "badgeSpecification" object followed by more properties that vary depending on the extension. I think for validation, we will want to compare the "content" object to the schema at the reference URL defined in badgeSpecification["reference"].

Please correct any errors you might find, and investigate any changes that would improve things.

Hopefully ya'll don't mind my folder structure. I put these in a folder for JSON-schema based exploration, thinking others could create separate folders for JSON-LD and current-spec style namespaced properties.

[ottonomy]

Another issue I came across, is that @kayaelle suggested "reference" and "version" for badgeSpecification, and I couldn't think of how to use those both together to locate the proper schema JSON. Instead, I think it might be better to include the version in the reference, as shown by schema-age-target-v0.5.json

But if there are any design patterns out there showing a better way, post post post!

[kayaelle]

Thanks for taking a stab at this @ottonomy! I'm going to digest a bit and get back to it.

[ottonomy]

I met with @kayaelle and @brianloveswords on Friday, and incorporated a couple naming suggestions from Brian into this commit:

Namely, renaming the extensions array "extensions" and to make the two objects in each extension the "schema" and "content" rather than a more complicated name, "badgeSpecification"

I have a few other ideas to commit for discussion:
*A method to add a SHA1 checksum of the schema file to the badgeclass so that validators don't need to re-download previously cached schemas but can still ensure they got the right version.
*Generalizing this extension method so that it can be used with assertion, issuer objects, etc.
*Two ideas for signed endorsement: (1) the endorsement of a badgeClass by an outside party, which would also allow organizations to verifiably certify that an issuing platform is acting on their behalf; and (2) the endorsement of a particular issued badge (assertion) either as it is issued or added to the assertion after the fact.

I think these things should probably be part of their own pull requests, but let me know if you think I should start committing them into this branch instead.

[andrewhayward]

I'm not entirely convinced that schema needs to have more than a reference to the actual schema being used. As @ottonomy already pointed out, including a version here is weird, as the URL can only point to a single instance of a schema, and having the title in there seems like dangerous redundancy.

[kayaelle]

@andrewhayward brings up a good point. Since the title is in the schema itself, it seems to belong just there and not in the reference.

Also agree that the version may not be the right thing for what we're trying to accomplish.

@ottonomy Thinking it would be helpful for discussion to see your method to add a SHA1 checksum of the schema file to the badgeclass in the code. I'm wondering what thoughts on it may be on using that to version each schema reference vs or in addition to versioning the badge class.

[ottonomy]

@kayaelle @andrewhayward: I'm coming around rapidly to your viewpoint on dropping title (and version) from the badgeclass end of the spec. I think initially, I was trying to focus on making this more human readable, but humans have never really read badgeClasses directly, and they are unlikely to start as the tools develop. Having extra junk in the badgeClass adds more failure points and confusion. @kayaelle, I'll pull request my branch on adding schema checksums here in a moment.

[ottonomy]

...and I made a quick change to the schema-hash branch pulled in #13 to remove title and version properties from the schema object in each extension to see how you two like it.