agroXML Schema code should come up to certain standards. A common style facilitates understanding of the schema documents. So this section describes, how they should look like. agroXML schema documents must be indented using single tab characters. Most XML editors support this kind of indentation style. To clean up an XML schema not conforming to this style, one can use for example the xmllint tool contained in the libxml2 package. By default, xmllint uses two spaces as indentation characters. Changing to tabs can be effected by setting the XMLLINT_INDENT environment variable to the appropriate value. Use the linefeed character (ASCII 0x0A) as lineending character. The rationale behind this can be found in http://www.w3.org/TR/2006/REC-xml-20060816/#sec-line-ends. Parsers have to normalize to this character anyways, so why not use it in the first place. Make sure, that your editor supports this. Every good programmer's editor uses either LF by default or has an option to set it accordingly. Don't use unnecessary spaces in the documentation. White space in documentation elements is significant. So including linebreaks or tabs at the beginning of lines can lead to ugly rendering in different tools for generation of human-readable documentation. Documentation should contain only usage information and text clarifying the meaning of elements or types to implementors. Annotations for the developers of agroXML schemas, like for example FIXME and TODO remarks signifying a requirement to rework the schema should go into comments. Comments are here to describe the code for schema developers. Do not comment on the obvious like e. g. repeating the element name to follow in a comment above, but document, where there are drawbacks or issues to resolve using the keywords TODO or FIXME. Element and datatype names must be UpperCamelCase. Attribute and attributeGroup names must be lowerCamelCase. Attach the prefix "Abstract" to abstract datatype names. Abstract elements are signified by an underscore ('_'). As per the SGML ISO standard, all names should be descriptive. In all cases, use the english spelling. If in doubt, consult the Oxford English Dictionary. Imports should come first in the XML Schema files to have them as close as possible to the definition of their namespace prefix given in the attributes to the <xsd:schema> element. After the imports follow the includes. A type definitions and the corresponding element are bundled up in blocks, where the definition appears first. These 'blocks' are arrange alphabetically and separeted by a comment line. In some cases it is usefull to seperate XML schema constructs for different reasons.For example It is assumed, that they are candidates for further editing or the constructs are elements of an homogen data set. Such constructs could be wrapped in an own block respectively subblock. In this section, we will look in detail into the technical process of how releases are prepared and the steps to be taken before and afterwards the publishing. 2 Weeks before freezing the code, the current version is investigated by the agroXML-team for ambiguity, errors and others deficiencies. After that the code is formatted after the formating rules defined above 3 Month befor the release, the code is freezed in a branche. From then on no more feature are added to the branch. The feezed code is examined and tested by all partners und interested users. Errors will bee handled in bug fixes. At the end of this periode, the code is ready for release. The code in a once tagged release MUST NEVER BE CHANGED, NO MATTER HOW SEVERE THE ERRORS IN THERE ARE. In an open project like agroXML, chances are that the code is already used by others without our knowledge. People already using might be annoyed (and rightfully so) if the code changes without a change in release number. Elimination of severe errors is done in the branch before tagging. As such, the code put onto the agroXML homepage for download MUST ALWAYS be put together by generating an export from the once tagged release in the source code management system. For reference on how to do this, see the respective documentation of the system currently in use (at the moment subversion). If it ever happens that there is an absolute show stopper in the schema, a new release with a new minor release number (at position 3) has to be generated. However, as by definition a schema is not erroneous if it follows the XML and XML Schema standards given by the W3C, and the tools used by the development team at KTBL check for this, the probability is relatively low. If people bring up requirements in content (i. e. new elements or attributes) after the fact, it is to be discussed, if there will be new minor release or if the requested changes go into the next major one. It is impossible to remove elements, datatypes or attributes from one minor release to another. A simple and very good rule concerning that point can be found in the INSPIRE specifications: Use enumerations whenever the change frequency of the content of the enumeration is lower than the common release cycle frequency of the schema. If the content changes more frequently, it should go into a codelist. In the case of agroXML, with an approximately yearly release cycle, this means, that if it is to be expected that the enumeration changes at least once per year, the content should rather go into a codelist. Building object class structures with generalizations (inheritance) can be done in XML Schema using abstract datatypes, elements and substitutionGroups. However you should avoid a depth of more than 2 levels in the inheritance tree, as in the case of XML schema, complex inheritance trees quickly loose clarity. If the one big advantage of object oriented design to facilitate development by offering clear and simple structuring of the problem at hand is lost, it should not be used at all. The most important pattern which calls for usage of inheritance is: Elements belonging to a common concept sharing more than one element. If elements share more than one common attribute, it is probably simpler and better, to put these attributes into an attributeGroup and reference the group by name rather than relying on inheritance. Think! When programming, the decision, if a variable will be global or local to a function is by no means always simple. It requires foresighted planning and thinking about reuse of the data in other functions spread across the program. Same goes for the decision, if an element definition should be global and if datatypes should be named or anonymous in XML Schema design. In contrast to DTDs, XML Schema differentiates between datatypes and elements. So think before you type! Points to consider: If a simpleType is so general, that it might be used for more than one element, give it a descriptive name and put it into CoreComponentTypes.xsd. Examples for generally usable types are for example datatypes for physical quantities. If a complexType is likely to be used in more than one element (probably seldom the case) or if a complexType might be extended in the future (probably often the case), give it a proper name and put it into the module, where it fits best considering its content. If an element using a simple content model is likely to be reused in more than one place, give it a descriptive name and put it into CommonBasicComponents.xsd. Examples are elements like name, description or length, which are used all over the place in agroXML. These elements might use their own anonymous type definitions or use one of the definitions given in CoreComponentTypes.xsd. If an element using a complex content model will be reused, give it a descriptive name and put it into the respective module. In most cases, however, it is probably better to only keep the data at one place in the content model (and thus the instance) and reference from other places if needed.