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 2 - Web Services Profile] RE: [regrep] RE: ACTION ITEM

Here is my second set of comments on the Web Services Profile. Not sure why they're showing up in "Gothic" font (perhaps my PC knows that Halloween is imminent):

Line 904: Recommend having a section called “Content Management Services” with 2 sub-sections (“Validation Service Profile” and “Cataloging Service Profile”), for consistency with representation in our specs.

Line 905: Misspelled “Registry”.

Lines 907-908: Why is content validation a key feature for enabling SOA governance within ebXML Registry? I suspect it’s because it helps ensure that services that are available to be used within a SOA behave in a manner that is expected according to requirements (i.e. by validating their definition according to these requirements, as much as is possible through the capabilities of ebXML Registry). Having said that, I recommend we don’t make the SOA leap here in the middle of the spec (it’s the first time we’re mentioning SOA, and it seems rather odd to do so this late). Instead, I recommend we strike this sentence, and consider creating a “Using ebXML Registry for SOA Governance” TN or spec in the future, where we have SOA governance as the general topic and we discuss how content validation (and other ebXML Registry features) is key for enabling SOA governance.

Line 911: Recommend providing an example(s) of an Invocation Control File somewhere in this spec (i.e. the actual XSLT code). For example it would be very helpful to see an XSLT excerpt for each of the business rules stated in section 6.2 (line 915).

Line 916-917, “and MUST be expressable declaratively within the Invocation Control File”: Recommend striking this statement, as long as it is understood that the Invocation Control File must be an XSLT style sheet (in our latest RS spec, the Canonical XML Content Cataloging Service has this requirement for its Invocation Control File, but I don’t believe it is clear that all Invocation Control Files have this requirement).

Line 919-920: Change “WSDLBindingType” to “ProtocolType”, which is the actual name of the ClassificationScheme (see line 768).

Line 923: Change “SOAPBindingStyle” to “SOAPStyle”, which is the actual name of the ClassificationScheme (see line 768).

Line 929: Change “http” to “HTTP”.

Line 932: Misspelled “Registry”.

Line 944: Why is support for an Invocation Control File for a cataloging service optional? How would the necessary transformations be done without an Invocation Control File?

Line 946: Add introductory sentence above this line for all metadata sections that follow “Input Metadata”, etc.). For example, ”The following sections describe the metadata and content requirements for input to the WSDL cataloging service, and the metadata that is produced by the WSDL cataloging service as output.”. Line 978 can then be deleted.

Line 951, “specified in chapter 11”: On line 590 and subsequent places we reference “the WSDL ClassificationNode in the ObjectType ClassificationScheme.”. Rather than referring the reader to Chapter 11 here, I recommend instead adding a reference to the WSDL ClassificationNode earlier in the spec (in the context of “This is how a WSDL document is classified within the ebXML Registry ObjectType  ClassificationScheme”), perhaps early in chapter 4 (before line 590). Adding this seems natural, since we refer to that node multiple times later on (line 590 and subsequent places). If this is done, we don’t have to refer the reader to chapter 11 here because they will have already read about the canonical WSDL ClassificationNode back in chapter 4. We can just say “refers to the canonical WSDL ClassificationNode”. Same idea for lines 953-954.

Lines 949-956: What separates these two cases is whether or not the WSDL document will be stored in the repository, or referenced as an ExternalLink. Recommend making this clear up front, by adding the following text to follow the current text on line 949: “The difference between the two types of metadata has to do with whether the WSDL document will be stored in the repository, or referenced via URL as an ExternalLink. The sentence beginning on line 955 (“Recall that, in the
ExternalLink case the WSDL document is not be stored in the repository.”) should then be deleted.

Lines 958-969: Recommend listing each example following its description, instead of together afterward.

Line 958: The description that precedes the example discusses ObjectType, but the example shows “id”. Recommend replacing the id with ObjectType as follows: objectType=”urn:oasis:names:tc:ebxmlregrep:ObjectType:RegistryObject:ExtrinsicObject:WSDL”>. Same idea for the next example, which begins on line 963.

Line 976: Need to replace “??” with something (not sure what should be there).

Line 979: Recommend dividing section 7.4.1 into two subsections: “Slots” and “Instances” (or “Registry Instances”, or some other better term). Then for the “Instances” subsection, I recommend using the RIM classes as the heading of each sub-subsection (e.g. “rim:ExtrinsicObject”), rather than including the wsdl elements. This makes sense because at this point, we are concentrating on the registry while earlier we were concentrating on WSDL (i.e. WSDL was driving the discussion).

Lines 982-991: Recommend adding a single example that shows both types of slots.

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: Chiusano Joseph [mailto:chiusano_joseph@bah.com] 
> Sent: Wednesday, October 26, 2005 10:09 PM
> To: Breininger, Kathryn R; ebXML Regrep
> Subject: [regrep] [Joe's Comments, Part 1] RE: [regrep] RE: 
> 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
> Associate
> 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 
> > at:
> > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr
> oups.php 
> > 
> > 
> ---------------------------------------------------------------------
> 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
> oups.php 

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