root/z3lab/zope/xmlschema/trunk/README.txt

XML Schema interface
=====================

This component provides an XML schema support on top of Zope3 interfaces.
It allows you to set XSD document on Python Interface definitions

Let's work with this simple XSD below :

"""
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="title" type="xsd:string"/>
  <xsd:element name="description" type="xsd:string"/>
</xsd:schema>
"""

It defines two string fields : title and description

First, let's register the XML Schema document through ZCML using the 
dedicated directive on the zope namespace : 

  >>> from zope.xmlschema.testing import registerDirective

  >>> registerDirective("""
  ...     <xmlschema
  ...         id="sample"
  ...         document="src/zope/xmlschema/tests/examples/simple.xsd"
  ...     />    
  ...     """)

Let's define an interface that will be bend to a xsd. For this, we
will use the zope.xmlschema.set declaration :

    >>> import zope.interface
    >>> import zope.xmlschema
    >>> class ITest(zope.interface.Interface):
    ...     zope.xmlschema.set('sample')

    >>> type(ITest)
    <class 'zope.interface.interface.InterfaceClass'>

    >>> ITest.__name__
    'ITest'
    >>> ITest.__doc__
    ''

Now introspect the fields defined within the xsd. We will see two new
fields : title and description.

    >>> names = list(ITest)
    >>> names.sort()
    >>> names
    ['description', 'title']

Now define a class implementing this interface.

    >>> class Test(object):
    ...     zope.interface.implements(ITest)
    ...     title = ''
    ...     description = ''
    >>>

ITest is implemented by Test

    >>> ITest.implementedBy(Test)
    True

Of course, Test doesn't provide "ITest", it implements it::

  >>> ITest.providedBy(Test)
  False

Let's create an instance of Test

    >>> test = Test()

ITest is provided by test

    >>> ITest.providedBy(test)
    True

Defines potential values for two fields

    >>> title = u"Title field"
    >>> description = u"Description field"

Now we, get the fields from the interface:

  >>> title_field = ITest.get('title')
  >>> description_field = ITest.get('description')

Next we have to bind these fields to the context, so that instance-specific
information can be used for validation:

    >>> title_bound = title_field.bind(test)
    >>> description_bound = description_field.bind(test)

Now try to validate them :

    >>> title_bound.validate(title)
    >>> description_bound.validate(description)