9 Replies Latest reply on Sep 12, 2008 6:47 AM by accountclosed

    Pages.xsd Schema Issues

    accountclosed

      Hello Seam Developers,


      In my quest to better understand the pages.xml file (and accompanying schema), I've been going through the pages.xsd file and I've come up with some suggestions regarding the pages.xsd - pages schema 2.0 (although these also apply to 2.1 as well).




      1.) Enforcement of schema rules


      The pages element contains a sequence of a choice between conversation elements and page elements unbounded so as many as you want, and after that, an unbounded number of exception elements. However, if one places the exceptions up at the top (i.e., before any page or conversation elements), the application runs just fine. IOW, the schema rule is not being enforced. This rule should either be enforced by the application or replaced with:



      <xs:element name="pages">
        <xs:complexType>
          <xs:sequence minOccurs="0" maxOccurs="unbounded">
            <xs:element ref="pages:conversation"/>
            <xs:element ref="pages:page"/>
            <xs:element ref="pages:exception"/>
          </xs:sequence>
          <xs:attributeGroup ref="pages:attlist.pages"/>
        </xs:complexType>
      </xs:element>




      Same issue with the exception element ... the end-conversation element having to be at the beginning is not being enforced. I'm assuming that this should be enforced.


      Other rules not being enforced (or that should ... see view-id attribute in redirect's view-id attribute) include:




      • exception element doesn't enforce order of end-conversation, http-error redirect respectively

      • both http-error and redirect allow many messages, schema reports to only allow zero or one

      • redirect view-id attribute should be of type IDREF or xs:keyref, don't want to point to a page that doesn't exist right?

      • http-error error-code attribute should be required(?)




      These enforcement rules should either be taken out or they should be enforced. Leaving as is causes confusion and unwanted bug reports which may not in fact be due to bugs.




      2.) Using Regex to clarify allowable values


      The use of regex would greatly help narrow what a user (us app developers). For example, the view-id attribute of the page element accepts ... a view id. Why not restrict it like this:



      <xs:attribute name="view-id">
        <xs:simpleType name="view-id">
            <xs:restriction base="xsd:NMTOKEN">
                <xs:pattern value="/.*"/>
            </xs:restriction>
        </xs:simpleType>
      </xs:attribute>




      If one wanted, a narrowing of scope could further the selection to something like:


      <xs:attribute name="view-id">
        <xs:simpleType name="view-id">
            <xs:restriction base="xsd:NMTOKEN">
                <xs:pattern value="/.*\..*"/>
            </xs:restriction>
        </xs:simpleType>
      </xs:attribute>




      Or even:


      <xs:attribute name="view-id">
        <xs:simpleType name="view-id">
            <xs:restriction base="xsd:NMTOKEN">
                <xs:pattern
                value="/.*\.(\.seam|\.html|\.xhtml|.\jsp)"/>
            </xs:restriction>
        </xs:simpleType>
      </xs:attribute>



      But that would probably be too restrictive (someone might complain that they can't create a page called index.monkey)


      Restrict page element's
      conversation attribute to being token
      scheme to being either http or https




      3.) Schema Annotation/Documentation


      Although the new 2.1 pages xsd has been fleshed out a bit more (and even annotation and documentation elements are included now), there is minimal documentation inside of this schema. Simply stating the obvious (e.g., 'Page action' for the action element) doesn't help app developers fully understand the intentions of particular elements. Fleshing the xsd schema out more will also help (you) the framework developers in solidifying the contract each element has with API calls possibly written by someone else.




      Summary



      This sort of check really should be performed at the beginning of the startup procedure and belch validation exceptions if the user has not provided a valid pages.xml file.


      Anyways, these are the ones that I've had a chance to play with so there could be others. I hope this doesn't come off as trolling, intonation gets lost in forum posts and so I just wanted to be clear that I'm not writing this out of anger but rather enthusiasm about this framework and particularly understanding the pages.xsd document and being able to use it correctly. One thing that I've been really trying to avoid is potentially filing out a bug report when in fact it's simply user error ... that would be embarrassing.


      Anyways, if need be I will file a JIRA report. Let me know ...


      Arron

        • 1. Re: Pages.xsd Schema Issues
          pmuir

          Arron Ferguson wrote on Sep 05, 2008 04:19:


          1.) Enforcement of schema rules
          The pages element contains a sequence of a choice between conversation elements and page elements unbounded so as many as you want, and after that, an unbounded number of exception elements. However, if one places the exceptions up at the top (i.e., before any page or conversation elements), the application runs just fine. IOW, the schema rule is not being enforced. This rule should either be enforced by the application or replaced with:


          <xs:element name="pages">
            <xs:complexType>
              <xs:sequence minOccurs="0" maxOccurs="unbounded">
                <xs:element ref="pages:conversation"/>
                <xs:element ref="pages:page"/>
                <xs:element ref="pages:exception"/>
              </xs:sequence>
              <xs:attributeGroup ref="pages:attlist.pages"/>
            </xs:complexType>
          </xs:element>





          Better still:


          <xs:element name="pages">
                  <xs:annotation>
                      <xs:documentation>The root of a pages.xml file</xs:documentation>
                  </xs:annotation>
                  <xs:complexType>
                      <xs:choice minOccurs="0" maxOccurs="unbounded">
                          <xs:element ref="pages:conversation"/>
                          <xs:element ref="pages:page"/>
                          <xs:element minOccurs="0" maxOccurs="unbounded" ref="pages:exception"/>
                      </xs:choice>
                      <xs:attributeGroup ref="pages:attlist.pages"/>
                  </xs:complexType>
              </xs:element>



          I fixed this.



          Same issue with the exception element ... the end-conversation element having to be at the beginning is not being enforced. I'm assuming that this should be enforced.


          I don't know XSD well enough to fix this. The rule we need is any order, end-conversation is optional, and must have either http-error OR redirect





          • both http-error and redirect allow many messages, schema reports to only allow zero or one





          Only the first one will be used





          • redirect view-id attribute should be of type IDREF or xs:keyref, don't want to point to a page that doesn't exist right?





          That's fine, Seam supports virtual pages, and also pages that aren't specified in pages.xml





          • http-error error-code attribute should be required(?)





          Agreed. I fixed this.




          2.) Using Regex to clarify allowable values
          The use of regex would greatly help narrow what a user (us app developers). For example, the view-id attribute of the page element accepts ... a view id. Why not restrict it like this:


          <xs:attribute name="view-id">
            <xs:simpleType name="view-id">
                <xs:restriction base="xsd:NMTOKEN">
                    <xs:pattern value="/.*"/>
                </xs:restriction>
            </xs:simpleType>
          </xs:attribute>





          Ok, I applied:


          <xs:simpleType name="view-id">
                  <xs:restriction base="xs:string">
                      <xs:pattern value="(/.*)|\*"/>
                  </xs:restriction>
              </xs:simpleType>



          which seems correct to me




          If one wanted, a narrowing of scope could further the selection to something like:

          <xs:attribute name="view-id">
            <xs:simpleType name="view-id">
                <xs:restriction base="xsd:NMTOKEN">
                    <xs:pattern value="/.*\..*"/>
                </xs:restriction>
            </xs:simpleType>
          </xs:attribute>




          Or even:

          <xs:attribute name="view-id">
            <xs:simpleType name="view-id">
                <xs:restriction base="xsd:NMTOKEN">
                    <xs:pattern
                    value="/.*\.(\.seam|\.html|\.xhtml|.\jsp)"/>
                </xs:restriction>
            </xs:simpleType>
          </xs:attribute>



          But that would probably be too restrictive (someone might complain that they can't create a page called index.monkey)



          Neither of these are valid, there is no requirement a view id must end in .*





          • Restrict page element's conversation attribute to being token





          I don't think this will work, as conversations can be declared in another pages.xml file.





          • scheme to being either http or https





          File an issue for this, I need to think about it.




          3.) Schema Annotation/Documentation
          Although the new 2.1 pages xsd has been fleshed out a bit more (and even annotation and documentation elements are included now), there is minimal documentation inside of this schema. Simply stating the obvious (e.g., 'Page action' for the action element) doesn't help app developers fully understand the intentions of particular elements. Fleshing the xsd schema out more will also help (you) the framework developers in solidifying the contract each element has with API calls possibly written by someone else.


          Totally agreeed. Want to write a patch with what you know/can garner from the docs? We need these for all the components.xsd as well...





          This sort of check really should be performed at the beginning of the startup procedure and belch validation exceptions if the user has not provided a valid pages.xml file.



          Yes, I don't know why we aren't validating .xml against the schema (Norman does I think). You could open an issue about this.



          Anyways, these are the ones that I've had a chance to play with so there could be others. I hope this doesn't come off as trolling, intonation gets lost in forum posts and so I just wanted to be clear that I'm not writing this out of anger but rather enthusiasm about this framework and particularly understanding the pages.xsd document and being able to use it correctly. One thing that I've been really trying to avoid is potentially filing out a bug report when in fact it's simply user error ... that would be embarrassing.

          Anyways, if need be I will file a JIRA report. Let me know ...



          Please use JIRA for this, it's the right forum as it includes notification, tracking, release note generation etc. The worst that happens is we reject your issue, and if you report an issue clearly like above that won't happen!


          And thanks for your help - this attention to detail is really important!

          • 2. Re: Pages.xsd Schema Issues
            christian.bauer

            Pete Muir wrote on Sep 05, 2008 13:43:


            Yes, I don't know why we aren't validating .xml against the schema (Norman does I think). You could open an issue about this.



            https://jira.jboss.org/jira/browse/JBSEAM-2938

            • 3. Re: Pages.xsd Schema Issues
              accountclosed

              Pete Muir wrote on Sep 05, 2008 13:43:

              Better still:

              <xs:element name="pages">
                      <xs:annotation>
                          <xs:documentation>The root of a pages.xml 
                            file</xs:documentation>
                      </xs:annotation>
                      <xs:complexType>
                          <xs:choice minOccurs="0" 
                            maxOccurs="unbounded">
                              <xs:element ref="pages:conversation"/>
                              <xs:element ref="pages:page"/>
                              <xs:element minOccurs="0"
                            maxOccurs="unbounded"
                              ref="pages:exception"/>
                          </xs:choice>
                          <xs:attributeGroup
                            ref="pages:attlist.pages"/>
                      </xs:complexType>
                  </xs:element>



              I fixed this.



              Actually you can take the minoccurs and maxoccurs out of the pages:exception reference, it's superfluous since the choice is already doing this.





              Same issue with the exception element ... the end-conversation element having to be at the beginning is not being enforced. I'm assuming that this should be enforced.


              I don't know XSD well enough to fix this. The rule we need is any order, end-conversation is optional, and must have either http-error OR redirect



              I've been using XSD for a few years now so I can change this for you if you'd like.







              • both http-error and redirect allow many messages, schema reports to only allow zero or one





              Only the first one will be used



              Validation at startup will take care of this.







              • redirect view-id attribute should be of type IDREF or xs:keyref, don't want to point to a page that doesn't exist right?





              That's fine, Seam supports virtual pages, and also pages that aren't specified in pages.xml



              Good point. In that case IDREF or xs:keyref would be inappropriate.







              • http-error error-code attribute should be required(?)





              Agreed. I fixed this.



              2.) Using Regex to clarify allowable values
              The use of regex would greatly help narrow what a user (us app developers). For example, the view-id attribute of the page element accepts ... a view id. Why not restrict it like this:


              <xs:attribute name="view-id">
                <xs:simpleType name="view-id">
                    <xs:restriction base="xsd:NMTOKEN">
                        <xs:pattern value="/.*"/>
                    </xs:restriction>
                </xs:simpleType>
              </xs:attribute>





              Ok, I applied:

              <xs:simpleType name="view-id">
                      <xs:restriction base="xs:string">
                          <xs:pattern value="(/.*)|\*"/>
                      </xs:restriction>
                  </xs:simpleType>



              which seems correct to me



              If one wanted, a narrowing of scope could further the selection to something like:

              <xs:attribute name="view-id">
                <xs:simpleType name="view-id">
                    <xs:restriction base="xsd:NMTOKEN">
                        <xs:pattern value="/.*\..*"/>
                    </xs:restriction>
                </xs:simpleType>
              </xs:attribute>




              Or even:

              <xs:attribute name="view-id">
                <xs:simpleType name="view-id">
                    <xs:restriction base="xsd:NMTOKEN">
                        <xs:pattern
                        value="/.*\.(\.seam|\.html|\.xhtml|.\jsp)"/>
                    </xs:restriction>
                </xs:simpleType>
              </xs:attribute>



              But that would probably be too restrictive (someone might complain that they can't create a page called index.monkey)



              Neither of these are valid, there is no requirement a view id must end in .*



              Ah yes, you're right. The starting slash is about the only thing you can restrict.








              • Restrict page element's conversation attribute to being token





              I don't think this will work, as conversations can be declared in another pages.xml file.



              xs:token collapses whitespace (i.e., all whitespace replaced with single spaces, trailing spaces have been removed. But if this may be an issue, leaving it is okay too.








              • scheme to being either http or https





              File an issue for this, I need to think about it.



              Done, it's here:


              3387






              3.) Schema Annotation/Documentation
              Although the new 2.1 pages xsd has been fleshed out a bit more (and even annotation and documentation elements are included now), there is minimal documentation inside of this schema. Simply stating the obvious (e.g., 'Page action' for the action element) doesn't help app developers fully understand the intentions of particular elements. Fleshing the xsd schema out more will also help (you) the framework developers in solidifying the contract each element has with API calls possibly written by someone else.


              Totally agreeed. Want to write a patch with what you know/can garner from the docs? We need these for all the components.xsd as well...


              Sure, I can do that as well as the changes suggested above (where order doesn't matter). Can you point me to the latest pages.xsd on SVN so I can grab the most recent? That way updating won't be too much of a headache. At which point I can either email you or post here(?) the updates.





              This sort of check really should be performed at the beginning of the startup procedure and belch validation exceptions if the user has not provided a valid pages.xml file.



              Yes, I don't know why we aren't validating .xml against the schema (Norman does I think). You could open an issue about this.



              Done. Made it a feature request since I don't think it's considered a bug. Found here: 3388






              Anyways, these are the ones that I've had a chance to play with so there could be others. I hope this doesn't come off as trolling, intonation gets lost in forum posts and so I just wanted to be clear that I'm not writing this out of anger but rather enthusiasm about this framework and particularly understanding the pages.xsd document and being able to use it correctly. One thing that I've been really trying to avoid is potentially filing out a bug report when in fact it's simply user error ... that would be embarrassing.

              Anyways, if need be I will file a JIRA report. Let me know ...



              Please use JIRA for this, it's the right forum as it includes notification, tracking, release note generation etc. The worst that happens is we reject your issue, and if you report an issue clearly like above that won't happen!

              And thanks for your help - this attention to detail is really important!


              You're welcome. Just checking. :)

              • 4. Re: Pages.xsd Schema Issues
                accountclosed

                Whoa, that was fast ... you beat me to the punch. :)


                Mine is at: https://jira.jboss.org/jira/browse/JBSEAM-3388


                Sound similar but if mine's a duplicate, close mine.

                • 5. Re: Pages.xsd Schema Issues
                  pmuir

                  Arron Ferguson wrote on Sep 05, 2008 18:21:


                  Actually you can take the minoccurs and maxoccurs out of the pages:exception reference, it's superfluous since the choice is already doing this.



                  Done.






                  Same issue with the exception element ... the end-conversation element having to be at the beginning is not being enforced. I'm assuming that this should be enforced.


                  I don't know XSD well enough to fix this. The rule we need is any order, end-conversation is optional, and must have either http-error OR redirect



                  I've been using XSD for a few years now so I can change this for you if you'd like.



                  Please - just attach a unified diff to JIRA :-)








                  • Restrict page element's conversation attribute to being token





                  I don't think this will work, as conversations can be declared in another pages.xml file.



                  xs:token collapses whitespace (i.e., all whitespace replaced with single spaces, trailing spaces have been removed. But if this may be an issue, leaving it is okay too.


                  I don't understand how these comments are related..??








                  3.) Schema Annotation/Documentation
                  Although the new 2.1 pages xsd has been fleshed out a bit more (and even annotation and documentation elements are included now), there is minimal documentation inside of this schema. Simply stating the obvious (e.g., 'Page action' for the action element) doesn't help app developers fully understand the intentions of particular elements. Fleshing the xsd schema out more will also help (you) the framework developers in solidifying the contract each element has with API calls possibly written by someone else.


                  Totally agreeed. Want to write a patch with what you know/can garner from the docs? We need these for all the components.xsd as well...


                  Sure, I can do that as well as the changes suggested above (where order doesn't matter). Can you point me to the latest pages.xsd on SVN so I can grab the most recent? That way updating won't be too much of a headache. At which point I can either email you or post here(?) the updates.


                  https://svn.jboss.org/repos/seam/trunk/src/main/org/jboss/seam/ - just use trunk. Post a patch in JIRA in unified diff format.

                  • 6. Re: Pages.xsd Schema Issues
                    accountclosed

                    Pete Muir wrote on Sep 05, 2008 19:51:




                    • Restrict page element's conversation attribute to being token






                    xs:token collapses whitespace (i.e., all whitespace replaced with single spaces, trailing spaces have been removed. But if this may be an issue, leaving it is okay too.


                    I don't understand how these comments are related..??


                    If I understand correctly you were concerned with xs:token being used for conversation attribute type. I was saying that xs:token simply collapses whitespace down to a single white space (I suppose you could further restrict if you wanted). Maybe I misunderstood what you meant.



                    https://svn.jboss.org/repos/seam/trunk/src/main/org/jboss/seam/ - just use trunk. Post a patch in JIRA in unified diff format.


                    Sure, gotcha. I'll do that. May take a few days though.


                    Regards,


                    Arron

                    • 7. Re: Pages.xsd Schema Issues
                      pmuir

                      Arron Ferguson wrote on Sep 05, 2008 22:09:



                      Pete Muir wrote on Sep 05, 2008 19:51:




                      • Restrict page element's conversation attribute to being token






                      xs:token collapses whitespace (i.e., all whitespace replaced with single spaces, trailing spaces have been removed. But if this may be an issue, leaving it is okay too.


                      I don't understand how these comments are related..??


                      If I understand correctly you were concerned with xs:token being used for conversation attribute type. I was saying that xs:token simply collapses whitespace down to a single white space (I suppose you could further restrict if you wanted). Maybe I misunderstood what you meant.



                      No, I think I misunderstood how xs:token works. File a JIRA issue, we can check it out :)

                      • 8. Re: Pages.xsd Schema Issues
                        accountclosed

                        Pete Muir wrote on Sep 05, 2008 19:51:


                        https://svn.jboss.org/repos/seam/trunk/src/main/org/jboss/seam/ - just use trunk. Post a patch in JIRA in unified diff format.


                        Authorization required :(

                        • 9. Re: Pages.xsd Schema Issues
                          accountclosed

                          I've filed the following at JIRA:


                          https://jira.jboss.org/jira/browse/JBSEAM-3414