What Makes a Schema, Rules and Guidelines ----------------------------------------- Tim Hockin 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: "" 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 "". 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