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

**Map fields become a SHOULD #341

Closed
evanp opened this Issue Jul 12, 2016 · 23 comments

Comments

Projects
None yet
9 participants
@evanp
Collaborator

evanp commented Jul 12, 2016

@jasnell inserted text making the use of **Map properties RECOMMENDED over the default properties. I think this is unnecessarily complex, since I believe that most documents will be unilingual, and won't need different languages for each property.

@sandhawke

This comment has been minimized.

Show comment
Hide comment
@sandhawke

sandhawke Jul 12, 2016

Contributor

But even if the document uses all one language, how is one to know what that language is?

I understood that question to be the motivation.

Contributor

sandhawke commented Jul 12, 2016

But even if the document uses all one language, how is one to know what that language is?

I understood that question to be the motivation.

@evanp

This comment has been minimized.

Show comment
Hide comment
@evanp

evanp Jul 12, 2016

Collaborator

@sandhawke as mentioned in the spec, @context can have a @language property.

Collaborator

evanp commented Jul 12, 2016

@sandhawke as mentioned in the spec, @context can have a @language property.

@sandhawke

This comment has been minimized.

Show comment
Hide comment
@sandhawke

sandhawke Jul 12, 2016

Contributor

Oh... Where is that in the spec? I don't see it. Oh, it's just in the new ED.

But that doesn't apply unless you're doing JSON-LD processing.

Contributor

sandhawke commented Jul 12, 2016

Oh... Where is that in the spec? I don't see it. Oh, it's just in the new ED.

But that doesn't apply unless you're doing JSON-LD processing.

@sandhawke sandhawke added the i18n label Jul 12, 2016

@sandhawke

This comment has been minimized.

Show comment
Hide comment
@sandhawke

sandhawke Jul 12, 2016

Contributor

I've added the i18n label, @r12a. I hope that's right, procedurally. Also, this is coming out of #335

Contributor

sandhawke commented Jul 12, 2016

I've added the i18n label, @r12a. I hope that's right, procedurally. Also, this is coming out of #335

@r12a

This comment has been minimized.

Show comment
Hide comment
@r12a

r12a Jul 12, 2016

As Sandro says, indeed the point of #335 was that, if a summary, say, is available only in a single language you still need to know what that language is to make the activity stream work in a worldwide Web.

I believe the spec needs to be clear about how one would specify language for properties that have content in a single language, and in its examples show that identifying the language is a practice that should be followed by default.

(Not sure why this is raised as a separate issue, rather than continuing the discussion under #335)

r12a commented Jul 12, 2016

As Sandro says, indeed the point of #335 was that, if a summary, say, is available only in a single language you still need to know what that language is to make the activity stream work in a worldwide Web.

I believe the spec needs to be clear about how one would specify language for properties that have content in a single language, and in its examples show that identifying the language is a practice that should be followed by default.

(Not sure why this is raised as a separate issue, rather than continuing the discussion under #335)

@aphillips

This comment has been minimized.

Show comment
Hide comment
@aphillips

aphillips Jul 12, 2016

Piling on: the reason this was requested was because the default format doesn't (or at least didn't) include language information. Monolingual documents still need language and direction metadata. If that's been added in @context, that would help address the need expressed by this Issue.

aphillips commented Jul 12, 2016

Piling on: the reason this was requested was because the default format doesn't (or at least didn't) include language information. Monolingual documents still need language and direction metadata. If that's been added in @context, that would help address the need expressed by this Issue.

@sandhawke

This comment has been minimized.

Show comment
Hide comment
@sandhawke

sandhawke Jul 12, 2016

Contributor

In our telecon just now, we had rough consensus on saying

  • if document producers know the language, they MUST include it in either *map properties or an @language nested in the @context
  • if document consumers can use language information, they MUST look for it in *map properties and @language nest in the @context

Hopefully @evanp will draft that in spec language. The main counter-argument is that it raises the complexity of minimal implementations and minimal examples, but the sense in the telecon seemed to be that it was worth it.

BTW @jasnell is away this week and we'd like his confirmation before proceeding

Contributor

sandhawke commented Jul 12, 2016

In our telecon just now, we had rough consensus on saying

  • if document producers know the language, they MUST include it in either *map properties or an @language nested in the @context
  • if document consumers can use language information, they MUST look for it in *map properties and @language nest in the @context

Hopefully @evanp will draft that in spec language. The main counter-argument is that it raises the complexity of minimal implementations and minimal examples, but the sense in the telecon seemed to be that it was worth it.

BTW @jasnell is away this week and we'd like his confirmation before proceeding

@aphillips

This comment has been minimized.

Show comment
Hide comment
@aphillips

aphillips Jul 12, 2016

@sandhawke Cool. Thanks for the update.

Did this consensus also include @dir information? Or is base direction (for RTL language support) being considered separately?

aphillips commented Jul 12, 2016

@sandhawke Cool. Thanks for the update.

Did this consensus also include @dir information? Or is base direction (for RTL language support) being considered separately?

@evanp

This comment has been minimized.

Show comment
Hide comment
@evanp

evanp Jul 12, 2016

Collaborator

This was done as a different issue because we had already called out the use of the JSON-LD feature, @language, and that's not controversial.

What is controversial is having both the @language in the @context and making use of the **Map properties RECOMMENDED even if there is only one language version of the property. That would leave us with the complicated version of the document below:

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/activitystreams",
    "@language": "en"
  },
  "type": "Note",
  "nameMap": {
    "en": "A simple note"
  },
  "summaryMap": {
    "en": "This is the summary of the simple note."
  },
  "contentMap": {
    "en": "This is the content of the simple note."
  }
}

I think we can get along with just using the JSON-LD version of @context, which we specifically call out in the document, and which we use for other parts of the specification (like extensions). So if we don't make the *Map version of properties RECOMMENDED, we'd have a more tractable document like this:

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/activitystreams",
    "@language": "en"
  },
  "type": "Note",
  "name": "A simple note",
  "summary": "This is the summary of the simple note.",
  "content": "This is the content of the simple note."
}

It would still be possible to use the first version, of course; but the second version would be OK.

Collaborator

evanp commented Jul 12, 2016

This was done as a different issue because we had already called out the use of the JSON-LD feature, @language, and that's not controversial.

What is controversial is having both the @language in the @context and making use of the **Map properties RECOMMENDED even if there is only one language version of the property. That would leave us with the complicated version of the document below:

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/activitystreams",
    "@language": "en"
  },
  "type": "Note",
  "nameMap": {
    "en": "A simple note"
  },
  "summaryMap": {
    "en": "This is the summary of the simple note."
  },
  "contentMap": {
    "en": "This is the content of the simple note."
  }
}

I think we can get along with just using the JSON-LD version of @context, which we specifically call out in the document, and which we use for other parts of the specification (like extensions). So if we don't make the *Map version of properties RECOMMENDED, we'd have a more tractable document like this:

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/activitystreams",
    "@language": "en"
  },
  "type": "Note",
  "name": "A simple note",
  "summary": "This is the summary of the simple note.",
  "content": "This is the content of the simple note."
}

It would still be possible to use the first version, of course; but the second version would be OK.

@evanp

This comment has been minimized.

Show comment
Hide comment
@evanp

evanp Jul 12, 2016

Collaborator

Another option would be to add a language or defaultLanguage property to our own vocabulary. I'm not keen on that, since it would replicated something already well-covered in JSON-LD.

I think we've already made using the @context property required for some functionality -- specifically, extensions -- and I think this is another good application.

Collaborator

evanp commented Jul 12, 2016

Another option would be to add a language or defaultLanguage property to our own vocabulary. I'm not keen on that, since it would replicated something already well-covered in JSON-LD.

I think we've already made using the @context property required for some functionality -- specifically, extensions -- and I think this is another good application.

@wilkie

This comment has been minimized.

Show comment
Hide comment
@wilkie

wilkie Jul 12, 2016

I think @context is just something that needs to be visible in all examples and should be in all activitystreams objects. Then it is no longer a stretch of the imagination to expect things to be in there. I believe @language inside @context will be less of a burden on implementations as long as the examples in the spec are clear enough that people must look for nameMap when @language is unknown. I can see people ignoring nameMap completely and some implementations may just decide to use only nameMap which is possible and maybe even practical. Nobody is going to use name and nameMap together, I would assume.

It would be nice if name could be a string that logically expands to an object using the default language or an object with language key/values instead of having both name and nameMap etc. oh well.

wilkie commented Jul 12, 2016

I think @context is just something that needs to be visible in all examples and should be in all activitystreams objects. Then it is no longer a stretch of the imagination to expect things to be in there. I believe @language inside @context will be less of a burden on implementations as long as the examples in the spec are clear enough that people must look for nameMap when @language is unknown. I can see people ignoring nameMap completely and some implementations may just decide to use only nameMap which is possible and maybe even practical. Nobody is going to use name and nameMap together, I would assume.

It would be nice if name could be a string that logically expands to an object using the default language or an object with language key/values instead of having both name and nameMap etc. oh well.

@evanp

This comment has been minimized.

Show comment
Hide comment
@evanp

evanp Jul 12, 2016

Collaborator

At this point, we're waiting for @jasnell to see if he can live with this formulation.

Collaborator

evanp commented Jul 12, 2016

At this point, we're waiting for @jasnell to see if he can live with this formulation.

@aphillips

This comment has been minimized.

Show comment
Hide comment
@aphillips

aphillips Jul 12, 2016

@evanp I don't have a problem with what you suggest.

Note that RECOMMENDED doesn't make the simpler form non-conforming. It just says that you SHOULD use the map form. You could even make it lowercase recommended (i.e. something like a health warning that "Use of the map form is recommended when the language is different from that of the @context or when language information is associated with a specific value separately from the document as a whole.")

aphillips commented Jul 12, 2016

@evanp I don't have a problem with what you suggest.

Note that RECOMMENDED doesn't make the simpler form non-conforming. It just says that you SHOULD use the map form. You could even make it lowercase recommended (i.e. something like a health warning that "Use of the map form is recommended when the language is different from that of the @context or when language information is associated with a specific value separately from the document as a whole.")

@evanp

This comment has been minimized.

Show comment
Hide comment
@evanp

evanp Jul 12, 2016

Collaborator

@sandhawke Also, I wonder if there's a fair comparison with language-tagged strings in RDF. Are they recommended even if the language of the document is declared elsewhere? Is it good style? I'm not sure.

Collaborator

evanp commented Jul 12, 2016

@sandhawke Also, I wonder if there's a fair comparison with language-tagged strings in RDF. Are they recommended even if the language of the document is declared elsewhere? Is it good style? I'm not sure.

@akuckartz

This comment has been minimized.

Show comment
Hide comment
@akuckartz

akuckartz Jul 13, 2016

JSON-LD is an RDF-serialisation. Language maps and @language are two different JSON-LD tools to express the same RDF language-tagged strings. In other words: If a JSON-LD document is converted to Turtle one does not know how (and if) these language-tagged strings were serialised in JSON-LD before.

akuckartz commented Jul 13, 2016

JSON-LD is an RDF-serialisation. Language maps and @language are two different JSON-LD tools to express the same RDF language-tagged strings. In other words: If a JSON-LD document is converted to Turtle one does not know how (and if) these language-tagged strings were serialised in JSON-LD before.

@azaroth42

This comment has been minimized.

Show comment
Hide comment
@azaroth42

azaroth42 Jul 13, 2016

Contributor

Language as a property, rather than being part of the RDF model layer, was considered in #251.

Contributor

azaroth42 commented Jul 13, 2016

Language as a property, rather than being part of the RDF model layer, was considered in #251.

@r12a

This comment has been minimized.

Show comment
Hide comment
@r12a

r12a Jul 14, 2016

How do the proposed solutions support the use case where the values of note, summary and content are in different languages, which seems entirely possible to me? It seems you might have to add some html markup to the properties that are not in the default language, which is a little clunky if it's just to get around the inability to apply language metadata to individual properties, and seems especially problematic because the default language would always have to be that of the name property, since it doesn't accept html markup:

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/activitystreams",
    "@language": "en"
  },
  "type": "Note",
  "name": "Richard added a new post to his wall",
  "summary": "Première phrase de Béowulf.",
  "content": "Hwæt wë Gār-Dene   in geārdagum, \ þēodcyninga    þrym gefrūnon, \ hū þā æþelinʒas   ellen fremedon."
}

r12a commented Jul 14, 2016

How do the proposed solutions support the use case where the values of note, summary and content are in different languages, which seems entirely possible to me? It seems you might have to add some html markup to the properties that are not in the default language, which is a little clunky if it's just to get around the inability to apply language metadata to individual properties, and seems especially problematic because the default language would always have to be that of the name property, since it doesn't accept html markup:

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/activitystreams",
    "@language": "en"
  },
  "type": "Note",
  "name": "Richard added a new post to his wall",
  "summary": "Première phrase de Béowulf.",
  "content": "Hwæt wë Gār-Dene   in geārdagum, \ þēodcyninga    þrym gefrūnon, \ hū þā æþelinʒas   ellen fremedon."
}
@r12a

This comment has been minimized.

Show comment
Hide comment
@r12a

r12a Jul 14, 2016

Um. To finish off what i was saying before: So although you wouldn't want to in normal monolingual situations, i would expect that it may make sense to allow a mixture of @language and ...Map in this case, as follows:

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/activitystreams",
    "@language": "en"
  },
  "type": "Note",
  "name": "Richard added a new post to his wall",
  "summaryMap": { "fr": "Première phrase de Béowulf." },
  "contentMap": { "ang": "Hwæt wë Gār-Dene   in geārdagum, \ þēodcyninga    þrym gefrūnon, \ hū þā æþelinʒas   ellen fremedon." }
}

In summary,

  • using @language in the context seems to be the most straightforward way to provide language information in a unilingual situation
  • where properties are localised into multiple languages, then ...Map should be used for all natural language text
  • where one property is in a different language than others, use @language for the default language, and use ...Map for properties containing values in other languages.

Does that make sense?

r12a commented Jul 14, 2016

Um. To finish off what i was saying before: So although you wouldn't want to in normal monolingual situations, i would expect that it may make sense to allow a mixture of @language and ...Map in this case, as follows:

{
  "@context": {
    "@vocab": "http://www.w3.org/ns/activitystreams",
    "@language": "en"
  },
  "type": "Note",
  "name": "Richard added a new post to his wall",
  "summaryMap": { "fr": "Première phrase de Béowulf." },
  "contentMap": { "ang": "Hwæt wë Gār-Dene   in geārdagum, \ þēodcyninga    þrym gefrūnon, \ hū þā æþelinʒas   ellen fremedon." }
}

In summary,

  • using @language in the context seems to be the most straightforward way to provide language information in a unilingual situation
  • where properties are localised into multiple languages, then ...Map should be used for all natural language text
  • where one property is in a different language than others, use @language for the default language, and use ...Map for properties containing values in other languages.

Does that make sense?

@jasnell

This comment has been minimized.

Show comment
Hide comment
@jasnell

jasnell Jul 16, 2016

Collaborator

I am back from my camping trip with the family but won't be catching up on
things until Monday. Even then I'm still technically on vacation for
another week. I'll get a response as soon as possible.

On Jul 12, 2016 11:40 AM, "Evan Prodromou" notifications@github.com wrote:

At this point, we're waiting for @jasnell https://github.com/jasnell to
see if he can live with this formulation.


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#341 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/AAa2eRmskOVD2rHHXJV0Py5pLEuzUTg1ks5qU9-rgaJpZM4JKmZT
.

Collaborator

jasnell commented Jul 16, 2016

I am back from my camping trip with the family but won't be catching up on
things until Monday. Even then I'm still technically on vacation for
another week. I'll get a response as soon as possible.

On Jul 12, 2016 11:40 AM, "Evan Prodromou" notifications@github.com wrote:

At this point, we're waiting for @jasnell https://github.com/jasnell to
see if he can live with this formulation.


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#341 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/AAa2eRmskOVD2rHHXJV0Py5pLEuzUTg1ks5qU9-rgaJpZM4JKmZT
.

@evanp

This comment has been minimized.

Show comment
Hide comment
@evanp

evanp Jul 18, 2016

Collaborator

@r12a your second example looks correct. I'm mostly concerned with what I think is the base case: where all natural language properties are in the document's default language.

Collaborator

evanp commented Jul 18, 2016

@r12a your second example looks correct. I'm mostly concerned with what I think is the base case: where all natural language properties are in the document's default language.

@evanp

This comment has been minimized.

Show comment
Hide comment
@evanp

evanp Jul 26, 2016

Collaborator

@jasnell it'd be great to get your response before tomorrow's telecon. I think that making the *Map properties RECOMMENDED even if we have a way to declare default language makes for clumsy documents (as seen above).

Collaborator

evanp commented Jul 26, 2016

@jasnell it'd be great to get your response before tomorrow's telecon. I think that making the *Map properties RECOMMENDED even if we have a way to declare default language makes for clumsy documents (as seen above).

@jasnell

This comment has been minimized.

Show comment
Hide comment
@jasnell

jasnell Jul 26, 2016

Collaborator

I'd prefer not to make the Map properties recommended in general. In other
words, I agree with you

On Monday, July 25, 2016, Evan Prodromou notifications@github.com wrote:

@jasnell https://github.com/jasnell it'd be great to get your response
before tomorrow's telecon. I think that making the *Map properties
RECOMMENDED even if we have a way to declare default language makes for
clumsy documents (as seen above).


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#341 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAa2eZTwitks8f4uNT-KgkIg03djprHsks5qZYRTgaJpZM4JKmZT
.

Collaborator

jasnell commented Jul 26, 2016

I'd prefer not to make the Map properties recommended in general. In other
words, I agree with you

On Monday, July 25, 2016, Evan Prodromou notifications@github.com wrote:

@jasnell https://github.com/jasnell it'd be great to get your response
before tomorrow's telecon. I think that making the *Map properties
RECOMMENDED even if we have a way to declare default language makes for
clumsy documents (as seen above).


You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#341 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAa2eZTwitks8f4uNT-KgkIg03djprHsks5qZYRTgaJpZM4JKmZT
.

@evanp

This comment has been minimized.

Show comment
Hide comment
@evanp

evanp Jul 26, 2016

Collaborator

Awesome. Let's close this one, then.

Collaborator

evanp commented Jul 26, 2016

Awesome. Let's close this one, then.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment