Clarification: What is meant by "human readable"?

[canweriotnow]

I've been perplexed by the requirement of "human readable" definitions as the endpoint of Verb, Activity, etc. IRI id's, as my understanding was that the goal of the project was to build a portable and interoperable API for APs, LRSs, and software to interpret that data.

The interpretation of "human readable" I initially assumed (perhaps a mistake on my part), based on some of the ADL verb examples, was an HTML representation like this: http://adlnet.gov/expapi/verbs/terminated/

But perhaps I was overly narrow in my interpretation; for instance, here's the same data in a format that should be easily readable by both humans and machines:

{
    "terminated": {
        "properties": {
            "id": "http://adlnet.gov/expapi/verbs/terminated",
            "display": "The human readable representation of the Verb in one or more languages. This does not have any impact on the meaning of the Statement, but serves to give a human-readable display of the meaning already determined by the chosen Verb."
        },
        "verbMeaning": {
            "definition": "terminate (bring to an end or halt)",
            "authoritativeSource": "http://wordnetweb.princeton.edu/perl/webwn?o2=&o0=1&o8=1&o1=1&o7=&o5=&o9=&o6=&o3=&o4=&s=terminated&i=0&h=000000#c",
            "usage": "Ends the formal tracking of learning content, any statements time stamped after a statement with a terminated verb are not formally tracked."
        },
        "JSONRepresentation": {
            "id": "http://adlnet.gov/expapi/verbs/terminated",
            "display": {
                "en-US": "terminated"
            }
        }
    }
}

I'm further confused by https://github.com/adlnet/xAPI-Spec/pull/529#discussion-diff-22400368R776 which suggests that IRIs themselves, and not just the endpoints to which they refer, must have "human readable portions."

Let's say I had an IRI that referred to the ADL definition above indirectly; is http%3A%2F%2Fadlnet.gov%2Fexpapi%2Fverbs%2Fterminated%2F" less human readable than http://adlnet.gov/expapi/verbs/terminated?

I don't know. This emphasis on human readability for xAPI statement components utterly baffles me. I guess it comes down to a few areas of disambiguation:

• What does "human readable" mean in this context?
• What humans are going to be reading these things?
• What do we expect them to be able to read?
• Is there a "lowest common denominator" for "human readable"? Should we expect them to read at a college level? 8th grade? 5th?
• Does "human readable" inherently dictate a MIME type for content?
• Why on earth would humans (non-developers) be reading/accessing raw statements in the first place?
• If they can manage to make sense of the statements in order to follow those IRIs, doesn't that mean they can read JSON as well as HTML?
• Wouldn't it make more sense to ensure that whatever tooling these humans are using can consume the information and present it to them (as well as process it)?

I think the discussion of exploring JSON-LD in #577 if expanded to other areas of the spec might ameliorate some of these issues. But as I continue to develop software for xAPI, it would help to clarify what is meant by "human readable" and the rationale for it.

[fugu13]

I'm not the one to ask about the human readable URIs bit; my preferred approach is just to recommend people follow existing best practices for making good permanent URIs. Which seems to be all that's meant by making the URIs "human readable" by preference, it's just an awkward way to state it. It's there because, in practice, a lot of humans involved in creating statements and debugging xAPI stuff will be able to do so a lot better if the URIs give some hint as to what they're about instead of being totally opaque.

Btw, your example with all the percent encodings isn't an IRI.

[canweriotnow]

@fugu13 no, it's encodeURIComponent'ed - my point was about the possibility IRI containing an encoded IRI as a reference (for whatever reason).

But good permanent URIs - :+1:

I'm just trying to disambiguate this "human readable" thing...

[fugu13]

The discussion was very recent, you likely saw it; I'm confident my exposition is pretty much all that's meant by the term.

[aaronesilvers]

in practice, a lot of humans involved in creating statements and debugging xAPI stuff will be able to do so a lot better if the URIs give some hint as to what they're about instead of being totally opaque.

+1

-a-

---

mobile

Aaron E. Silvers | MakingBetter http://makingbetter.us/ 857.34.BEARD | @aaronesilvers http://twitter.com/aaronesilvers

Let’s meet! Pick a time https://doodle.com/makingbetter.

On Tue, Jan 6, 2015 at 3:09 PM, fugu13 notifications@github.com wrote:

The discussion was very recent, you likely saw it; I'm confident my exposition is pretty much all that's meant by the term.

— Reply to this email directly or view it on GitHub https://github.com/adlnet/xAPI-Spec/issues/578#issuecomment-68925447.

[garemoko]

Thanks for raising this Jason and to Russell for responding.

Jason, do you feel you now understand what human-readble means in this context? Do you (or anybody else) feel the spec needs any specific changes to make this clearer?

[aaronesilvers]

I think I get the challenge Jason is seeing. "Human readable" is, at best, ambiguous and therefore deficient to specify let alone derive conformance requirements for. 

It could be a SHOULD but how would an LRS or any system validating a statement behave if it encounters what t believes to be a non-human-readable statement?

Or maybe I'm putting words into Jason's mouth. We may understand it. How would we enforce it?

-a-

---

mobile

Aaron E. Silvers | MakingBetter

857.34.BEARD | @aaronesilvers

Let’s meet! Pick a time.

On Wed, Jan 7, 2015 at 5:56 AM, Andrew Downes notifications@github.com wrote:

Thanks for raising this Jason and to Russell for responding.

Jason, do you feel you now understand what human-readble means in this context? Do you (or anybody else) feel the spec needs any specific changes to make this clearer?

Reply to this email directly or view it on GitHub: https://github.com/adlnet/xAPI-Spec/issues/578#issuecomment-69006730

[aaronesilvers]

Note: I'm in favor of human-readable URIs as Russell described. How do we encourage that in the spec in a way that is clear, unambiguous and (heh) machine-readable ;) ?

-a-

---

mobile

Aaron E. Silvers | MakingBetter

857.34.BEARD | @aaronesilvers

Let’s meet! Pick a time.

On Wed, Jan 7, 2015 at 5:56 AM, Andrew Downes notifications@github.com wrote:

Thanks for raising this Jason and to Russell for responding.

Jason, do you feel you now understand what human-readble means in this context? Do you (or anybody else) feel the spec needs any specific changes to make this clearer?

Reply to this email directly or view it on GitHub: https://github.com/adlnet/xAPI-Spec/issues/578#issuecomment-69006730

[garemoko]

Making a list of offending parts of the spec:

• 4.1.3 id property in table The IRI should be human-readable and contain the Verb meaning.
• 4.1.3 requirements The IRI contained in an id SHOULD contain a human-readable portion which SHOULD provide meaning enough to disambiguate it from other similar(in syntax) Verbs.

I think that's it. All other mentions of "human readable" (less common) or "human-readable" (more common) relate to the display or language map properties which are human readable in the sense of learner/tutor/manager-readable rather than just developer-readable.

I'll re-word those two instances as part of #529 as follows:

• 4.1.3 id property in table delete that sentence entirely. It's covered by the requirements below.
• 4.1.3 requirements The IRI contained in an id SHOULD contain a human-readable portion which SHOULD provide meaning enough for a person reviewing the raw statement to disambiguate the Verb from other similar(in syntax) Verbs.

[garemoko]

As this is a SHOULD, it not something we'll be able to automatically test for conformance - it's a recommendation.

Will these changes resolve this issue?

[andyjohnson]

Sorry I'm late to the party, "human-readable" is certainly not going to be enforceable, rather just a guideline that someone reading just the IRI has some clue what it is representing. We don't want a verb vocabulary of 12 digit hex strings, which could be the easy way out for someone who just reads the "unique" requirement.

The way I feel about it is that if a consumer, developer, whoever sees an actor, verb id, and activity id could make some sense out of it. The actor of course could be obscured for security reasons, but the verb is key in my opinion. While we can lean on the "display" part of the Statement, I'd feel better knowing that the person coining the verb IRIs can take a role in controlling the direction of APs which may not use the display property effectively or consistently. The activity id being readable is useful in knowing if it is a quiz, test, simulation, etc., but where I think it really becomes important is if the activity is taking on the form of an object. Beating to death the "fired" example, I'd like to know if the object is a person, a missile, a gun, a kiln, etc. without having to query it or even expand the view.

To take it to one final level, I'd love to see a tool that is smart enough to allow manipulations of actors, verbs, and activities/objects in a UI that is smart enough to get rid of the "least human readable" parts and display only what is needed by the author.

This is a value-added proposition that I think is worth it!

[garemoko]

Is this resolved by #529 or does it need more work? If more work, what work?

[andyjohnson]

I think we are good in this issue unless there is anything else Jason wants to add.

On Wed, Feb 25, 2015 at 9:30 AM, Andrew Downes notifications@github.com wrote:

Is this resolved by #529 https://github.com/adlnet/xAPI-Spec/pull/529 or does it need more work? If more work, what work?

— Reply to this email directly or view it on GitHub https://github.com/adlnet/xAPI-Spec/issues/578#issuecomment-75968653.

Andy Johnson ADL Technical Team 608-318-0049

[andyjohnson]

Closing for 1.0.3, can re-open for 1.1 or later if needed.