Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

How we name things is potentially confusing #312

Closed
dauwhe opened this issue Aug 21, 2018 · 10 comments

Comments

@dauwhe
Copy link
Contributor

commented Aug 21, 2018

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

This comment has been minimized.

Copy link
Contributor

commented Aug 21, 2018

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

This comment has been minimized.

Copy link
Member

commented Aug 22, 2018

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

This comment has been minimized.

Copy link
Contributor

commented Aug 22, 2018

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

This comment has been minimized.

Copy link
Contributor

commented Aug 22, 2018

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

This comment has been minimized.

Copy link
Member

commented Aug 22, 2018

@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

This comment has been minimized.

Copy link
Contributor

commented Aug 22, 2018

@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

This comment has been minimized.

Copy link
Member

commented Aug 22, 2018

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

This comment has been minimized.

Copy link

commented Aug 22, 2018

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

This comment has been minimized.

Copy link
Member

commented Aug 22, 2018

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.

@TzviyaSiegman TzviyaSiegman added this to discuss - call in PWG Task Management Sep 7, 2018

@TzviyaSiegman TzviyaSiegman moved this from discuss - call to discuss - GH in PWG Task Management Sep 7, 2018

@iherman

This comment has been minimized.

Copy link
Member

commented Sep 11, 2018

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
7 participants
You can’t perform that action at this time.