New LinkRole type to support HTML attributes when data provided in JSON-LD

[vholland]

HTML's has a number of attributes for expressing language and how one URL relates to another. Unfortunately, JSON-LD has no such mechanism, so data in a feed cannot express things like "the endpoint is in Japanese" or "the endpoint is an alternate link".

We have touched on this idea in issue #561. A clearer, more extensible mechanism would be to add LinkRole:

A LinkRole is a Role that represents a Web link e.g. as expressed via the 'url' property. Its linkRelationship property can indicate URL-based and plain textual link types e.g. those in IANA
link registry or others such as 'amphtml'. This structure provides a placeholder where details from HTML's element can be represented outside of HTML, e.g. in JSON-LD feeds.

Itt would have two properties:

inLanguage: The language of the resource. (This property already exists. We would be extending the domain.)

linkRelationship: Indicates the relationship type of a Web link.

[danbri]

Thanks @vholland - would you have a full example handy?

[vholland]

I added these in pull request #1047.

For an EntryPoint which resolves to a resource/application available in multiple languages:

<script type="application/ld+json">                                                                                                                            
{                                                                                                                                                              
  "@context": "http://schema.org/",                                                                                                                            
  "@type": "Restaurant",                                                                                                                                       
  "potentialAction": {                                                                                                                                         
    "@type": "ReserveAction",                                                                                                                                  
    "target": [                                                                                                                                                
      "http://www.example.com/Reserve",                                                                                                                        
      {                                                                                                                                                        
        "@type": "LinkRole",                                                                                                                                   
        "target": "http://www.example.com/Reserve-JP",                                                                                                         
        "inLanguage": "jp",                                                                                                                                    
        "linkRelationship": "alternate"                                                                                                                        
      }                                                                                                                                                        
    ]                                                                                                                                                          
  }                                                                                                                                                            
}                                                                                                                                                              
</script>

For an article available in AMP HTML on mobile:

<script type="application/ld+json">                                                                                                                            
{                                                                                                                                                              
  "@context": "http://schema.org/",                                                                                                                            
  "@type": "Article",                                                                                                                                          
  "url": [                                                                                                                                                     
    "http://www.example.com/article",                                                                                                                          
    {                                                                                                                                                          
      "@type": "LinkRole",                                                                                                                                     
      "url": "http://www.example.com/article-amp",                                                                                                             
      "linkRelationship": "amphtml"                                                                                                                            
    }                                                                                                                                                          
  ]                                                                                                                                                            
}                                                                                                                                                              
</script>  

[betehess]

The solution discussed here seems very ad hoc as there seems to be a more general need to say that links/entities/endpoints are "the same" while being specific to a specific language/country.

A few things I do not understand wrt linkRelationship in the examples:

• how to we know which Things are in the same link-relationship?
• what are the kinds of linkRelationship one can use? Can't those be URIs?

Other remarks:

• in #561, you used inLanguage on a EntryPoint: what was wrong with that approach?
• in Question on expressing translations of terms , several of us discussed about extending schema:sameAs to things that are not webpages, which I believe that would apply quite well here as well

[vholland]

The kinds of linkRelationships are the same as supported in the "rel" attribute for the HTML tag. I hesitate to enumerate as there is a difference between the HTML5 documentation and how sites are marked up today. For example, "canonical" is supported by most (all?) modern browsers, but is not listed in the W3C docs.

I was going with text because that is what HTML uses. The idea was to use the same string one would use if the document were in HTML.

Initially, I see "alternate" and "amphtml" the most useful.

in #561, you used inLanguage on a EntryPoint: what was wrong with that approach?

We would need to update everything that expects URL to also expect EntryPoint. This seemed less weighty as Roles can already be used anywhere.

in Question on expressing translations of terms , several of us discussed about extending schema:sameAs to things that are not webpages, which I believe that would apply quite well here as well

I don't think I understand. How would that apply?

[unor]

I hesitate to enumerate as there is a difference between the HTML5 documentation and how sites are marked up today. For example, "canonical" is supported by most (all?) modern browsers, but is not listed in the W3C docs.

In HTML5, only link types defined in the spec or registered in the Microformats wiki (http://microformats.org/wiki/existing-rel-values#HTML5_link_type_extensions) can be used. On this page in the Microformats wiki, the link types amphtml and canonical are (currently) registered.

So the definition of the linkRelationship property could refer to http://microformats.org/wiki/existing-rel-values#HTML5_link_type_extensions (if there is value in allowing/expecting the same link types that are allowed in HTML5).

[vholland]

So the definition of the linkRelationship property could refer to http://microformats.org/wiki/existing-rel-values#HTML5_link_type_extensions (if there is value in allowing/expecting the same link types that are allowed in HTML5).

That makes sense. My point was that schema.org should not be defining these terms.

[vholland]

Thinking about this more, the AMP example would probably look like:

<script type="application/ld+json">                                                                                                                            
{                                                                                                                                                              
  "@context": "http://schema.org/",                                                                                                                            
  "@type": "Article",                                                                                                                                          
  "url": [                                                                                                                                                     
    {
      "@type": "LinkRole",
      "url": "http://www.example.com/article",
      "linkRelationship": "canonical"
    },                                                                                                                         
    {                                                                                                                                                          
      "@type": "LinkRole",                                                                                                                                     
      "url": "http://www.example.com/article-amp",                                                                                                             
      "linkRelationship": "amphtml"                                                                                                                            
    }                                                                                                                                                          
  ]                                                                                                                                                            
}                                                                                                                                                              
</script>

[danbri]

I've taken the current proposal manually from @vholland 's pull request and added it to the development version of the pending extension for review:

http://pending.webschemas.org/LinkRole

[danbri]

@vholland should we retract/retire this?

[vholland]

Yes. I'll rethink and open a new issue when I can make a better case.

[danbri]

Thanks. This leaves us with an interesting howwework meta issue: what do we do with retracted proposals, can we delete them from pending? My inclination is that we should be able to do so, but we can also park things there indefinitely if they've seen some level of usage...

[vholland]

I think we can delete them. Otherwise, we will accrue abandoned proposals and it will be unclear which are active and which are not.

[RichardWallis]

+1 for deleting them

[danbri]

That works for me. We could always keep an 'attic' of things that were in pending somehow. The raw materials are all preserved in this repository, at least. The list of closed issues tagged "pending.schema.org" is a reasonable path in, no need to code something dedicated.

[danbri]

We did implement an Attic section to document terms that "didn't make it", e.g. after being tested via Pending. There are also various superseded terms that could be hidden there. Should LinkRole go into the Attic?

[danbri]

Ok, hearing no objections, I will move http://schema.org/LinkRole from "pending" to "attic" section, whose intent is to hide-but-not-delete the documentation of ideas that didn't work out.

[danbri]

Last call! @TzviyaSiegman

[TzviyaSiegman]

The Publishing Working Group is interested in using this in the manifest for Web Publications. See https://w3c.github.io/wpub/#publication-link-def cc/@iherman @mattgarrish

[mattgarrish]

Yes, without being able to express relationships we'll have to introduce something of our own making, as we've done in the interim in the draft. Definitely not the way we want to go, though.

[iherman]

What @mattgarrish said. LinkRole would fit our use case perfectly well, although there is an open issue filed elsewhere (#1959) that should also be resolved if this class is kept. It would be a pity if the publishing community was required to introduce its own type for something like this.

[danbri]

@TzviyaSiegman @iherman @mattgarrish do you still expect/want to use LinkRole? Otherwise we should probably retire the proposal, to declutter pending.schema.org. What's the status of it w.r.t. the digital publishing group? is the lack of encodingFormat your only concern?

[iherman]

@danbri our situation has not changed. The Web Publication Manifest has introduced its own type: LinkedResource. Ideally, we would prefer to use a schema.org class if it was available but, as @mattgarrish said, it is not the way we want to go...

[danbri]

So, if LinkRole expected the encodingFormat property, that would make this viable for you?

[rvguha]

Ivan, I am really confused ... You would prefer that, but it is not the way you want to go?

…

On Mon, Feb 4, 2019 at 8:43 PM Ivan Herman ***@***.***> wrote: @danbri <https://github.com/danbri> our situation has not changed. The Web Publication Manifest has introduced its own type: LinkedResource <https://www.w3.org/TR/wpub/#linkedResource>. Ideally, we would prefer to use a schema.org class if it was available but, as @mattgarrish <https://github.com/mattgarrish> said, it is not the way we want to go... — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#1045 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFAlCqSAQDuJGXOYloyWPAp-ZwyCir2aks5vKQwKgaJpZM4H1Tcd> .

[danbri]

@rvguha - I think Ivan wrote his sentence a bit backwards. The comment from Matt earlier was "without being able to express relationships we'll have to introduce something of our own making, as we've done in the interim in the draft. Definitely not the way we want to go, though.".

[rvguha]

Ah got it. Lets find a way for them to express what they would like to. guha

…

On Mon, Feb 4, 2019 at 8:49 PM Dan Brickley ***@***.***> wrote: @rvguha <https://github.com/rvguha> - I think Ivan wrote his sentence a bit backwards. The comment from Matt earlier was "without being able to express relationships we'll have to introduce something of our own making, as we've done in the interim in the draft. Definitely not the way we want to go, though.". — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1045 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFAlCrb6K8Wvl_y1yvgxa9FCRJIJrOP7ks5vKQ1igaJpZM4H1Tcd> .

[iherman]

@rvguha sorry not to be clear. We use our own type because we have to, but we do not think this is the right way to go; we would prefer to use a schema.org type if it was available.

@danbri we need both the encoding type and the rel. Essentially, we need to express what HTML's <link> can express. In another place (but maybe this will come to the publishing, too) the necessity to reproduce sri (from subresource integrity) also came to the fore as a possibility (still pending).

[danbri]

@rvguha - yep, that may or may not be LinkRole, but let's leave LinkRole in Pending for now while we figure that out.
@iherman et al. - can you share a couple of complete examples here so we can figure out what you need?

[rvguha]

Yup, examples would be great. guha

…

On Mon, Feb 4, 2019 at 8:57 PM Dan Brickley ***@***.***> wrote: @rvguha <https://github.com/rvguha> - yep, that may or may not be LinkRole, but let's leave LinkRole in Pending for now while we figure that out. @iherman <https://github.com/iherman> et al. - can you share a couple of complete examples here so we can figure out what you need? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1045 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFAlCorIFl49lFnWe4iZocMSyI3eE7R-ks5vKQ8ygaJpZM4H1Tcd> .

[iherman]

@rvguha we have some in the document: https://www.w3.org/TR/wpub/#app-manifest-examples.

[danbri]

@iherman looking at that example, I don't see the direct benefit of a generic type that's all about the fact that we're linking/referring to something. Why not simply omit it, use something generic like Thing, or use specific types that capture the intrinsic nature of the linked thing? e.g. WebPage, or new stuff like maybe FontMediaObject for that specific example.

[iherman]

I am not sure what you mean by "omit it". You mean omit the type reference?

Also, I also do not understand "use specific types that capture the intrinsic nature of the linked thing"?
Do you mean to say that I would use different typed objects, depending on whether the target is an image file, an audio file, a web site in HTML or SVG, etc? I am not sure why that would be better than using a common structure with a number of well defined properties...

But I may not understand what you say.

[iherman]

B.t.w., in that list of references the idea is that any resource that is on the Web may be addressed. We do not intend to list/restrict the types of resources a publication may include. This is open ended and creating a link for every new kind of resource does not really scale in my view...

[thadguidry]

He's looking for a Type that encapsulates the concept of a Resource as in the implied metatype within DCMI and LRMI. Schema.org does not have that Type, and neither does DCMI or LRMI (there they have "a Resource" implied as its core descriptive Thing within their vocabulary, but yet don't provide the Resource Type directly, only URI, PhysicalResource, BibliographicResource, and other Resource Types). In Schema.org, currently the closest Type to Resource we have is Thing.

[VladimirAlexiev]

I'm really confused about this proposal.

• Is it pending or is it retracted and therefore to be moved to attic?
• If the incoming relation of this class is url, it should show in the class page
• What are its differentia from its parent class Role?
  • Seems to me that linkRelationship in this class duplicates roleName in its parent
  • inLanguage describes the target resource, so isn't it better to move that to a description of the target, such description being EntryPoint?

Seems to me the example can be reworked as follows

{                                                                                                                                                              
  "@context": "http://schema.org/",                                                                                                                            
  "@type": "Article",                                                                                                                                          
  "url": [                                                                                                                                                     
    {
      "@type": "Role",
      "url": "http://www.example.com/article",
      "roleName": "canonical"
    },                                                                                                                         
    {                                                                                                                                                          
      "@type": "Role",                                                                                                                                     
      "url": "http://www.example.com/article-amp",                                                                                                             
      "roleName": "amphtml"                                                                                                                            
    }                                                                                                                                                          
  ]                                                                                                                                                            
}

[iherman]

@VladimirAlexiev,

What we need in our case is described in the specification for LinkedResource, which is currently defined separately from schema.org. Our wish would be to rely on an existing type in schema.org.

Looking at that definition of Role: the description, and also the description of the roleName attribute, suggests that this is for humans. Ie, what "role" do I play in a theatre play or a soccer team. What we are looking for is the equivalent of the HTML's rel attribute for <link> which is based on a set of registered rel values or explicit URL-s. The proposed linkRelationship is, as far as I can see, the equivalent of the rel attribute, ie, exactly what we are looking for.

Although not part of this issue, we also need a the possibility of using encodingFormat, which is not part of Role and, indeed, would not be appropriate as a relationship for humans.

Hence our proposal to keep linkRole as a subtype of Role, using indeed linkedRelationship as proposed here, but also allow encodingFormat as a valid property (see also #1959).

[VladimirAlexiev]

Role: the description, and also the description of the roleName attribute, suggests that this is for humans

True, but then it cannot have LinkRole as a subclass, can it? cc @danbri
IMHO the best is to generalize Role to apply to any similar situation, and not repeat already existing attributes like roleName in subclasses.

[iherman]

@VladimirAlexiev

True, but then it cannot have LinkRole as a subclass, can it? cc @danbri

That is probably correct. Generalizing Role may be a possibility indeed if there is a correct formulation on describing what it does; at this moment I do not really see what that could be without making it very convoluted. It would mean somehow describing us humans and resources on the Web within the similar framework... which may lead to complicated and opaque discussions:-)

[danbri]

@iherman - I'm looking at this with @vholland

It seems we already have linkRelationship in https://webschemas.org/LinkRole --- do you have everything that you need, except for encodingFormat being expected on this type? If you propose additional changes can you tell us exactly what they are.

The definitions are in https://github.com/schemaorg/schemaorg/blob/master/data/ext/pending/issue-1045.rdfa

[iherman]

@danbri we may be there indeed.

• linkRelationship is very close and it is possible just a matter of description; at the moment the value is very open, just a text. In our use case it is a bit stricter, a mirror of the rel attribute in HTML, insofar as the value must be either a URL or a IANA link registry item. But if our application is restricting the expected values (and checks it by itself) I believe is fine from a schema.org point of view.
• As you say, encodingFormat is missing.

---

In the future, we may need some additional attributes, e.g., noting the duration of the resource when it is an audio element. I am not sure whether in the schema.org environment we must keep it very clean in a modeling sense (in which case those attributes should be added as metadata on the target rather than the link itself) or whether we could add some extra attributes that are ignored by processors. But that is matter of a separate discussion...

Thanks! (And, @danbri, see you in a few days in Berlin!)

[danbri]

@iherman can you (or the WG) help us turn this into a concrete / exact change proposal? Also for #1959

[github-actions]

This issue is being tagged as Stale due to inactivity.