RE: Draft specification for LRMI serialized as JSON-LD

[Joshua Marks]

Looping in the accessibility group (“A11Y” as they call it). -> a11y-metad...@googlegroups.com

 

With regard to the topic, it is important to have a workable implementation for LR, so I feel it is important for this work to move forward. I however am not able to provide much useful input on the issues identified and aired (yet).

 

Joshua Marks

CTO

Curriki: The Global Education and Learning Community

jma...@curriki.org

www.curriki.org

US 831-685-3511

 

I welcome you to become a member of the Curriki community, to follow us on Twitter and to say hello on our blog, Facebook and LinkedIn communities.

 

From: lr...@googlegroups.com [mailto:lr...@googlegroups.com] On Behalf Of Jason Hoekstra
Sent: Wednesday, September 18, 2013 9:26 AM
To: lr...@googlegroups.com; learnin...@googlegroups.com
Subject: Re: Draft specification for LRMI serialized as JSON-LD

 

Hi all -

 

I've heard a few private comments and additions to the LRMI JSON-LD specification sent out late last Friday.  It would be helpful to hear publicly what we as a LR / LRMI community feel on moving this forward.  I know in most cases silence can mean folks are okay with no comments on the work, but would be good to get a sense if this is the right direction to move forward in.

 

Also, recently I've heard there is some work being done around accessibility and schema.org.  I'd be happy to extend another section into this with accessibility in mind if that would be useful as well.

 

Lastly, this would be good conversation to precede the LRMI tagging workshop in Denver on Sunday.  Please provide any initial thoughts here which we can use to work the details Sunday-Tuesday at EdNET.

 

Thanks,

 

Jason

 

 

 

On Fri, Sep 13, 2013 at 8:18 PM, Jason Hoekstra <jasonh...@gmail.com> wrote:

Thank you to the number of people which have contributed to the discussion of serializing LRMI metadata into JSON-LD in the past weeks.  As we've learned this year, the JSON microdata format for LRMI isn't ideal as hasn't been yet adequately described in specificity for JSON as it has been for HTML usage.  JSON-LD fits use cases for standalone JSON such as consuming and retrieving from the Learning Registry well as designed with this purpose in mind.

 

Based on exploration of the JSON-LD specification and feedback from the LRMI mailing list, below is a draft specification of LRMI in JSON-LD.  Please note, a Word template was used here to maintain formatting for best readability and fast editing.  Once we finalize the specification, we can look at to publishing in web or GitHub formats as well.

 

Below is the link to the draft specification:

 

http://goo.gl/G4wD1P

 

Please do comment on the list publicly of any recommendations, edits, additions or corrections to this document.  Feel free to send back the Word document to me directly to incorporate in-line changes.

 

Looking forward to your feedback,

 

Jason

 

Note: cross posting to LRMI and Learning Registry Dev lists as interest to both communities.

 

--
You received this message because you are subscribed to the Google Groups "Learning Resource Metadata Initiative" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lrmi+uns...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Jason Hoekstra]

Thanks Josh and hello A11Y group,

Recently on an LR / LRMI web conf, someone displayed the A11Y Schema.org / LRMI proposed extensions.  Given JSON-LD supports multiple contexts, I'd like to take a shot at including that into this specification as an additional section.  Given LRMI / EdNET is this week, it may take a week or more to get that work done just to set expectations.  However once done, will bounce back around to the group for review.

Curious if anyone has that the link with the accessibility attributes available for reference to include into this?

Thanks,

Jason

[Jason Hoekstra]

Also as I've received some feedback offline, I've updated the spec doc.  The changes are the in the @graphs section with the @id[s] correctly referencing the the intended resources.  Please do email additional comments here to the group.

https://www.dropbox.com/s/1zbjetron1ye25m/LRMI-JSONLD-Spec-v11.docx

Thanks,

Jason

[Rob Koberg]

For String data type values, perhaps it should be mentioned or an
example placed in the description property where the string is
double-quoted Unicode, with backslash escaping. (or maybe it is
plainly obvious?)

> "Learning Registry Developers List" group.

> To unsubscribe from this group and stop receiving emails from it, send an

> email to learningreg-d...@googlegroups.com.

[Jason Hoekstra]

Hi Rob - that sounds like a good idea.  Certainly makes sense as both LRMI and LR projects are meant to support content worldwide.  I personally don't work much with unicode, could you help provide an example of what this may look like?  I know that Python for example has ' u"unicode string" ', but unfamiliar in the JSON context.

Thanks,

Jason

[Rob Koberg]

On Sat, Sep 21, 2013 at 12:52 PM, Jason Hoekstra
<jasonh...@gmail.com> wrote:
> Hi Rob - that sounds like a good idea. Certainly makes sense as both LRMI
> and LR projects are meant to support content worldwide. I personally don't
> work much with unicode, could you help provide an example of what this may
> look like? I know that Python for example has ' u"unicode string" ', but
> unfamiliar in the JSON context.
>

It is probably the same. Most languages will be able to output to the
JSON spec. In other words, don't rely on manual/arbitrary string
concatenation. Keep your payload in an object or array (depending on
your language or preferences) and then output the JSON from a well
known library.

But for example, a less than sign is \u003C and a greater than sign is
\u003E, so a BR element (<br/>) would look like:

\u003Cbr/\u003E

when escaped for a JSON string value.

[Jason Hoekstra]

Updates to come:

* Thanks Steve and Dave for the input into the recommendation categories.  Using "strongly recommended" feels like a good middle ground to denote this is a valuable attribute, however not forcing the usage if the metadata is not available.  Some of the required attributes (@content, @type, @id) for example) in my opinion should stay as it is core to signifying this is a JSON-LD document as opposed to other types.

* Rob's guidance on explicitly state unicode support into this specification.  As Michael said today in the LRMI workshop, a lot of his work on behalf of the LRMI community is also engaging the international community to make clear LRMI is designed as an international standard, so the unicode guidance is useful in supporting that.

* Accessibility metadata guidance as another section into the specification.  Also Dave and Michael mentioned today in the workshop, there is a set of professional development standards which will also be helpful to fold into this (a number of the PD publishers we work with have been asking for this, so really good timing).

Thanks all for the feedback into this.  I know many of us are looking to close the door on serialization so we can move "higher up the stack" to the tools and application of the metadata work to further empower learning with digital resources.  Further feedback is encourged, either related to this or any other thoughts in regards to LRMI data formats.

Jason

On Sat, Sep 21, 2013 at 7:18 PM, Steve Midgley <steve....@mixrun.com> wrote:

I think Dave has a good point regarding "name" -- it seems like "name" is not structurally required to make the metadata work? From that perspective, I'd also vote that "name" field be marked "recommended" instead of "required." 

Jason, maybe you want to further distinguish between "required" and "recommended" - meaning some recommended fields are actually a best practice to use and the publisher should expect to break (ie be excluded from) some consumers if they don't use it. For those fields, maybe add a third category of "strongly recommended" or something like that?

I'd propose that "name" and "description" should both be "strongly recommended" and all the other fields are optional or just recommended..

I love the format of this spec, in that each section is a stand-alone, clear example of what the metadata should look like. 

Steve

On Fri, Sep 20, 2013 at 10:46 AM, <finke...@gmail.com> wrote:

I wasn't sure where we were supposed to post comments about the draft and wasn't sure if I was supposed to post here since no one else has but I just wanted to point out two things that caught my attention

I don't quite understand the purpose of the @id element. Currently for microdata, NSDL puts in an internal unique id into an attribute called id. This is so we can reference back to it if needed for updates. In the document it says "highly recommended defined as a URI". Can anyone elaborate why this should be. If someone decides to post the same url a few times because they have different revisions of it its not really unqiue anymore. If this attribute isn't going to be used by consumers of the data why can't @id be defined as required but say "default it to the URI" if you have no unique identifier for it.

name is required. I never read past LR LRMI specs that said anything is required within the payload. Why is this changing now? Shouldn't the node/consumer decide if it wants to consume a LRMI record  that doesn't have a name. NSDL has a small amount use cases where we don't have name to but we still want to submit it to the LR.


thanks, hopefully i posted in the right spot
Dave - NSDL Developer

--
You received this message because you are subscribed to the Google Groups "Learning Registry Developers List" group.
To unsubscribe from this group and stop receiving emails from it, send an email to learningreg-d...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to the Google Groups "Learning Registry Developers List" group.

[Martin Quiazon]

Hi Jason,

Thanks for a clear and pragmatic draft spec. We've been working on our own submissions to the Learning Registry which incorporates the work done by both LRMI and the A11y Metadata Project.

Here's a sample document that we've pushed up to the Learning Registry sandbox, where we've used the @context mechanism for LRMI's useRightsUrl property as well as the CreativeWork extensions proposed by the A11y Metadata Project.

http://sandbox.learningregistry.org/obtain?request_id=1ea9cc34149342fb9807d0d4015eeacf&by_doc_ID=T

-martin

[Jason Hoekstra]

Hi all -

After being able to find some focus time this weekend, I've made updates to the LRMI JSON-LD specification based on feedback from multiple parties both on and off lists.  Thank you all for the thoughtful contributions.  I've done my best effort in consolidating those insights; please let me know if I've mischaracterized or made any mistakes from your information.

LRMI JSON-LD v1.5:  https://www.dropbox.com/s/4pkei3w9ykyw5sn/LRMI-JSONLD-Spec-v15.docx

The updates contained within:

*** v1.2 - Jim Klo @ SRI had a number of fine-detail adjustments and improvements.

a.)  Define JSON-LD document using the @vocab construct as a @context document has not yet been defined at schema.org.  

b.)  Correcting mistake in educationAlignment(s) to use scalar values per alignment instead of array to properly align targetUrl attributes if specified.

c.)  Added @type of AlignmentObjects on educationAlignment(s).  

d.)  Removed @id as shorthand definition of “url” allows attribute to serve both.  

*** v1.3 - Rob Koberg - added text specifying JSON Unicode support and escaping.

*** v1.4 - Dave Finke @ NSDL - Changed Schema.org “name” to "recommended" recognizing not all learning object collections have titles for the items.  Learning Registry envelope addition of “JSON-LD” along with “LRMI” within “payload_schema” to clearly denote payload format.

*** v1.5 - Martin Quiazon @ Benetech - A11Y example of JSON-LD vocabulary extensions.

Please do review and let me know if there are additional comments or improvements.  It is preferred to reply to this thread back directly.

Thanks,

Jason

PS - There have been a few notes regarding Word format, at this point its easiest for me to work with in formatting and updates while delivering high readability.  Certainly open to other formats (HTML, GitHub Pages, etc) going forward if someone is familiar on how to convert while retaining similar formatting in this document.

On Tue, Oct 1, 2013 at 6:21 PM, Steve Midgley <steve....@mixrun.com> wrote:

Yeah - double plus for including "JSON-LD" in the payload_schema field - good catch Dave. That's actually really important.

Just to give a little background, that field allows LR consumers to find only metadata that they know how to consume/process. Providing additional detail such as LRMI and JSON-LD would help a lot for those consumers. If there is an IANA media type available (or more than one) for the format and binding, it's helpful to include that too - that's where the "application/microdata+json" comes from I think. I don't there's a media type available for schema.org yet, let alone schema/lrmi bound to JSON-LD!

Steve

On Tue, Oct 1, 2013 at 2:00 PM, <finke...@gmail.com> wrote:

I just wanted to add two things that I noticed about the JSON-LD draft while I was implementing publishing JSON-LD to sandbox. One of which I mentioned to Jason while he was in town.

1) In the example in the document I would think educationalRole should also be added as an extra context since it is not contained within CreateWork spec. So I was assuming the example would look like this if both useRightsUrl and educationRole attributes needed to be published

        {

            "lrmi": "http://lrmi.net/the-specification#",

            "useRightsUrl": {

                "@id": "lrmi:useRightsUrl",

                "@type": "@id"

            },

          
           "educationalRole ": {

                "@id": "lrmi:educationalRole",

                "@type": "@id"

            }

        },

2) When publishers were publishing as microdata. Everyone was setting their payload_schema to

"payload_schema": [

• "schema.org",
• "LRMI",
• "application/microdata+json"

],
In the JSON-LD document it mentioned that it would be just
"payload_schema":"LRMI"

I wonder if it should be a little more specific, so we can tell without even looking at the payload @context that its JSON-LD. Maybe something like

"payload_schema": [

• "LRMI",
• "JSON-LD"

]

The advantage to doing this would enable the nodes to exclude records that are of type JSON-lD if they choose to via filters. Help the consumers of the record be able to tell how to extract the payload without looking in the @context and guessing and finally enable users to filter only for JSON-LD records when querying a node.

Dave - NSDL

--
You received this message because you are subscribed to the Google Groups "Learning Registry Developers List" group.
To unsubscribe from this group and stop receiving emails from it, send an email to learningreg-d...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

[Jason Hoekstra]

Hi Dave -

Thanks for the recommendation on defining educationalRole inline as well.  Wanted to check in before documenting --- I noticed the LRMI spec specifies that educationalRole is a new EducationalAudience class under Schema.org/Audience.  

Given its now defined by Schema.org (beyond LRMI), but outside of the @type CreativeWork scope, is there another shorthand or definition structure that should be used?

Thanks,

Jason

PS - many thanks for the recommendation on adding both "LRMI" and "JSON-LD" to the LR envelope "payload_schema" attribute - that will be a very helpful filter, as you mention, once publishers being releasing in this format.

[finke...@gmail.com]

For educationalRole I'm not really sure what it should be. In the LRMI spec it says "New class EducationalAudience created under Schema.org/Audience" but then for expected type it says "schema.org/Text". So I'm not positive which way they meant it and why "audience" which is part of CreativeWork was not used instead. The definitions look identical.  Hopefully someone else that understands the LRMI spec a little more can clarify.

Everything that you changed looks good but I was hoping to understand
"c.)  Added @type of AlignmentObjects on educationalAlignment(s).  "

I noticed that was added and it makes sense but I cannot figure out why @type was only added for educationalAlignments but not for publisher. Since both are defined in CreativeWork as an object. This would also go for other properties that are not in your examples (author, encodings, contributor, copyrightHolder etc..)

thanks
Dave - NSDL