How we name things is potentially confusing

[dauwhe]

to express "address" we use "url" in the manifest
to express "title" we use "name"
to express "canonical identifier" we use "@id"
to express "publication date" we use "datePublished"
to express "default reading order" we use "readingOrder"
to express "resource list" we use "resources"
to express "language" we use "inLanguage"

I know we inherited some of this terminology from schema.org, but basically everyone will have to look up what manifest term is used for each concept. There is no pattern.

[HadrienGardeur]

An alternate approach would be to map such properties using our JSON-LD context.

This is the approach that was adopted for Readium, you can take a look at the context document.

[iherman]

I sympathize with the feeling, but I am not sure about a complete renaming.

We know that the metadata we use here is a subset of what schema.org provides. We also know that there are quite a number of additional schema.org properties that publishers/authors MAY want to use that we do not talk about here; after all, we do not want to reproduce the full schema.org manual. Take, as a random example, the term license, defined on CreativeWork instances and which are, as a consequence fine terms to use in our manifests in practice.

What this means in practice is that our authors may want to look at the schema.org documentation and examples for further inspiration for terms; in that case these mapping will become a drag. Much as I do not like name for the usage of title, the disconnect within our document seems to be the lesser evil.

Another approach we could take (all my hopes are in @mattgarrish...) is to reformulate the general part of the spec, and reuse, as much as we can, the schema.org terms in the general text, too.

One such general remapping, via the context, that we may want to do nevertheless, is to remove the @ characters. Use value instead of @value, id instead of @id, etc. The extra bonus is that it would make the specification of the life cycle smoother (something that we discussed, separately, already).

[HadrienGardeur]

We also know that there are quite a number of additional schema.org properties that publishers/authors MAY want to use that we do not talk about here; after all, we do not want to reproduce the full schema.org manual.

We took a different approach in Readium as well:

• we only declare a single context document (our own) instead of two references (our own + schema.org)
• but out context document contains a reference to schema.org: "schema": "https://schema.org/"

This gives us access to all schema.org terms, for example for https://schema.org/license we can use schema:license.

This gives us better consistency and naming for our core metadata, without losing the ability to reference schema.org as an extensibility mechanism.

[laudrain]

I don't mind about technical terms, as soon as they come from standard specifications.
BTW, all non native English speakers have to use terminology that are not what they use in their native language.

[iherman]

@HadrienGardeur per
#312 (comment), I do not really understand why that setup would change anything significantly on this issue. We can put into our context whatever we want and we would get to the same result.

[HadrienGardeur]

@iherman it's a different approach:

• prioritize clarity by using terms that are closer from what we use in the publishing industry (title vs name, narrator vs readBy) and mapping them back to schema.org
• allow additional schema.org terms but clearly identify them as such

There are pros and cons for both solutions, just pointing out how Readium handled this differently.

[iherman]

I have played with the google structured data checker (again...) and it is clear that a remapping of, say, title to name is certainly possible.

(That being said, their tool seems to be problematic: it does not read our context file from www.w3.org/ns, it reports an error, whereas if the context file is copied verbatim it is fine. I have sent them a feedback on this.)

Note also, b.t.w, that the mapping type->@type is part of the schema.org context file (alongside id->@id) already.

[RachelComerford]

To make sure we're all on the same page (and in hopes we can get some new voices on these threads), is this accurate?

Problem Statement: The terms/tags required for use in the manifest may not maintain a recognizable relationship to their meaning or a pattern, making it difficult to remember/apply them.

Who is impacted? Anyone 'authoring' (building) the wpub (including those who need to interpret the spec for 'authors')

Qualifier to take into account: Non-native english speakers may experience this issue, or something similar, no matter what the tags are.

Potential Solutions to consider:

• Apply a pattern to the tags so that there is a consistent experience
• prioritize clarity by using terms that are closer from what we use in the publishing industry (title vs name, narrator vs readBy) and mapping them back to schema.org and allow additional schema.org terms but clearly identify them as such
• map all the properties using our JSON-LD context (hiding the complexity from the content author?)
• reformulate the general part of the spec, and reuse, as much as we can, the schema.org terms in the general text, too

We have a number of publishers and publishing vendors in this group that haven't yet weighed in on this but this will impact the ease with which they build wpubs. If the above is accurate, I would like to email it to some of these members for feedback that I'll happily add to this thread.

[mattgarrish]

I don't like a lot of the schema.org names, too, but like Ivan says, I'd rather know exactly what schema.org property I'm using than have to dig for a context document to figure out what a property re-maps to. And I highly suspect that authors are going to get confused by our revised naming and try to add already-mapped properties to the manifest and not understand why they're getting errors.

Plus it just tends to defeat the point of a common vocabulary like schema.org if everyone goes around renaming properties whenever they don't suit them. And maybe we should request new names for some of the real stinkers, like "readBy".

But I also suspect there is a way we can highlight the property names to bring them to the fore, whether it's in the property section titles, through a mapping table in the specification, etc.

[iherman]

This issue was discussed in a meeting.

• RESOLVED: remove the ‘@’ from keywords; leave other terms as they are

View the transcript

Garth Conboy: #312 (comment)
Garth Conboy: The last issue, Rachel summarized in the comment provided, this was an issue Dave raised. Is anyone in a good position to summarize?
Dave Cramer: Because we’re inheriting tons of terminology from schema.org they have set names for items, that don’t always match up with publishing, what we call a title, schema calls it a name. So a book title would have to be a “name” so there is a bit of resistance that the common terms different from what we have to call things in the manifest. Not sure what we can do about it, but it makes our spec harder to understand.
Garth Conboy: Is this an area we need to be more explicit about?
Dave Cramer: Everything we can do in our spec prose to help our readers understand - to express language we use IN language… We should be really aware of as we write text here.
Ivan Herman: To be clear, technically speaking, if we use JSON LD, it is possible to rename those terms to our own liking by extending the wpub context file. I must admit that if we are getting nervous about defining HTML, I get the same about redefining schema.org. Yes we should give full power to Matt to make things more readable, but I would be very reluctant of changing schema.org terms - with ONE exception…
… JSON LD we have @type, @id, @value and @language, and it’s a very common practice in JSON LD, that @type is redefined to use type, and @id is redefined as id. It’s so common that schema.org does it. This will make things easier to port into a javascript structure to simplify the keywords.
Matt Garrish: We touched on that this is something we can improve in our spec language. This is the push and pull of using property tech names and natural language. Our section right now is structured to concepts rather than specific naming. We can flip it around, put property names with the language, and there’s ways of tweaking, but i’m comfortable migrating us away from schema.org. There are ‘read-by’ for narrator, and we should strike up a convo with[CUT]
… that’s probably the most appropriate way to go…
Dave Cramer: I wanted to agree with Ivan - yes, I think in the JSON LD context, the cure is worse than the disease.
Garth Conboy: Much like Ivan said, we need to use the schema.org terms, but we want to be careful in our drafting that we don’t lose the drafting, like the first entry, we live with what we have but we try to be as clear in our language as possible to avoid confusion.
Ivan Herman: we need a resolution on to change, so I moved agreeing on the removal of ‘@’
Proposed resolution: remove the ‘@’ from keywords; leave other terms as they are (Ivan Herman)
Ivan Herman: +1
Joshua Pyle: +1
Nick Ruffilo: +1
Matt Garrish: +1
Jeff Buehler: +1
Garth Conboy: +1
Ben Walters: +1
Dave Cramer: +1
Resolution #3: remove the ‘@’ from keywords; leave other terms as they are
Ric Wright: +1
Marisa DeMeglio: +1