What Makes a Schema, Rules and Guidelines
-----------------------------------------
Tim Hockin <thockin@cobalt.com>
July, 2000

1. Overview

	The object model of CCE is defined by schemas, which are provided by
	vendors to define various entities to CCE.  A schema can contain class,
	property, or typedef definitions.  The syntax of a schema description
	file is a subset of XML, and is very flexible.

	Throughout schema description files, whitespace (spaces, tabs, and 
	newlines) is ignored.  The only exceptions to this rule are within 
	quoted strings, and within the content field of an element.  In these
	cases, whitespace is preserved.  To denote the optional presence of 
	whitespace, the symbol "SP" will represent a single whitespace 
	character.  As in regular expressions the '*' modifier means 
	"zero-or-more", and the '+' identifier means "one-or-more".

2. Syntax

	A schema file consists of 1 or more elements.  An element is always
	started with the form:
		"<" SP* element_name SP+ (attr_name SP* "=" SP* attr_val)* ">"

	If the element has a content field (for example: properties are
	content of a class) the element is ended with:
		"</" SP* element_name SP* ">"

	If there is no content field, the element may use the above form to
	end an element, or may use the optional start form with no second end
	tag:
		"<" SP* element_name SP+ (attr_name SP* "=" SP* attr_val)* "/>"

	The elements definable in a schema are:
		SCHEMA
		CLASS
		PROPERTY
		TYPEDEF

	Each follows similar syntax, but has different attributes.  Each item
	is described below.  All tokens are whitespace delimited, and
	newlines are only significant between opening and closing tags (what
	is called the content) and within quoted strings.

	Attribute names are always alphanumeric, and attribute values are
	always surrounded by single quotes (') or double quotes (").
	Attribute and tag names are case-insensitive.  All tags have at least
	one required attribute, and 0 or more optional attributes.

	Every schema description file should contain one or more SCHEMA 
	elements, which is the single toplevel element.  This element provides 
	a logical grouping of elements, and is the parent/wrapper element 
	for other elements.  If a SCHEMA is not specified, a default SCHEMA 
	will be assumed for all top-level items in a schema description file.  
	Multiple SCHEMA elements may be defined within a single schema 
	description file, though it is generally not recomended.

2.1 Syntax: comments

	A comment begins with the string "<!" and ends with "-->".  All text
	between these elements is ignored.

2.2 Syntax: SCHEMA

	A SCHEMA is provided to identify a schema definition to the system.  
	This element provides such information as schema name, vendor, 
	version and any other information a vendor may find useful to store 
	with their schema definition.  All child elements of a schema are
	grouped together by the schema definition.  
	
	If no SCHEMA element is defined, or other top-level elements are
	defined, the non-schema-wrapped elements of the description file are 
	assumed to be part of a schema with NAME set to the current filename 
	(minus the .schema extension), and VENDOR and VERSION set to the empty 
	string ("").

	Tag name: "SCHEMA"
	Required attributes: "NAME", "VENDOR", "VERSION"
	Optional attributes: any
	Valid children: 0 or more "CLASS" or "TYPEDEF"
	Valid Parents: none

	NAME, VENDOR, and VERSION are freeform identifiers, and may be any
	string.
	
2.3 Syntax: CLASS

	A CLASS is the formal definition of an object's structure.  An object
	has all the properties of it's CLASS, and only the properties of it's
	CLASS.

	Tag name: "CLASS"
	Required attributes: "NAME", "VERSION"
	Optional attributes: "NAMESPACE"
	Valid children: 0 or more "PROPERTY"
	Valid Parents: "SCHEMA"

	NAME must be a C-style symbol.  That is to say: it must start with a
	letter or underscore (_) , followed by any number of letters, digits,
	or underscores.  NAME should, per convention, start with a capital
	letter. (examples: "Foo", "Foo_123")

	VERSION may be any string, but is, by convention, an integer or
	floating point number (examples: "1", "3.1415").

	NAMESPACE follows the same rules as NAME, with the exception that
	NAMESPACE may be a blank string (""), or be unspecified.

2.4 Syntax: PROPERTY

	A PROPERTY is a sub-element of a CLASS.  A single PROPERT defines a
	single datum.  CLASSES are essentially useless without properties to
	hold data.

	Tag name: "PROPERTY"
	Required attributes: "NAME", "TYPE"
	Optional attributes: "DEFAULT", "OPTIONAL", "ARRAY", "READACL", 
		"WRITEACL"
	Valid children: none
	Valid Parents: "CLASS"

	NAME must be a C-style symbol.  See section 2.1 "CLASS" syntax for
	the NAME attribute.

	TYPE must be a valid TYPEDEF name.  Type bindings are resolved after
	all-schemas are loaded, so there are no problems using a typedef
	before it is defined.  A PROPERTY with a TYPE that does not exist 
	will fail all data validation.

	DEFAULT may be any value that is valid for the specified TYPE.  If
	DEFAULT is unspecified, the default value is an empty string (""), 
	which may or may-not be valid for the PROPERTY.

	OPTIONAL may be any string or unspecified.  If unspecified or assigned
	the value "" or "0" (zero), the optional flag is set to false,
	otherwise, the optional flag is set to true.  When set to true, data
	for this property can be either the empty string ("") or data which
	is valid for the TYPEDEF specified.

	ARRAY may be any string or unspecified.  If unspecified or assigned
	the value "" or "0" (zero), the array flag is set to false,
	otherwise, the array flag is set to true.  When set to true, data for
	this property is assumed to be an unbounded array of data, of the type
	specified.

	READACL and WRITEACL are defined in Security.txt.

2.5 Syntax: TYPEDEF

	A TYPEDEF is a mechanism to better use the basic data typing provided 
	by CCE.  A TYPEDEF is a symbolic name given to a definition of a
	type, and is used by a PROPERTY to validate it's data.

	Tag name: "TYPEDEF"
	Required attributes: "NAME", "TYPE", "DATA"
	Optional attributes: "ERRMSG"
	Valid children: none
	Valid Parents: "SCHEMA"

	NAME must be a C-style symbol.  See section 2.1 "CLASS" syntax for
	the NAME attribute.

	TYPE must be one of "re" or "extern".

	DATA must be TYPE appropriate data validator.  For "re" it should be
	a valid regular expression, for "extern" it should be the path to an
	external program to validate data.

	ERRMSG may be any string, or unspecified.  This value will be
	returned by CCE when invalid data is attempted to be written to an
	instance of this TYPEDEF.

3.0 Sample

    <SCHEMA 
     NAME="Sample Schema"  
     VENDOR="Cobalt Networks"
     VERSION="3.1415">
    
    	<!-- Add a User class, one property, one namespace, one type -->
    	<CLASS name='Sample' version='1.0' >
    		<PROPERTY name='name' type='alphanum' default='new' />
    	</CLASS>

    	<CLASS name='Sample' namespace="Demo" version='ver1.1'>
    		<PROPERTY name="name" type="alphanum" default='New' />
    	</CLASS>

    	<TYPEDEF name="alphanum" type="re" data="[A-Za-z0-9]*" />
	
    </SCHEMA>

