We're using maven-enunciate-plugin version 1.26.2 and are encountering an issue during the generation of our documentation. We have added comments to our XSDs in the following manner:
<xs:complexType name="PagingParameters">
<xs:annotation>
<xs:documentation>information about PagingParameters</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:choice minOccurs="0">
<xs:element name="StartPos" type="xs:long" nillable="false">
<xs:annotation>
<xs:documentation>information about StartPos</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="FollowOnBrowseToken" type="xs:string" nillable="false">
<xs:annotation>
<xs:documentation>information about token</xs:documentation>
</xs:annotation>
</xs:element>
</xs:choice>
<xs:element name="NoOfRecords" type="xs:long" nillable="false">
<xs:annotation>
<xs:documentation>information about noOfRecords</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
The first set gets parsed and outputs correctly on the enunciate page, however all of the comments for the individual elements therein are completely lost. Oddly enough this only happens with sequences of elements, but enumerations work just fine.
I've tried a few different means of formatting the documentation, including the use of CDATA blocks, but nothing seems to quite be working.
What am I missing? If needed I can include more of the XSD.
Enunciate uses JavaDoc to parse its documentation. Can you confirm the JavaDoc is showing up in the generated Java classes?
Javadoc do NOT show up in the generated-classes but then jaxb overwrites this with their own standard comment like this:
/**
* Gets the value of the X property.
*
* #return
* possible object is
* {#link String }
*
*/
public String getX() {
but still no javadoc is shown in enuciate
Related
I have the following XSD structure:
<xs:schema xmlns:ns="http://abc/">
...
<xs:element name="abc">
<xs:complexType>
<xs:sequence>
<xs:element ref="map"/>
</xs:sequence>
</xs:complexType>
</xs:element>
...
<xs:element name="map">
<xs:complexType>
<xs:sequence>
<xs:element name="entry" type="ns:MapEntryType" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:unique name="entry">
<xs:selector xpath="entry"/>
<xs:field xpath="key"/>
</xs:unique>
</xs:element>
<xs:complexType name="MapEntryType">
<xs:sequence>
<xs:element name="key" type="xs:string"/>
<xs:element name="value" type="xs:anyType"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
This is doing its job.
The map element now has to be called something different based on whichever is the wrapper, so the name is sometimes map, sometimes properties, sometimes options, etc.
Therefore I want to genericize the map element.
I tried doing the following:
Making map a xs:complexType and changing ref to type.
This resulted in xs:unique not being accepted and failed
Making map a xs:complexType, changing ref to type and moving the xs:unique constraint to the element definitions.
This worked but resulted in the XSD having a lot of xs:unique present in the document.
Isn't there a way to simply tell that I want a specific structure and it containing unique elements without having to repeat the unique constraint everywhere?
As Petru Gardea said in his answer
Both XSD 1.0 and 1.1 place the identity constraints under an element
So you have to add xs:unique to every element, but if you are using XSD 1.1 you can define only once a complete xs:unique and then in the rest of the elements use xs:unique ref="name". This is not valid for you as you are using XSD 1.0, but I let it here for future XSD 1.1 users that find this good question.
Example (namespaces removed for clarity):
<xs:element name="map">
<xs:complexType>
<xs:sequence>
<xs:element name="entry" type="MapEntryType" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<!-- Only completely defined once -->
<xs:unique name="uniqueEntry">
<xs:selector xpath="entry"/>
<xs:field xpath="key"/>
</xs:unique>
</xs:element>
<xs:element name="hashMap">
<xs:complexType>
<xs:sequence>
<xs:element name="entry" type="MapEntryType" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<!-- Referenced here and every other time -->
<xs:unique ref="uniqueEntry"/>
</xs:element>
Short answer, it is not possible. Both XSD 1.0 and 1.1 place the identity constraints under an element; a constraint cannot be globally defined, therefore there is no "reuse" per se, other than that of the enclosing element. Given your scenario (different element names for different needs) it is not possible to reuse.
I am creating an XSD for the following XML structure:
<BaseNode>
<ParentNode1>
<childnode/>
</ParentNode1>
<ParentNode2>
<childnode/>
</ParentNode2>
<ParentNodeA>
<childnode/>
</ParentNodeA>
<ParentNodeB>
<childnode/>
</ParentNodeB>
</BaseNode>
Where: ParentNodes 1 and 2 must appear and in order, and A and B are optional (and will only appear once each, if present), but must appear after 1 and 2 if present.
What I 'think' will work is the following, but is it valid? (specifically, the presence of both, sequence and all Order Indicators)
<xs:element name="BaseNode">
<xs:complexType>
<xs:sequence>
<xs:element name="ParentNode1">
....
</xs:element>
<xs:element name="ParentNode2">
....
</xs:element>
</xs:sequence>
<xs:all>
<xs:element name="ParentNodeA">
....
</xs:element>
<xs:element name="ParentNodeB">
....
</xs:element>
</xs:all>
</xs:comlexType>
</xs:element>
I couldn't find any reference (in w3schools.com or elsewhere) to compound use of order indicators, and don't have a validator readily available.
Thank you in advance.
I found the answer at http://www.w3.org/TR/xmlschema-0/#groups
XML Schema stipulates that an all group must
appear as the sole child at the top of a content model.
example provided at the link.
Is it possible to distinct xs:choices in xsd by using fixed values? I have a simple type:
<xs:simpleType name="datatypeCategory">
<xs:restriction base="xs:string">
<xs:enumeration value="SIMPLE"/>
<xs:enumeration value="COMPLEX"/>
<xs:enumeration value="COLLECTION"/>
</xs:restriction>
</xs:simpleType>
And what I want to achieve is
<xs:element name="datatype">
<xs:complexType>
<xs:choice>
<xs:sequence>
<xs:element id="category" type="datatypeCategory" fixed="SIMPLE"/>
<!-- some fields specific for SIMPLE -->
</xs:sequence>
<xs:sequence>
<xs:element id="category" type="datatypeCategory" fixed="COMPLEX"/>
<!-- some fields specific for COMPLEX -->
</xs:sequence>
<xs:sequence>
<xs:element id="category" type="datatypeCategory" fixed="COLLECTION"/>
<!-- some fields specific for COLLECTION -->
</xs:sequence>
</xs:choice>
</xs:complexType>
</xs:element>
When I do this my XMLSpy tells me:
# The content model of complex type definition '{anonymous}' is ambiguous.
# Details: cos-nonambig: <xs:element name='category'> makes the content model non-deterministic against <xs:element name='category'>. Possible causes: name equality, overlapping occurrence or substitution groups.
You can't do exactly that. The error is because a simple validator that sees a <category> element won't immediately know which branch of the choice to take, and XML Schema 1.0 supports such simple validators.
An alternative would be to name each element according to the category.
<xs:element name="datatype">
<xs:complexType>
<xs:choice>
<xs:sequence>
<xs:element name="simpleCategory" type="empty"/>
<!-- some fields specific for SIMPLE -->
</xs:sequence>
<xs:sequence>
<xs:element name="complexCategory" type="empty"/>
<!-- some fields specific for COMPLEX -->
</xs:sequence>
<xs:sequence>
<xs:element name="collectionCategory" type="empty"/>
<!-- some fields specific for COLLECTION -->
</xs:sequence>
</xs:choice>
</xs:complexType>
</xs:element>
where empty is defined as an empty type. Or give them complex types to hold the "specific fields". There are other alternatives depending on your constraints, such as using substitution groups or derived complex types.
In general though, XML Schema 1.0 is not good for constraints based on interrelated values. For that, you have to go to XML Schema 1.1 or an external tool.
IDs must be unique within a document. You can't use the same value on multiple elements:
http://www.w3.org/TR/2006/REC-xml11-20060816/#id
In the following schema I am trying to make an unordered xml that extends simpleConfigurationObject:
<xs:complexType name="forTestingConfigurationObjectCreator">
<xs:complexContent>
<xs:extension base="simpleConfigurationObject">
<xs:all>
<xs:element name="a" type="xs:string"/>
<xs:element name="b" type="xs:string" minOccurs="0"/>
</xs:all>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="simpleConfigurationObject">
<xs:all>
<xs:element name="base" type="xs:string" minOccurs="0"/>
</xs:all>
</xs:complexType>
But I get the following error on the xs:all
"all is not the only particle in the group, or is being used as an extension" (which is correct)
Off-course if put the base element inside the xs:all and not use xs:extension at all I will get an unordered schema restriction. (but that is not what I want)
The question is: how can I produce unordered schema with the extension?
Thanks
You can't, this is prohibited by the schema specification. See this post of Henry Thompson (the author of the spec) for an explanation.
In short: the content model of the base type has to be completely parsed by the time the parser gets to the derived type; that is not possible with what you are trying to achieve.
I've inherited the task of creating a schema for some XML which already exists - and IMHO is not the best that could have been done. The section giving me problems is the element at the end of the 'scan-result' element.
The best I'm hoping for with regard to the data in the 'spectrum' element is to treat it as type="xs:string". I'll programatically divide up the numeric pairs that constitute the data in the string later. (Even though this step would not be needed had the data been properly structured in the first place.)
Here's a similar piece of XML data to what I have to work with...
<scan-result>
<spectrum-index>0</spectrum-index>
<scan-index>2</scan-index>
<time-stamp>5609</time-stamp>
<tic>55510</tic>
<start-mass>22.0</start-mass>
<stop-mass>71.0</stop-mass>
<spectrum count="5">30,11352;31,360;32,16634;45,1161;46,26003</spectrum>
</scan-result>
The problem is, I can't seem to get a working definition for the 'spectrum' element that has the 'count' attribute and allows me to define the 'spectrum' element type as "xs:string".
What I would like is something like the following:
<xs:complexType name="ctypScanResult">
<xs:sequence>
<xs:element name="spectrum-index" type="xs:integer"/>
<xs:element name="scan-index" type="xs:integer"/>
<xs:element name="time-stamp" type="xs:integer"/>
<xs:element name="tic" type="xs:integer"/>
<xs:element name="start-mass" type="xs:float"/>
<xs:element name="stop-mass" type="xs:float"/>
<xs:element name="spectrum" type="xs:string">
<xs:complexType>
<xs:attribute name="count" type="xs:integer"/>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="count" type="xs:integer"/>
</xs:complexType>
The problem is that I can define the type of the 'spectrum' element as "xs:string" XOR I can define the anonymous 'xs:complexType' in the 'spectrum' element, which allows me to insert the 'count' attribute. But I need to be able to express both.
Given that I'm kind of stuck with the XML as it was handed to me, is there a schema definition that will allow me to describe this data?
Sorry this is long, but thanks to any and all who respond,
AlarmTripper
Followup: I know why the error occurs...
Quoted from W3C:
3.3.3 Constraints on XML Representations of Element Declarations
Schema Representation Constraint: Element Declaration Representation OK
In addition to the conditions imposed on element information items by the schema for schemas: all of the following must be true:
1 default and fixed must not both be present.
2 If the item's parent is not , then all of the following must be true:
2.1 One of ref or name must be present, but not both.
2.2 If ref is present, then all of , , , , , nillable, default, fixed, form, block and type must be absent, i.e. only minOccurs, maxOccurs, id are allowed in addition to ref, along with .
3 type and either or are mutually exclusive.
4 The corresponding particle and/or element declarations must satisfy the conditions set out in Constraints on Element Declaration Schema Components (§3.3.6) and Constraints on Particle Schema Components (§3.9.6).
But I'm still in the same fix I was before... How can I actually accomplish something that resembles my goal?
Thanks,
AlarmTripper
Let a tool do it for you! Try xsd.exe.
Or, if you must define by hand, at least check your hand-written-definition with an automatically generated one.
Here's what XSD.exe gave me for your input. I trimmed out some MS-NS cruft.
<xs:element name="spectrum">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="count" type="xs:string" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
You need to set the attribute mixed="true" on complexType:
<xs:element name="spectrum">
<xs:complexType mixed="true">
<xs:attribute name="count" type="xs:integer" />
</xs:complexType>
</xs:element>
EDIT: Okay, just read your comment, sorry. I believe the following should work instead:
<xs:element name="spectrum">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="count" type="xs:integer" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="spectrum" type="xs:string">
<xs:complexType>
<!-- ADD THIS NEXT LINE -->
<xs:complexContent mixed="true"/>
<xs:attribute name="count" type="xs:integer"/>
</xs:complexType>
</xs:element>