I designed a data model which is represented by an XSD scheme.
The data model also provides the types that are being used as web service parameters in a WSDL descriptor.
I would like to send the XSD scheme around and ask the people involved to peer review the data model.
What tool or presentation method would you suggest to be used as a basis for peer reviews? The data model should be readable for non-skilled people, at least when it comes to the semantic meanings of the parameters
Edit:
To be more specific: Of course, syntactically, the scheme validates. Actually I'm already working on code which is based on JAXB generated classes. My goal is
to freeze the data model and thus
the input parameters
to make sure
nothing got lost or forgotten from a
semantic (in the meaning of
business-relevant) point of view.
Edit 2
I've been thinking about how it probably would be best to spread a datamodel around. I'm thinking of something like a JavaDoc for XSD schemas. Anyone knows if something like that exists? Basically it would be done with a set of XSLTs, right?
I know the following tools that generate documentation from XML Schema files (XSD):
xs3p
XSLT stylesheet that generates single XHTML from XSD
xsddoc
free / LGPL
mainly XSLT based
JavaDoc like output
see xsddoc examples
xnsdoc
improved commercial version of xsddoc
free for personal/educational use
JavaDoc like output
XSDdoc 2.0
commercial
JavaDoc like output
For small a XML schema, I would probably suggest using the xs3p XSLT stylesheet. For more a complex schema, I suggest using xsddoc.
I recommend using the XSD for something. Specifically, show some actual applications, with examples as real code.
Actual applications are what make a schema interesting. The examples don't have to be big, sophisticated or completely realistic. They just have to compile. Other people will want to copy and paste the code samples.
These examples are the "hello world" of the schema. And they act as a kind of unit test for the schema.
The closest thing to Javadoc for an XML schema that I've seen is running the Javadoc tool on source generated from the schema. This requires two things: 1) That your schema has internal annotation elements documenting it, and that 2) your source generator uses those annotations as Javadoc elements.
The very useful Oxygen XML developer also supports generating documentation, see
http://www.oxygenxml.com/xml_schema_documentation.html
(commercial, but there's a fully functional 30 day trial available)
I'll try it out now, need a simple way to generate a document with all types and available xsd:documentation description as a simple interface description...
** Disclosure : I work for Innovasys, the producer of the documentation tool mentioned below *
You could take a look at Innovasys Document! X. As well as automatically generating a structured and linked page for every element, simple type, complex type, group and attribute group it will also generate linked XSD diagrams (including sequences/choice etc.) and structure tables that include the annotations from your XSDs and make sense of the relationships between the elements in your schemas. The output is template based so you can adapt it to your preferred style and structure. It will build output to web ready html or compiled help files.
Uniquely it also includes a WYSIWYG editor that allows you author additional content to supplement the stuff that's automatically generated and the annotations from the XSD source - so you can provide additional contextual information for your peer review. There is also a Community Extensions feature that allows people viewing the generated output to record comments and feedback and that can be viewed and actioned directly from within Document! X.
Related
I want to define some constraints for my profile. For example I need a constraint for a stereotype of the metaclass "connector". I want to define that these element must have one source like the oclkindof(source) and one target like the oclkindof(target). I found some texts by using the Google search engine like http://modeling-languages.com/wp-content/uploads/2012/03/OCLChapter.pdf or http://www.omg.org/spec/OCL/2.0/ and other slides and papers but not the right description of OCL for me.
Best regards
How to attach OCL constraints to metamodels (e.g. via stereotypes) used to vary from tool to tool.
For your project, using the Eclipse Papyrus project should suffice, which should support what you need.
In Papyrus, you can also try out OCL queries in the console on the current UML model before you store them in the profile.
We have to develop a protocol as a interface description between different systems in different companies. The implementations will be made in different languages (not known) by the developers in each company.
However, we want to develop the protocol on a textual description base together. I will have the base copy of the current version and want to send it out to all for comments.
What is a good tool to do so?
At the moment we are using MS Word what leads to several problems:
We need a lot of time for text formatting things.
Its not possible to reference to a datatype in the methods description.
The wording differs from chapter to chapter (different authors) and is hard to align.
Perfect would be:
A tool with a glossary and auto-completion.
References to other items (methods, data types, ...) with active links.
Automatic generation of a human-readable (PDF-) document.
Do you know such a tool?
PS: I did not get Sparx Systems Enterprise Architect doing the job. Maybe also hints for this one?
This is a very big question, since there are many possible aspects you may (should) wish to document in a protocol specification. The two most important ones would be data structures and message sequences, then there's error management, authentication, timing, etc etc.
UML can certainly be used to describe these things, and Enterprise Architect is eminently able to generate versatile documentation from a model - it will definitely help with your reference issues. But first you will have to determine quite strictly how each aspect of the protocol is to be modelled, and from that you will need to construct the necessary EA configuration / adaptation.
In order to get good quality documents out of EA, I recommend generating the documents from an Add-In using the Object Model's DocumentGenerator class as this gives you more flexibility than the traditional RTF generator - for one thing, you can access Word's API in addition to EA's and thus do far more with the document than is possible using EA's API alone.
Without knowing the size or complexity of your protocol, I'd say this would require at the very least a few weeks' work for someone who is experienced in writing EA adaptations. But if the scope of your project is such that there are several companies involved, it is likely to be worth the investment.
I want to represent UML models in a serialized document using the most standard conventions available. I am looking for a canonical schema document that explicitly dictates the best way to do this. I suspect that, if such a document exists, then it would be written in either XSD, RDF and OWL. So far, I have only been able to find OMG specification documents and academic papers on the subject. I have found some XSD schemas, but they only apply to a particular aspect of the implementation.
Is there a canonical document schema? Where can I find it? If not, what are the most common representation formats and where can I find their schemas?
Are there any libraries that facilitate the generation of mappings from well-formed documents of this kind to graphical representations (e.g. SVG)? The library would ideally be .NET compatible, but this is not a requirement.
Are you looking for XMI (XML Metadata Interchange)? It's an OMG spec for XML representations of UML models; the current version appears to be 2.4.1, and the spec page links to two XSD schema documents.
In theory, XMI should answer part of your first question. XMI is not, however, without perils. From my own experience trying to achieve exactly the same, I would think that the first thing to do is to understand what others did about it, and how these standard documents would be used. These days I would suggest a system setup that involves IBM RSA and Sparx Enterprise Architect (eval versions available, registration may be required, and I am not affiliated with any of these companies). Build at least one comprehensive UML model which would give you the coverage you need, in one tool, then use the XMI export/import function to move the model between them. See what happens. Take a look at a company such as this (the makers of TOOLBUS, not affiliated with them) and think how XMI should affect their business model, and yet it seems that it doesn't...
I would think that success is achievable, but may prove feasible for a (very) narrow scope - scoping is key here.
As for the second part, I don't think you're going to find it, particularly for .NET.
XMI is the keyword you need. But XMI specifies only the document format. It does specify the document structure or contents. The UML metamodel does this. A library which does both for you is org.eclipse.uml2 - it implements the UML 2.4 metamodel and allows to store and restore it in XMI. IBM RSA uses this library as well. As several other Java Tools do.
I'm not aware of a UML2 implementation in a .NET language.
I recently moved to a project where I noticed there have a specific requirement to store some data as XML.
The prior team used Castor generated classes to Marshall and Unmarshall the data.
I have a new requirement now that requires me to add some additional (yet optional) fields to this XML. However I realized the prior team supposedly never checked in the XSD at all and I have no way to reach out to them.
The XSD for sure was large and complex since it is responsible for generating around 50 classes. So writing the XSD again is going to be error prone and also a risk that I might end up creating XMLs now that are in compatible with the old XML.
The other alternative I thought of was using a tool like XML Spy and try to reverse engineer the XSD from the XML, however that sounds a bit difficult too since I will need to reverse engineer 20 odd XMLs to generate XSDs and then merge all these XSDs into one, since the XML had several optional sections. There is still an element of error possible in this approach.
The best option I can think of is reverse engineering the classes to an XSD - however Castor supposedly does not support this feature. So I don't have the means to convert these Castor generated classes back to an XSD! While the classes generated by Castor do have some Castor specific methods, in essence they are Pojos if the Castor specific methods are ignored!
Do we have any suggestions here for getting or generating the XSD from java classes? Do we have any other suggestions to solve the issues I discussed?
Thank you.
Just an update, while I have not achieved 100% of what I was looking for, I was able to successfully reverse engineer the XSD using JAXB's schemagen tool.
Just note that castor generates an XXXDescriptor with each class since that does NOT map to the actual XSD do not pass the XXXDescriptor classes as input to the schemagen tool.
The schemagen tool works with the getter methods and ignores methods like Castor's validate, marshall and unmarshall.
So things look quite hopeful at this point, compared to the situation I was in when I first posted the question.
Thanks.
Is anyone aware of a vendor neutral XSD to describe a relational database schema? Our system needs to grab information about the structure of a database:
Tables
Columns and types
Primary and Foreign Keys Constraints
Indexes
etc
in a vendor independent manner and store it in an XML file for later processing.
Before we do what we typically do and roll our own. I wanted to do some research and see if there was an existing XSD that people are standardizing on for what I assume is not an uncommon requirement for modeling tools and such. I did not find anything on Google that was not database vendor specific. If you know of an existing public standard I would very much appreciate a link.
Thanks in advance,
Terence
This isn't exactly what you're looking for, but the PostgresSQL Wiki has an interesting section on XML exports, that describes how they are supporting SQL and XML together. It displays a section on how a table would be exported as as XML and the XSD that would support it, which looks rather generic. It could serve as a model for you to create your own.
The Wiki talks about reference to a ISO/IEC 9075-14:2006 standard, that appears to be adopted by a few big vendors as a baseline. I quick browse on the ISO site says that :2006 was updated to 2008. I'm sure you can find a covered spec of this that you don't have to pay for to download.
The article also points to a SQL/XML standard definition that is a bit outdated, but could serve your needs if you're looking for some basics.
Interesting problem - I am not aware of any standard or tool to achieve this.
You would almost have to have some kind of a "neutralized" version with adapters for each individual database system you want to target - even just to map all the various data types (VARCHAR and NVARCHAR in SQL Server, VARCHAR2 in Oracle and so on).
You might just use the types defined in the SQL:2003 standard - but even then you'd probably still have to have some kind of a vendor-specific mapping / adaption of sorts. Not to mention some kind of support for vendor-specific implementation details (like IDENTITY columns in SQL Server vs. SEQUENCE in Oracle and others).
Very interesting question! I hope others will be able to shed more light on the issue and maybe recommend an existing tool.
If not, and you decide to roll your own - consider making it open-source on CodePlex or Google Code! I'm sure a lot of folks would be most interested!
MArc
The UML Information Management Metamodel (IMM) Specification from OMG may worth a try.