Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
How we name things is potentially confusing #312
to express "address" we use "url" in the manifest
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.
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
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
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
We took a different approach in Readium as well:
This gives us access to all schema.org terms, for example for https://schema.org/license we can use
This gives us better consistency and naming for our core metadata, without losing the ability to reference schema.org as an extensibility mechanism.
@iherman it's a different approach:
There are pros and cons for both solutions, just pointing out how Readium handled this differently.
I have played with the google structured data checker (again...) and it is clear that a remapping of, say,
(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
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:
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.
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.
This issue was discussed in a meeting.
View the transcriptGarth 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…
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