Archive

Archive for the ‘Standards’ Category

Sitecore and Lionbridge Join to Address Globalization

February 15, 2011 Leave a comment

Globalization is expected to be one the biggest influence on technology direction for next few years. Sitecore and Lionbridge must have gotten the message. The firms have annouced a partnership to integrate the Sitecore Content Management System (CMS) technology with Lionbridge’s Freeway translation technology platform. Sitecore’s software automates the manual process of content translation with Lionbridge’s online translation service delivery platform. Lionbridge’s language solutions will be available from within Sitecore’s CMS and fully integrated with the Content Editor to form a seamless translation workflow that dramatically streamlines the entire global content lifecycle. Read more about the new integrated solution in the press release.

Advertisements

Critical Questions to Ask Before Developing a Social Media Policy

February 15, 2011 Leave a comment

In the last few years, social media expanded beyond the boundaries of LOLs and texting teens into the hallowed walls of corporate America. Organizations are leveraging social media externally as a marketing tool to solidify their brand and internally for collaboration. The possibilities are tempting. However, organizations taking advantage of these possibilities should incorporate guidelines for the management and use of social media into their governance, HR and other corporate policies as quickly as possible to avoid introducing organizational risk.

Analysis firm extroidinaire, Gartner, recently published seven critical questions organizations should ask before designing a social media policy. Check it out and let me know your thoughts.

Organizations Opening the Door to Open Source

February 11, 2011 Leave a comment
open source

Increasingly, open source is becoming an important part of the corporate software portfolio.

A recent Gartner study is confirming what many of us have long known – open source software (OSS) rocks. Enticed by promises of flexibility, innovation, lower cost and faster acquisition times, companies are increasingly adopting open source solutions to support their business processes. OSS is becoming pervasive. The benefits are compelling, but nothing in life is free, and despite popular perception, that includes open source software.

Read more of my article on TechAxcess

3 Ideas to Make Architecture Executable in Visual Studio 2010

May 19, 2010 Leave a comment

One of the main complaints people have about architects is that we set a bunch of standards and produce a bunch of paper but little else even when they appreciate the visionary aspect we bring to the table.  While concepts, standards, and white papers  can provide valuable guidance, ultimately the value proposition is only as good as organizational adoption.

One of the question I always ask myself is how can I make this concept tangible to my audience. Further, how can I make what I’m promoting normal part of the workflow without  introducing additional ceremony.

I think Visual Studio 2010 introduces new opportunities for organizations using the MS platforms to make technical architecture executable for their technical teams. Here are few ideas you might want to incorporate:

  1. Make coding standards executable: StyleCop and Code Analysis (or  FxCop) are free code analyzers. StyleCop works on non-compiled code while Code Analysis/FxCop work on IL. While these are not new tools for VS2010,they were improved, and  you should consider incorporating them into your build processes. Instead of just writing coding standards  (which usually also include  simple design rules in addition to formatting guidelines)  configure StyleCop and CodeAnalysis to evaluate the rules at build time or compile time. This can be done on developer machines, even if you haven’t implemented a CI process. Modify your coding standards document indicate which rules are executable.  Custom rules can  be implemented to reflect the needs of your organization. (Note: integrating the execution of StyleCop into TFS 2010 will require you to create a custom workflow activity.) Choosing this strategy instead of a document has several benefits: allows standards to be quickly and consistently evaluated so that code reviews can focus on more valuable design related activities, provides metrics regarding standards compliance — maybe your standards are unrealistic and need to be evaluated or developers require more education, and allows standards to be available from within in the normal development workflow instead of spending time switching between coding and reading a document to ascertain compliance (a not very Lean practice).  More information on the tools are available at:
  2. Make high level architectural patterns available in the IDE. Layers (http://www.openloop.com/softwareEngineering/patterns/architecturePattern/arch_Layers.htm)  are probably one the most commonly used architectural pattern. 
    Layer Diagram

    Pretty Boxes

     

    There are few systems that don’t refer to themselves as n-tier or MVC these days. Layering is even used to describe infrastructure in commonly used tools such as the OSI model.  Solutions architects typically articulate their grands visions for how their systems should be implemented using layers and how those layers should interact in a few ways: reference implementations, pretty boxes (my fave – you can’t tell me you’ve never drawn a bunch of nebulous boxes on the white board:)), or UML package/component diagrams. Why not use the same pretty picture for your software architecture document to actually validate the code that is being delivered. I will wait a moment for your wow :).  A new option with Visual Studio 2010 are layer diagrams.Layer digrams allow you to define the layers of your system within Visual Studio, define the relationship and constraints among layers, associate the layers namespaces, and validate that the implemented code conforms with layer diagram. You can easily imagine a scenario where you can quickly perform an audit to determine how many new web  applications developed for  the quarter conform with the MVC architecture. You could also use the diagrams as part of SLA agreements with your solution providers to ensure they are conform with approved enterprise architectural patterns. More information on the use and capabilities of layer diagrams is available at:

  3. Generate code. There have long been numerous model driven architecture tools available for .Net.  Visual Studio 2010 is throwing it’s hat in the arena to arguably make it simpler. VS2010 allows you to create UML diagram and apply stereotypes to the diagrams that represent your intended design. You can then use T4 to generate code from the models. I estimate that 40%-60% of code could be generated in this way for most common applications. (Note: True DSL support for the MS platform is a little spotty but most organizations have reached a point which true DSL use is pervasive.) It should be noted that code generation as a strategy is most effective if you have well-defined standards for development including cross cutting concerns. For example if my ORM standard is nHibernate I can easily generate a domain model that leverages nHibernate for persistence. The benefit of code generation are numerous: time and delivery cost, delivery consistency, increased focused on value add portions of the application that actually drive competitive advantage instead of expending resources on infrastructure code, increased focused on business needs and domain modeling and code as a mechanism to support it instead of the reverse, and rapid spiking/prototyping. Additional information is available regarding UML and code generation at:

I am not suggesting that these things were not achievable before using a combination of open source tools and commercial products for the MS platform. However, Visual Studio 2010 provides a fairly significant set of tools that may not be being completely leveraged it the tool is primarily used for “just coding”. Obviously you don’t have to implement all of these ideas, but some may provide benefits in your organization.

XML Schema Standards Recommendation

February 11, 2010 Leave a comment

Document Purpose

The goal of this document is to recommend a set of  standards and guidelines that should be applied when designing XML schemas for use in interoperability scenarios. This document is intended for a technical audience that is responsible for creating and/or modifying XML schemas.  The reader should be familiar with XML, general use of development tools, and preferably object oriented design.

Structural Guidelines

General Guidance

  • Avoid deep element nesting. The more complex XML schemas are the more processing will be required to parse and validate the document. This guideline is especially important for schemas that are likely to be leveraged by webservices. The consumer will have to marshal their programming objects to XML elements before issuing a request, and the service provider will have to map the XML elements to programming objects in processing the request. This may result in significant performance overhead for large documents.
  • Do not use unnamed complex types. Their use can result in difficult to use programming language constructs when the schema is mapped/bound to programming objects.
  • Use explicit namespace prefixes. Some older parsers treat elements in an unrefined default namespace as having no namespace.
  • Don’t use <any> element to pass information. Schemas should be explicit. The content expected in this element will not be documented in your XML schema. Therefore, the use of <any> elements almost always have the impact of introducing ambiguity by reducing the ability of the schema to be self-describing. Additionally, use of <any> elements introduce the possibility of inconsistent structural validation for the schema.
  • All elements, types, and attributes defined in XML schemas should be annotated.

NameSpace Definition Guidance

Namespaces in XML schemas are used to provide a scope or logical space for the definitions described by the schema. Namespaces in XML serve a similar role to package names in Java and namespaces in .Net languages. When using multiple schemas in an XML document, namespaces help ensure the uniqueness of elements and attributes.

 A complete specification of the rules governing namespaces can be found at: http://www.w3.org/TR/REC-xml-names/ .

According the specification, namespaces can be any valid URI excluding an empty string. While this provides a great deal of autonomy it does create a strong likelihood of a namespace conflict if no additional guidelines are applied.

 I encourage you to  leverage schema namespaces to assist in classifying the purpose of a XML schema document. The recommend namespaces format is:

http://schemas.{companyname}.com/{domain}/{purpose}/{version}

Figure 1 – Schema Namespace Format

where the bolded items are replaced with values appropriate for your application context. The following is an example of well defined schema namespace:

 http://schemas.ion.com/consulting/survey/1-0

Figure 2 – Example Namespace

Namespace Assignment Guidance

  • Always assign a target namespace to the schema.
  • Set the elementFormDefault attribute to “qualified”. A qualified settings forces elements in any instance documents that use the schema to be fully qualified with the namespace.
  • Set attributeFormDefault to “unqualified”.

The following is an example of the settings in a schema using the namespace from figure 2

<xs:schema xmlns:vha=http://schemas.ion.com/consulting/survey/1-0

xmlns:xs=http://www.w3.org/2001/XMLSchema

targetNamespace=http://schemas.vha.com/clinical/survey/1-0

elementFormDefault=”qualified”

attributeFormDefault=”unqualified”>

Figure 3 –Namespace Related Settings

Programming Language Constraints

Schema designers should be aware of the constraints in commonly used development tools that are likely to be used to consume schemas. When possible, these constructs, excluding annotations should be avoided.

Java .Net
  • In JAX-RPC 1.1 there are no constructs to represent: 
    • Default values
    • Optional attributes 
    • Annotations
    •  In JAX-RPC 1.1 WSDL to Java mapping tools are allowed to reject documents that use
       <xs:redefine>
       <xs:notation>
       substitution groups
    • In JAX-RPC 1.1 support for the following constructs are optional. Thus, behavior will vary by vendor platform:
      •  <xs:entity>
      • <xs:notation>
      • <xs:idref>
      • <xs:union>
      • <xs:anyType>
      • <xs:choice>
      • <xs:group>
      • Nested arrays and arrays of any subtype of the array type
      • Deriving complex types by restriction
      • Abstract types
    • JAX-WS schema support
    • Xsd.exe and XmlSerializer (System.Xml.Serialization) has the following restrictions:
      • <annotation> : Not supported
      • <any> : Partially supported
      • <anyAttribute>  : Partially supported
      • <appinfo>  : Not supported
      • <attributeGroup>         : Partially supported
      • <documentation>         : Not supported
      • <enumeration>    : Partially supported
      • <field>  : Not supported
      • <fractionDigits>  : Not supported
      • <group> : Partially supported
      • <import> : Partially supported
      • <include>  : Partially supported
      • <key>  : Not supported
      • <keyref>  : Not supported
      • <length>  : Not supported
      • <list> : Partially supported
      • <maxExclusive>  : Not supported
      • <maxInclusive>  : Not supported
      • <maxLength>  : Not supported
      • <minExclusive>  : Not supported
      • <minInclusive>     : Not supported
      • <minLength>  : Not supported
      • <notation>  : Not supported
      • <pattern>  : Not supported
      • <redefine>  : Not supported
      • <restriction>  : Partially supported
      • <selector>  : Not supported
      • <simpleContent>  :Partially supported
      • <totalDigits>  : Not supported
      • <union>  : Not supported
      • <unique>  : Not supported
      • <whitespace>  : Not supported
 

    • Xsd.exe and XmlSerializer (System.Xml.Serialization) has the following restrictions:
      • <annotation> : Not supported
      • <any> : Partially supported
      • <anyAttribute>  : Partially supported
      • <appinfo>  : Not supported
      • <attributeGroup>         : Partially supported
      • <documentation>         : Not supported
      • <enumeration>    : Partially supported
      • <field>  : Not supported
      • <fractionDigits>  : Not supported
      • <group> : Partially supported
      • <import> : Partially supported
      • <include>  : Partially supported
      • <key>  : Not supported
      • <keyref>  : Not supported
      • <length>  : Not supported
      • <list> : Partially supported
      • <maxExclusive>  : Not supported
      • <maxInclusive>  : Not supported
      • <maxLength>  : Not supported
      • <minExclusive>  : Not supported
      • <minInclusive>     : Not supported
      • <minLength>  : Not supported
      • <notation>  : Not supported
      • <pattern>  : Not supported
      • <redefine>  : Not supported
      • <restriction>  : Partially supported
      • <selector>  : Not supported
      • <simpleContent>  :Partially supported
      • <totalDigits>  : Not supported
      • <union>  : Not supported
      • <unique>  : Not supported
      • <whitespace>  : Not supported
 

Table 1 – Language Constraints

Datatype Utilization Guidance

  • Prefer the token data type (xs:token) to the string data type (xs:string) when extra spaces in a value are not significant. Tokens have the same lexical space as the string data type, but provide the extra benefit of normalizing whitespace. The lexical space for a data type is the set of valid literals it supports. Each value in the data type’s value space maps to one or more valid literals in its lexical space. For example, “100.0” and “1.0E2″ are two different representations for the same value. In other words, ” this is a string ” represented token data type will be normalized to “this is a string” whereas a string data type allows the value to remain as ” this is a string “. This may seem trivial, but such distinctions are the cause of a surprising number of value comparison errors.
  • Avoid the use of unsignednumerical types (xs:unsignedInteger). Java does not support unsigned types and the mapping from the schema type to a Java type may vary by implementation. This will result unpredictable system behavior.
  • Avoid the use of data type restrictions facets (e.g., restricting a number between –180 and 180) Most platforms don’t support restrictive sub-classing when representing the XML structure as a language structure.
  • Avoid the use of decimal and floating point numbers in XML schemas. Each platform may support precision differently. This is especially important in cross platform systems involving financial data.
  • Avoid the use of arrays (soapenc:arrayType) since there are differences across platforms regarding how empty arrays are serialized.
  • Avoid using “nillable” primitives (e.g. xs:int) and date types in XML schemas. This practice can cause issues across platforms since many language do not support assigning a null object to a primitive.
  • Avoid serialization platform-specific XML types, such as dataset from .NET or collection classes from Java. The use of such structure will result in a lack in interoperability across platforms. Complex types explicitly defined in the XML schema should be used to represent these structures.

Schema Versioning

It is recommended that schemas support tracking changes using version numbers. Version numbers are controlled at two levels:

  • Major—widespread changes, most likely not backward compatible
  • Minor—small changes and refactoring which are backward compatible. Minor changes may introduce new features without removing or changing the existing structures

 The major number must be included inside the target XML namespace of the XML schema. Figure 2 above includes an example of this. The minor version number should be specified in the version attribute of the schema as illustrated in figure 4 below.

 <xs:schema xmlns:vha=http://schemas.ion.com/consulting/survey/1-0

xmlns:xs=http://www.w3.org/2001/XMLSchema

targetNamespace=http://schemas.ion.com/consulting/survey/1-0

elementFormDefault=”qualified”

attributeFormDefault=”unqualified” version=”2”>

Figure 4 –Schema Versioning

Design Guidelines

General Guidance

Attributes Versus Elements

There are many cases in which data can be represented as an attribute or an element.

For example:

<item price='42.25'/>

Figure 5 –Element Form

or

<item><price>42.25</price></item>

Figure 6 –Attribute Form

There are no rule as to when attributes should be used versus elements.  However, attributes do have the constraints of only being singular. The following guidance should be used in your decision making:

  • Attributes should be used for metadata about the parent element (item is the parent element above).
  • Use elements for data that has a meaning separate from the enclosing element.
  • If you don’t know which to use, then use the element form. It is more extensible.

Global Elements

Only declare items as global elements if they represent a valid instance document. For example, if a schema includes a survey element and a survey person if you do not intend to process a survey person as a standalone instance document it should be declared as a child of the survey.

 Complex types can be declared globally without this side effect.

 Domain Driven Design

XML schemas should be designed in a similar manner to an object or component oriented system. XML elements should reflect the language and structure of the business domain as closely as possible as opposed to any specific technical implementation. When possible, technical concerns should be factored out of schemas and transmitted as meta-data (e.g. in a SOAP header).

 For example an XML schema to describe a book in the library might be designed as:

<?xml version=”1.0″ encoding=”UTF-8″?>

<xs:schema xmlns:vha=”http://schemas.ion.com/library/book/1-0&#8243; xmlns:xs=”http://www.w3.org/2001/XMLSchema&#8221; targetNamespace=”http://schemas.ion.com/library/book/1-0&#8243; elementFormDefault=”qualified” attributeFormDefault=”unqualified” version=”1″>

       <xs:element name=”Book”>

              <xs:annotation>

                     <xs:documentation>Comment describing your root element</xs:documentation>

              </xs:annotation>

              <xs:complexType>

                     <xs:sequence>

                           <xs:element name=”Author” type=”xs:token” maxOccurs=”unbounded”/>

                           <xs:element name=”Pages” type=”xs:int”/>

                           <xs:element name=”Subject” type=”xs:token” maxOccurs=”unbounded”/>

                     </xs:sequence>

              </xs:complexType>

       </xs:element>

</xs:schema>

Figure 7 –Simple Book Schema

There are innumerable texts that describe how to identify objects and create domain driven designs; therefore, that content will not be reiterated within this document.

Design Patterns

Similar to other languages, a set of design patterns have emerged for creating XML documents. An XML pattern catalog is available at http://www.xmlpatterns.com/patterns.shtml. These patterns represent solutions to common concerns when developing XML schemas. These patterns should be viewed as information point for designing schemas rather than a rule set that must be followed.

Schema  Reuse

Before ANY new schema is developed, it is recommend a central schema repository should be created when possible reviewed to determine if an existing schema can be leveraged. All new schemas should be stored in this repository. Initally organizations can leverage existing document or source management repositories to serve this need. As XML usage becomes mores sophisticated a dedicated XML repository can be considered if it provides a tangible benefit over the less sophisticated solution (e.g. ESB, XML Firewall, etc.)

Data defined in schemas should be non-redundant. XML schemas should import and include other XML schemas rather than duplicating or re-defining types and elements locally.

Applicable Standards

  • XML  1.1
  • XML Schema 1.0

 

Please note that W3C XML schemas (.xsd) is the recommended format for  the development of schemas. Other formats such as DTD and Relax NG are not preferred due to less wide spread adoption and incompatability with modern Web Service standards.

Tools

Tool Description
Xsd2Code An open source add-in for Visual Studio available at http://www.codeplex.com/Xsd2Code that generates C# or VB classes from an XML schema
Xml Spy .
Xsd.exe A command line tool included with Visual Studio that can be used to generate a XSD from classes or classes from an XSD
Schema Agent  

Table 2 – XML Tools

Appendix – Datatype Mappings

The following datatype mapping is provided to minimize compatibility issues across languages:

XML Schema Types .Net Types Java Types
anyURI System.Uri java.net.URI
base64Binary System.Byte[] byte[]
boolean System.Boolean boolean
byte System.SByte byte
date System.DateTime java.util.Calendar
decimal System.Decimal java.math.BigDecimal
double System.Double double
float System.Single float
hexBinary System.Byte[] byte[]
ID System.String java.lang.String
IDREF System.String java.lang.String
IDREFS System.String[] java.lang.String[]
int System.Int32 int
integer System.Decimal java.math.BigInteger
language System.String java.lang.String
long System.Int64 long
month System.DateTime long
Name System.String java.lang.String
NCName System.String java.lang.String
negativeInteger System.Decimal java.math.BigInteger
NMTOKEN System.String java.lang.String
NMTOKENS System.String[] java.lang.String[]
nonNegativeInteger System.Decimal java.math.BigInteger
nonPositiveInteger System.Decimal java.math.BigInteger
normalizedString System.String java.lang.String
NOTATION System.String java.lang.String
positiveInteger System.Decimal java.math.BigInteger
QName System.Xml.XmlQualifiedName javax.xml.namespace.QName
short System.Int16 short
string System.String java.lang.String
time System.DateTime java.util.Calendar
timePeriod System.DateTime java.util.Calendar
timePeriod System.DateTime java.util.Calendar
token System.String java.lang.String
unsignedByte System.Byte short
unsignedInt System.UInt32 long
unsignedLong System.UInt64 java.math.BigInteger
unsignedShort System.UInt16 int

Table 3 – Datatype Mappings