Details

    • Type: Improvement Improvement
    • Status: Closed Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 1.0
    • Fix Version/s: 1.0
    • Component/s: Foundation
    • Labels:
      None
    • Environment:
      N/A

      Description

      Issue-015 from the contributed issues document

      Artifact URLs have the type encoded in them. Having /s-ramp/{artifactModel}/{artifactType} should not
      be required. Instead this should be inferred from the ServiceDocument and would allow for implementers
      to define their own URL's.

        Activity

        Hide
        Randall Hauch added a comment - - edited
        The following sections in the (original) Foundations document use the explicit URL format:

        Section 2.6 "Referencing S-RAMP Artifacts" - this section actually describes the /s-ramp/{artifactModel}/{artifactType} syntax, describes what's allowed and not allowed, and lists the various Artifact Model and Artifact Types, and gives several examples. This section could possibly be removed, or if deemed still needed would need to be rewritten or highly modified to describe how the URLs are defined by the binding, and to point to the Atom Binding document's ServiceDocument. The table of various Artifact Model and Artifact Types may need to be moved to a new Appendix.

        Section 4.2 "Query Expression Predicates" - this section defines "pathExpression" as "/s-ramp/{artifactModel}/{artifactType}" and thus would need to be made more generic. It also gives several examples with particular artifact models and types, and these could be changed to assume that if the artifact types were available at that URL, then the examples would work (but again to note that the actual URLs are stipulated for the Atom Binding by its Service Document.

        Section 4.4 "S-RAMP Query Grammar" - this section outlines the actual grammar for the query language, and the "location-path" rule would need to be made more generic.
        Show
        Randall Hauch added a comment - - edited The following sections in the (original) Foundations document use the explicit URL format: Section 2.6 "Referencing S-RAMP Artifacts" - this section actually describes the /s-ramp/{artifactModel}/{artifactType} syntax, describes what's allowed and not allowed, and lists the various Artifact Model and Artifact Types, and gives several examples. This section could possibly be removed, or if deemed still needed would need to be rewritten or highly modified to describe how the URLs are defined by the binding, and to point to the Atom Binding document's ServiceDocument. The table of various Artifact Model and Artifact Types may need to be moved to a new Appendix. Section 4.2 "Query Expression Predicates" - this section defines "pathExpression" as "/s-ramp/{artifactModel}/{artifactType}" and thus would need to be made more generic. It also gives several examples with particular artifact models and types, and these could be changed to assume that if the artifact types were available at that URL, then the examples would work (but again to note that the actual URLs are stipulated for the Atom Binding by its Service Document. Section 4.4 "S-RAMP Query Grammar" - this section outlines the actual grammar for the query language, and the "location-path" rule would need to be made more generic.
        Hide
        Randall Hauch added a comment -
        The following sections in the (original) Atom Binding document would need to be addressed:

        Section 2.3.3 "Service Document" - This section does not point out that the URL for the Service Document (e.g., "/s-ramp/serviceDocument") is the only fixed/pre-defined URL, and that all other URLs should be determined by accessing the Service Document. It should also probably point out that although the "/s-ramp/{artifactModel}/{artifactType}" form used in the rest of the document's examples are merely possible URL forms and not mandated by the specification. Suggested wording here would be appreciated. This may need to be made as visible as possible using a Note.

        Section 2.3.5 and subsections - Describe how artifacts are published and often refer to collections (e.g., "/s-ramp/xsd") and other URLs. However, many of these are examples, so they may be acceptable as is, although those that don't mention the Service Document URLs should probably do that.

        Section 3.3.1 appears to require that all stored queries are accessible at "/s-ramp/queries". I assume this should be changed to say that they are accessible at a collection defined in the Service Document, which may be "/s-ramp/queries". Other opinions?

        Appendix B "S-RAMP URI Space" - This appendix describes the URI space that appears to be expected, but per this issue it needs to be changed to say the presented URI space is one example of a URI space used by an implementation.

        Section 2.3.5.2.2 "Publishing Using POST of ZIP files" - This section mandates that ZIP files should be posted to the "/s-ramp" URI space. Should this be specified in the Service Document, or should the spec maintain this requirement?
        Show
        Randall Hauch added a comment - The following sections in the (original) Atom Binding document would need to be addressed: Section 2.3.3 "Service Document" - This section does not point out that the URL for the Service Document (e.g., "/s-ramp/serviceDocument") is the only fixed/pre-defined URL, and that all other URLs should be determined by accessing the Service Document. It should also probably point out that although the "/s-ramp/{artifactModel}/{artifactType}" form used in the rest of the document's examples are merely possible URL forms and not mandated by the specification. Suggested wording here would be appreciated. This may need to be made as visible as possible using a Note. Section 2.3.5 and subsections - Describe how artifacts are published and often refer to collections (e.g., "/s-ramp/xsd") and other URLs. However, many of these are examples, so they may be acceptable as is, although those that don't mention the Service Document URLs should probably do that. Section 3.3.1 appears to require that all stored queries are accessible at "/s-ramp/queries". I assume this should be changed to say that they are accessible at a collection defined in the Service Document, which may be "/s-ramp/queries". Other opinions? Appendix B "S-RAMP URI Space" - This appendix describes the URI space that appears to be expected, but per this issue it needs to be changed to say the presented URI space is one example of a URI space used by an implementation. Section 2.3.5.2.2 "Publishing Using POST of ZIP files" - This section mandates that ZIP files should be posted to the "/s-ramp" URI space. Should this be specified in the Service Document, or should the spec maintain this requirement?
        Hide
        Randall Hauch added a comment -
        Targeted proposed changes to the docs by Monday July 25.
        Show
        Randall Hauch added a comment - Targeted proposed changes to the docs by Monday July 25.
        Hide
        Randall Hauch added a comment -
        My proposal for the changes to the Foundation document have been uploaded to the S-RAMP document space, and is available at http://www.oasis-open.org/apps/org/workgroup/s-ramp/document.php?document_id=44002

        This change, however, will make it more difficult to define the query language, because the query grammar now depends on the structure of the URIs. So I think there are several possible approaches to take in resolving this issue, and I plan on discussing these options and coming to an agreement on the desired course of action during the upcoming virtual F2F meeting on October 24-26. The possible approaches are:

        1) Leave the "/s-ramp/{ModelType}/{ArtifactType}" syntax for the URIs and query grammar, but change the Atom Binding to expose this structure in the service document. In other words, the structure remains fixed whereas the service document would follow good RESTful conventions by dynamically exposing this structure (and any implementation-specific model types or artifact types).

        2) Decouple the query grammar from the literal resource URI structure: continue to use the "/s-ramp/{ModelType}/{ArtifactType}" syntax in the query grammar (where the syntax would define the logical structure used for constraints), but repository implementations are free to use a completely different resource URI structure and would expose this structure within the service document. I'm not sure if this approach even makes sense.

        3) No longer define the resource URI structure for use by the repository and queries. The "location-path" rule within the query grammar would need to be made more general, and the variations in the current rule would need more description. The proposed changes to the Foundation document mentioned capture this approach, though I would like some suggestions for exactly how to change the "location-path" rule.
        Show
        Randall Hauch added a comment - My proposal for the changes to the Foundation document have been uploaded to the S-RAMP document space, and is available at http://www.oasis-open.org/apps/org/workgroup/s-ramp/document.php?document_id=44002 This change, however, will make it more difficult to define the query language, because the query grammar now depends on the structure of the URIs. So I think there are several possible approaches to take in resolving this issue, and I plan on discussing these options and coming to an agreement on the desired course of action during the upcoming virtual F2F meeting on October 24-26. The possible approaches are: 1) Leave the "/s-ramp/{ModelType}/{ArtifactType}" syntax for the URIs and query grammar, but change the Atom Binding to expose this structure in the service document. In other words, the structure remains fixed whereas the service document would follow good RESTful conventions by dynamically exposing this structure (and any implementation-specific model types or artifact types). 2) Decouple the query grammar from the literal resource URI structure: continue to use the "/s-ramp/{ModelType}/{ArtifactType}" syntax in the query grammar (where the syntax would define the logical structure used for constraints), but repository implementations are free to use a completely different resource URI structure and would expose this structure within the service document. I'm not sure if this approach even makes sense. 3) No longer define the resource URI structure for use by the repository and queries. The "location-path" rule within the query grammar would need to be made more general, and the variations in the current rule would need more description. The proposed changes to the Foundation document mentioned capture this approach, though I would like some suggestions for exactly how to change the "location-path" rule.
        Hide
        Randall Hauch added a comment -
        During the Virtual Face to Face meeting on October 26, Vince noted that the intent of the original S-RAMP specification was that the structure used in the query grammar is not tied to the URI structure used for interacting with governed resources, and any similarity was coincidental. Therefore, option 3 appears to be closest to this original intent.

        I will suggest changes to the Foundation and Atom Binding documents to reflect this direction, and will submit them for review and approval.
        Show
        Randall Hauch added a comment - During the Virtual Face to Face meeting on October 26, Vince noted that the intent of the original S-RAMP specification was that the structure used in the query grammar is not tied to the URI structure used for interacting with governed resources, and any similarity was coincidental. Therefore, option 3 appears to be closest to this original intent. I will suggest changes to the Foundation and Atom Binding documents to reflect this direction, and will submit them for review and approval.
        Hide
        Randall Hauch added a comment -
        Actually, my previous comment states "Therefore, option 3 appears to be closest to this original intent." During a weekly telecon, we confirmed that this should refer to option 2 (which is compatible with the rest of my comment).
        Show
        Randall Hauch added a comment - Actually, my previous comment states "Therefore, option 3 appears to be closest to this original intent." During a weekly telecon, we confirmed that this should refer to option 2 (which is compatible with the rest of my comment).
        Hide
        Eric Wittmann added a comment -
        Resolved and ready to be incorporated into both the foundation and binding docs.
        Show
        Eric Wittmann added a comment - Resolved and ready to be incorporated into both the foundation and binding docs.
        Hide
        Eric Wittmann added a comment -
        Changes have been made to the foundation doc. Next is to incorporate binding doc changes.
        Show
        Eric Wittmann added a comment - Changes have been made to the foundation doc. Next is to incorporate binding doc changes.

          People

          • Assignee:
            Vincent Brunssen
            Reporter:
            Vincent Brunssen
          • Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: