FdtStructure: Verify XML Access by XSD

In many applications XML files are used to provide user data. AS3 offers a simple loading and saving mechanism for XML and provides E4X as simple access method.

This picture shows a simple example with typical usage of E4X:
XSDE4XExample
The E4X code has several warnings and is not verified by FDT since the XML file is loaded during runtime. The XML file is expected to have a certain structure:
XSDXmlExample If the XML file is not matching the expected structure of the E4X code the application crashes or behaves incorrectly. In ActionScript 3 this situation could be avoided by using the Flex XML schema API to check XML files against XML schemas.

In the current example the XML file above is a valid instance of this XML schema:
XSDXmlSchema
But there is still a problem: The expected structure by E4X code may not be equal to the structure described by the XML schema. If you take another look at this example you may find the problem that the E4X code expects the attribute document inside the element but XSD schema and XML file have an attribute settings.

FDT’s new XSD support provide a solution to this problem. XSDs could be added to the classpath like SWCs to make XML schemas available for E4X access verification.
XSDProjectStructure
Here you can see the XML schema of XSD file DemoOptions.xsd interpreted by FDT. Since there is no explicit target namespace in the XML schema the project relative file path file://DemoOptions.xsd is used as structure package name within FDT to identify the XML schema of DemoOptions.xsd.

The XML schema types of classpath XSDs can be used inside the metadata tag FdtStructure:
XSDFdtStructure
The metadata tag FdtStructure could be used at variables, parameters and functions. The FdtStructure metadata tag default parameter attaches a structure to a variable type or a function return type. FdtStructure in line 17 attaches the XML Schema type WindowType in structure package file://DemoOptions.xsd to type XML of variable windowOpt in line 18.

In line 13 FdtStructure for method initDesktopOptions attaches the XML schema type OptionsType in structure package file://DemoOptions.xsd to type XML of method parameter options. Each parameter of a function can be listed inside FdtStructure to attach a structure to the parameter type. Only one FdtStructure metadata tag is necessary and allowed for a function to attach structures to parameter types and the return type.

In this example the structure information allows FDT to verify each E4X access used with parameter options and variable windowOpt. The error marker in line 16 indicates that element mainWindow below element options has no attribute document. Additionally no further warning is generated since FDT is able to decide that all other E4X parts are valid against the XML schema.

To correct this error FDT offers auto completion using the FdtStructure information:
XSDAutoCompletion
The auto completion shows attribute settings with type XMLList{String}. This means the AS3 type of settings is XMLList and the attached FdtStructure is a String. For element window of type XMLList the attached FdtStructure is XML schema type WindowType. Attached FdtStructures are always presented in curly braces after AS3 types. FDT gains this information by interpreting XML schema types inside classpath XSDs. Here it is the file DemoOptions.xsd.

An auto completion to select one XML schema type is available, too:
XSDStructureAutocompletion
Each XSD schema type is prefixed by the structure package name of the XML schema.

For more flexibility the structure package name for each XML schema is the

  • XML schema id (if it is defined)
  • target namespace (if it is defined and no id is defined)
  • project relative path to the XSD file (if no id and no target namespace are defined)

In this example the XML schema id is defined and so it is used as structure package name:
XSDXmlSchemaId

Here is an XML schema with a namespace which is also the structure package name:
XSDXmlSchemaTargetNamespace
In case the XML schema has a target namespace it is useful to declare an AS3 namespace with the same destination so that FDT could offer auto completion for members declared with this namespace. An example with namespace you can download here: DesktopDemo_XSD_Namespace.zip



FdtStructure: Verify Dynamic Object Members by Json Schema
A Json schema is supported in a similar way as an XML schema for FdtStructure.
Here is an example of a Json schema for a DektopDemo application:
JsonSchema
This Json schema can be added to the classpath, too:
JsonProjectStructure
The Json schema types are named by their Json pointer.

The structure package name for each Json schema is the

  • schema title (if it is defined)
  • schema id (if it is defined and no title is defined)
  • project relative path to the Json file (if no id and no title are defined)

Since no title and no id is specified in the example Json schema the structure package name is the project relative path file://DemoOptions.json to the Json file.

This Json file is valid instance of the example Json schema above:
JsonExample

FdtStructure can be used with Json schemas in a similar way as XML schemas:
JSONAccessExample
The error marker describes the problem that mainWindow does not have a property document. The type of mainWindow is Object with Json schema type #/definitions/mainWindowType as the attached FdtStructure which does not contain any property document.

This Json example you can get here: DektopDemo_Json.zip



FdtStructure: Verify Dynamic Object Members by AS3 Type

Any AS3 types can be used as FdtStructure, too:
AS3TypeAccessExample
In this example variable res is attached with a standard AS3 class as FdtStructure. The variable res is still of type URLVariables (a dynamic class). All the dynamic members (sessionId, answerId, topicId, message, and userName) will be verified by using the attached AS3 class URLVariablesRequestDescriptor. The error marker at line 10 describes that topicId is assumed to be a String and could not be initialized by a number.
AS3TypeExample

Type * as FdtStructure can be used to switch off any member or attribute validation:
StarFdtStructure


FdtStructure: Feature Overview

  • FdtStructure attaches any AS3 type, Json schema type, or XML schema type to a variable, function, or parameter having a dynamic class as type.
  • Each E4X term or dynamic member access is validated against an attached structure.
  • Validation is done by FDT: ActionScript 3 compiler ignores FdtStructure metadata tags (see compiler option –keep-as3-metadata here)
  • Auto completion for attached structures and their members, attributes, or elements
  • Attach XML schema types to any XML or XMLList
  • Attach JSON schema types to any Object or Array
  • Attach AS3 types (interfaces or classes) to any dynamic class
  • Attach * to any dynamic class to switch off validation

Known limits:

  • XSD:
    • Include directives inside XSDs are ignored.
  • JSON
    • Only Draft v4 is support (http://json-schema.org/draft-04/schema#)
    • Only local “$ref“ of this form “#/../..”, no external schema is loaded.
    • Array tuple schema is not supported
    • “not” schema is not supported
    • Missing additionalProperties is interpreted as “additionalProperties”:false
    • Only basic error reports on problems in Json schema files

Please note: FdtStructure is not available in FDT Free.