[oslc-core] XHTML vs simple text in OSLC Core's common properties

Steve K Speicher sspeiche at us.ibm.com
Tue Nov 29 16:48:35 EST 2011


Throwing my 2 cents in as well below.

Thanks,
Steve Speicher | IBM Rational Software | (919) 254-0645

> From: Arthur Ryman <ryman at ca.ibm.com>
> To: John Arwe/Poughkeepsie/IBM at IBMUS, 
> Cc: oslc-core at open-services.net, oslc-core-bounces at open-services.net, 
Joe 
> Ross/Austin/IBM at IBMUS, Robert Uthe/Raleigh/IBM at IBMUS, Ken 
Parzygnat/Raleigh/
> IBM at IBMUS, Anamitra Bhattacharyya/Bedford/IBM at IBMUS
> Date: 11/24/2011 04:40 PM
> Subject: Re: [oslc-core] XHTML vs simple text in OSLC Core's common 
properties
> Sent by: oslc-core-bounces at open-services.net
> 
> John,
> 
> There are several issues here.
> 
> 1. How To Represent Formatted Text
> 
> Many applications require the ability to use formatted text as the value 

> of properties. This is especially true in the Requirements space where 
> people often use textual formatting to signify meaning. Many formats are 

> used and have there advocates, e.g. RTF, HTML, and wiki text. In order 
to 
> promote interchange, we decided to use one format for formatted text, 
> namely XHTML. The reasons for chosing XHTML is that it's a W3C standard 
> (like RDF), it's relatively easy to parse (unlike HTML), and it can be 
> conveniently represented in RDF using the XMLLiteral datatype.
> 
> 2. <div> versus <span>
> 
> Some properties, like dcterms:description, are intended to contain 
> multi-line formatted text. They should contain valid <div> content. 
Other 
> properties, like dcterms:title, are intended to contain single-line 
text. 
> They should contain valid <span> content. The OSLC wiki unfortunately 
has 
> some errors caused by careless copy and paste. I've reported this and 
> Steve has committed to fix the errors.

This issue has been logged and I did make this change.  As always when 
reading specs, check known issues and errata.

> 3. Formatted versus Plain Text
> 
> Plain text is a subset of formatted text. However, if the plain text 
> contains special XML characters, they need to be replaced by character 
> entities when used in XMLLiteral values.
> 
> An application that only handles plain text can easily escape and 
unescape 
> the special characters. The problem comes when a client POSTs or PUTs 
> formatted text. In this case, I think it is acceptable to discard the 
> markup if the loss of the formatting is not harmful. If the app does not 

> natively support formatting then it's hard to see where discarding 
> formatting would be harmful. Discarding formatting can easily be done 
> using standard XML parsing libs.

Agree with this assessment.

> The inability to handle formatting is like other inherent limitations in 

> the app. For example, there may be limits to string length, integer 
size, 
> or precision of floating point numbers. The app has to decide which 
types 
> of truncation are harmless and which might cause harm. If the truncation 

> is harmful then the app should reject the request and provide some 
useful 
> error message.

Agree with this as well.

> Regards, 
> 
___________________________________________________________________________ 

> 
> Arthur Ryman 
> 
> DE, PPM & Reporting Chief Architect
> IBM Software, Rational 
> Toronto Lab | +1-905-413-3077 (office) | +1-416-939-5063 (mobile) 
> 
> 
> 
> 
> 
> From:
> John Arwe <johnarwe at us.ibm.com>
> To:
> oslc-core at open-services.net
> Cc:
> Joe Ross <joeross at us.ibm.com>, Anamitra Bhattacharyya 
> <abhattacharyya at us.ibm.com>, Robert Uthe <uthe at us.ibm.com>, Ken 
Parzygnat 
> <kparzygn at us.ibm.com>
> Date:
> 11/15/2011 05:40 PM
> Subject:
> [oslc-core] XHTML vs simple text in OSLC Core's common properties
> Sent by:
> oslc-core-bounces at open-services.net
> 
> 
> 
> A subset of common properties has value-type = XMLLiteral and a 
> description that says the content [should] include valid 
> XHTML-within-<div> [1]; description and title are examples. 
> Most of Tivoli's existing product set expects "just straight strings" 
(no 
> rich text/XHTML permitted; markup would be treated as strings, i.e. not 
> recognized as markup).  I'm trying to avoid re-inventing new while still 

> enabling existing products that would not, as servers processing a 
> POST(Create)/PUT/PATCH, tolerate XHTML coming in.  I see oslc:name 
(within 
> Resource Shapes) which is potentially re-usable (RS is part of Common as 
a 
> resource definition, but oslc:name is not listed in common properties). 
> I would be interested in thoughts from Core on how best to accomplish 
the 
> goal of enabling apps not yet ready to change to accept XHTML as 
described 
> above. 
> (1) One possibility would be to define a Common Property whose value is 
> simply "String"; one might re-use oslc:name for that purpose (to avoid 
> defining new) or simply define new. 
> (2) I wonder out loud about an alternative of using the existing common 
> properties with an explicit type of ^^String on the [RDF/XML at least... 

> :-( want JSON too though] serialized representations.  But I find that 
not 
> so appealing, since (at a bare minimum) it imposes requirements on 
client 
> implementations to use serialization rules more restrictive than those 
> defined in Core in order for one of my servers to accept the data. 
> (3) Becoming even more of a language lawyer than usual and noting that 
the 
> existing descriptions of the relevant properties use a conditional 
> (SHOULD), and the domain specs (like CM 2.0) only impose normative 
> requirements on implementations (not representations).  So compliant 
> service providers (should? must? not clear!) tolerate sans-XHTML values 
> (good for me), and compliant clients (should, by my reading) provide 
> with-XHTML values which my providers (may? should? must? not clear!) 
> accept... I choose the "should" reading, but do not implement that, so 
my 
> provider is compliant but less useful than ones that would accept 
> with-XHTML values.  The reason I assert "not clear!" is: specs like CM 
2.0 
> [2] based on Core say "OSLC CM consumers and service providers MUST be 
> compliant with both the core specification and this CM specification, 
and 
> SHOULD follow all the guidelines and recommendations in both these 
> specifications. "  I.e. they talk about compliance only in terms of 
> consumers and providers, not resources.  In a case like [1]'s 
> oslc:shortTitle, whose entire description is "Shorter form of 
> dcterms:title for the resource represented as rich text in XHTML 
content. 
> SHOULD include only content that is valid inside an XHTML <div> element. 

> ", it is left to the reader to decide the effects of the SHOULD.  There 
is 
> no clear statement of responsibilities for service providers or 
consumers. 
>  While my reading would be that compliant service providers MUST 
tolerate 
> sans-XHTML values (good for me), compliant clients should provide 
> with-XHTML values, and compliant service providers MUST accept 
with-XHTML 
> values, if my evil twin read the last MUST as a SHOULD and challenged me 

> to show which normative statement was violated then I would be hard 
> pressed to find one.  If I change my goal to practical interop rather 
than 
> trying to minimize the cost of shoe-horning my existing implementation 
> within the letter of the spec, I have a reasonable case to argue for 
MUST. 
>  [Aside and fair disclosure: [1] does in at least one place appear to 
> attempt to place normative restrictions on a resource - foaf:person. But 

> I find no place in Core that defines compliance, so we revert to domain 
> specs like CM 2.0 and the identical problem.] 
> (4) Clarify the meaning of "... SHOULD include only content that is 
valid 
> inside an XHTML <div> element. " with respect to implementations, and 
then 
> see where I stand.  The preceding seems ample evidence that the current 
> text is ambiguous. 
> (5) Define an extension property(ies) that lack the XHTML restriction 
and 
> use those until my implementations learn to recognize it as markup when 
> present.  Which, in the case of a CM 2.0 ChangeRequest, means that it 
> would be a gating factor in becoming compliant (dcterms:title = 1:1) as 
a 
> service provider. 
> (6) Accept the with-XHTML values but do not render them in my UI.  Seems 

> within my power at least, although not perfect.  The horse/water meme 
:-) 
> One could draw the conclusion OSLC assumes a Web-based UI when it 
requires 
> these XHTML-enabled fields.  Is that an explicit intent of OSLC?  If it 
is 
> UNintentional, 1:1 on XHTML-enabled strings would appear to be an 
> anti-pattern.  Requiring a value and encouraging that value to contain 
> XHTML but then saying "well you don't have to display them ever" seems 
> incoherent - if they're not for display, why XHTML? 
> [1] 
> http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixA?
> sortcol=table;table=up#OSLC_Properties 
> 
> [2] 
> http://open-services.net/bin/view/Main/CmSpecificationV2?
> sortcol=table;table=up#Compliance 
> 
> Best Regards, John
> 
> Voice US 845-435-9470  BluePages 
> Tivoli OSLC Lead - Show me the Scenario 
> _______________________________________________
> Oslc-Core mailing list
> Oslc-Core at open-services.net
> http://open-services.net/mailman/listinfo/oslc-core_open-services.net
> 
> 
> 
> 
> _______________________________________________
> Oslc-Core mailing list
> Oslc-Core at open-services.net
> http://open-services.net/mailman/listinfo/oslc-core_open-services.net
> 




More information about the Oslc-Core mailing list