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


Help: OASIS Mailing Lists Help | MarkMail Help

regrep message

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

Subject: [Joe's Comments, Part 1] RE: [regrep] RE: ACTION ITEM

Here are my comments on the first half of the spec (up to Section 5, inclusive). Rest are in process.


Line 205: Misspelled “artifacts”

Lines 206-222: Move to above Chapter 1, or do not reference Chapter 1 in the list, as we are currently in Chapter 1

Line 209: Switch with line 208, for better flow

Lines 207-222: Present as a table, with chapter number/chapter title/chapter description

Lines 212-219: Present all profiles as a single chapter, with a section for each type of profile

Line 233: What type of UML Diagrams? Only class diagrams?

Line 261: This chapter is called “WSDL Information Model Overview” here, but in the earlier list of chapters it was described as “provides an overview of the Web Services information model.”. Recommend changing the earlier description to be ““provides an overview of the information model for Web Services description within an ebXML Registry”, and changing the title on line 261 to “ebXML Registry Information Model for Web Services”.

Line 263: Before “For more information”, add a sentence stating that “This chapter will focus on Web Services that are described using the W3C Web Services Description Language (WSDL) standard”.

Line 263: Change “For more information see” to will “For more information on WSDL see”

Line 264: Add the following above the figure: “The following figure illustrates the WSDL information model:”

Line 266: “At the lowest level” - is the PortType really considered the “lowest” level? Some would consider it to be the highest level.

Lines 266-271: Recommend replacing this with a statement that “The WSDL information model is shown above. Its elements are described below”. Otherwise, it appears that we are duplicating information between here and the descriptions below.

Line 273: Misspelled “description” 

Line 273: Capitalize “Service” and “Port”, and any other WSDL elements that are referred to from this point on in the document.

Line 278, “described”: On line 274 we used the term “define” for port. This may be considered inconsistent.

Line 278, “end-point”: Change to “endpoint”, for consistency throughout the document.

Illustration 1, General: Recommend replacing/augmenting with a figure that shows the “native” WSDL elements (PortType, Operation, etc.) separately from the “binding” WSDL elements (Service, Port, etc.), and the relation between them (as described in the subsection for each element). 

Illustration 1, General: Should we add “Part” (message part) as an element?

Line 285: Add “the” before “definition”

Chapter 2, General: Consider adding a concrete example either woven throughout the subsections that describe the WSDL elements, or following all of the subsections.

Chapter 3, General: I recall we discussed on a TC call the idea of removing this section, and having the reader refer to our specs. I recommend instead that we focus this chapter only on the Service Information Model and its classes, describing each class as we do in the ebRIM spec (but perhaps with less detail) 

Lines 514-515: Does the mapping have to stop at the WSDL PortType? Why couldn’t we have Operations, Messages, and Types (and Message Parts) as ExtrinsicObjects in the registry that are reused among various PortTypes?

Line 521: Add an introductory statement prior to this line stating that we will now describe each mapping occurrence (is “occurrence” the correct word? Perhaps “instance”?) from WSDL to ebRIM.

Line 522: Add an explanation after this line of why this mapping is accurate - i.e. what is it above the ebXML “Service” class that enables it to be mapped to the WSDL “service” element? Recommend citing the description of the “Service” class in ebRIM 3.0 which states that “Service instances describe services, such as web services.”.

Line 535: This appears to me to be different than a mapping; rather, it is a rule or convention for consistency (and subsequently enhanced interoperability). Recommend separating it (and any other such rules/conventions) from the mappings, perhaps by having multiple subsections (i.e. one for mapping, one for rules/conventions, etc.). 

Line 549: Same idea as with line 535.

Line 565: Same idea as with line 535.

Line 571: Recommend including an “xml:lang” attribute in the wsdl:documentation element, since we describe this case.

Line 587: Recommend including a figure that visually depicts the following lengthy description: “Classifies the rim:Service for wsdl:service by the Service ClassificationNode child of the WSDL ClassificationNode in the ObjectType ClassificationScheme.”. Whew!!! (same for later similar instances, such as line 683)

Line 606: I was going to recommend depicting wsdl:port instances in example, as well as the full representation of the <rim:ServiceBinding> element - but I see that that is done on line 620. So I recommend removing the line 606 example, as it is redundant (it’s also redundant).

Line 665: We cover SOAP bindings for accessURI; should we cover the other possible WSDL 1.1 bindings as well (HTTP GET & POST, MIME)? If not, we should state up front that the only WSDL 1.1 binding discussed in the specification will be SOAP.

Line 680: Recommend showing the rim:ServiceBinding “service” attribute in the figure on line 670, and including the explanation on line 680 before the figure on line 670.

Line 858: Since this line describes associations, it has occurred to me that we might like to have a description up front of the various techniques that will be used in this specification (i.e. mappings, matching (identifier matching, name matching, description matching), classifications, associations, ExtrinsicObject creation, etc.) so that the reader is better prepared when the various sections are described. 

Chapter 4, General: I recommend organizing this section a bit more consistently. Perhaps we can list the following sub-subsections for each subsection (a subsection would be 4.3, for example):

  - Maps To (ebXML Registry mapping - i.e. instead of listing the subsection name as “4.3 wsdl:binding → rim:ExtrinsicObject Mapping”, list it as “wsdl:binding” and state what the part of ebRIM the wsdl:binding maps to)
  - Technique Used (i.e. mapping, matching, etc.)
  - Description
  - Example

This uniformity would make the subsections easier to read.

Line 876: Recommend showing an example of this.

Line 879: Recommend showing an example of this.

Line 882: Recommend showing an example of this.

Line 889: Recommend showing an example of this.

Line 890: Should we really care how registered WSDL files are partitioned? Could this requirement be a burden on users? We point out that such partitioning facilitates better reuse - but shouldn’t that be up to the submitting party? (that is, if they wish to have better reuse abilities, they should partition their WSDL files - if they do not, they won’t have better reuse abilities).

General: Section 5 sparked a thought: Are we anticipating that there will be “WSDL assembly tools” available in the future that interact with ebXML Registry? (similar idea to schema assembly tools) Such tools would (for example) take a registered Service instance and serialize it (and its associated information) as a WSDL document. This would enable users to register WSDL documents, and construct other WSDL documents from their constituent “parts”, or to create WSDL documents from registry contents that did not even originate from WSDL documents.

General: We don’t specify anywhere that we are referencing WSDL 1.1, not WSDL 1.2. Recommend adding a statement to this effect near the top of the document.

General: We don’t describe anywhere why we are writing this specification and why it is needed. I recommend adding a paragraph or two to this early on (I would be very happy to contribute a first cut).  

Kind Regards,
Joseph Chiusano
Booz Allen Hamilton
700 13th St. NW
Washington, DC 20005
O: 202-508-6514  
C: 202-251-0731
Visit us online@ http://www.boozallen.com

> -----Original Message-----
> From: Breininger, Kathryn R [mailto:kathryn.r.breininger@boeing.com] 
> Sent: Wednesday, October 26, 2005 12:06 PM
> To: ebXML Regrep
> Subject: [regrep] RE: ACTION ITEM
> Schedule update - Farrukh plans to have draft 4 out in a week or so.
> Please review and send comments ASAP.  Thank you.
> Kathryn Breininger
> Boeing Library Services
> 425-965-0182 phone
> > _____________________________________________ 
> > From: 	Breininger, Kathryn R  
> > Sent:	Wednesday, October 26, 2005 8:52 AM
> > To:	'ebXML Regrep'
> > Subject:	ACTION ITEM
> > 
> > Please review the Web Services Profile document:
> > 
> http://www.oasis-open.org/apps/org/workgroup/regrep/download.php/14756
> > /regrep-ws-profile-1.0-draft3.pdf  and send comments by 
> November 3rd.
> > We will be discussing this document and determining whether we are 
> > ready to open a vote on it as a TC approved document.
> > 
> > 
> > Kathryn Breininger
> > CENTRAL Project Manager
> > Emerging Technologies
> > Boeing Library Services
> > 
> > 425-965-0182 phone
> > 425-237-3491 fax
> > kathryn.r.breininger@boeing.com
> > 
> > How was your service? Please click link below.......
> > http://socal.web.boeing.com/ssglibsurvey/
> > 
> > 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS 
> TC that generates this mail.  You may a link to this group 
> and all your TCs in OASIS
> at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr

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