OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dss-x message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: ID vs. Id vs. id, semantic and XML syntax, readability


Hi colleagues,


due to restricted ausio abilities during the call I would comment on three topics within this mail:


I have to admit that a sloppy assembly of the name mapping table introduced the irritating 'Id' entry. This element is defined in XMLDSig schema (in SignatureValueType) but it's not used in the core schema. But my simplistic creation of the names map takes all schemes and groups XML and JSON names. Shame on me, I'll fix this flaw.


Regarding the topic of semantic vs syntax:

I agree with Ernst Jan that the sematic model should be independent of any syntax. So I would consider it just a coincidence that the model names match the XML names quite good. But we discussed the few differences ( 'ID' et al) and the introduction of a model->XML mapping for every element seems to be an overkill. An efficient solution I would propose is :

  • Enrich the input scheme with XML-specific names ( es:xmlName="ID") when the model and XML names differ
  • Use camelCase Names (starting with an capital letter) in the semantic  model
  • map the JSON names as usual
  • Add a specific comment to the XML section of the components where mapping is required. Like the automatically added comment regarding the synthetic 'value' member in the JSON mapping.
  • Extend the schema and specification generator

This approach has a clear structure, and a proper separation of concerns.


The current version of the documentation generator has already the ability to group the components by arbitrary tags. Section 4.2 groups all components associated to request/response. We can rearrange the components included in this section, or even create a new 'operation' section.


What's your view on these topics?


Greetings,


Andreaas

 

-- 
Andreas Kühne 
phone: +49 177 293 24 97 
mailto: kuehne@trustable.de

Trustable Ltd. Niederlassung Deutschland Gartenheimstr. 39C - 30659 Hannover Amtsgericht Hannover HRB 212612

Director Andreas Kühne

Company UK Company No: 5218868 Registered in England and Wales 


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]