JSON schema vs OpenAjax

From MemberWiki

Jump to: navigation, search

Properties: OpenAjax versus JSON Schema

The following table compares the list of attributes (and child elements) on the OpenAjax <property> element versus the various parameters within JSON schema that define a single object property. Colorization conventions:

  • Green-colored rows indicate that OpenAjax Metadata and JSON Schema have compatible names and definitions.
  • Yellow-colored rows indicate that there are differences that require discussion.


JSON SchemaOpenAjaxJSON Schema DescriptionNotesProposed decision or final decision
(see Notes)name I believe in JSON Schema the property name is defined within the parent data structure.2008-01-24 TENTATIVE APPROVAL: include 'type' in OpenAjax Metadata
typetypeThis is a type definition value. A type definition can be a string indicating a primitive, it can be another schema definition object, or it can be an array which is a union of type definitions. If the property is not defined or is not in this list, than any type of value is acceptable. Other type values may be used for custom purposes, but minimal validators of the specification implementation can allow any instance value on unknown type values. 2008-01-24 TENTATIVE APPROVAL: include 'type' in OpenAjax Metadata
(absent)valueType In OpenAjax Metadata, for selected core datatypes, the 'valueType' attribute on the <property> element provides supplemental datatype information that allows for deeper interoperability between software products and for tailored user interfaces within editing tools. Sometimes tools can use the 'valueType' attribute to provide advanced user interface when the user edits a given property. For example, if a property allows the user to enter the name of a CSS selector, a tool might search the document for a list of CSS selectors that are used in the document.2008-01-31 TENTATIVE APPROVAL: Call this attribute 'format' instead of 'valueType'
(absent)arrayType In OpenAjax Metadata, for type 'Array', indicates the datatype of the elements of the array. Accepts the same list of datatypes as the 'type' attribute.2008-02-05 TENTATIVE APPROVAL: Get rid of 'arrayType', instead use type='[<type>]' Oops. Maybe this decision won't work. We already use type='[<type>]' for allowing a list of supported types. 2008-02-21 TENTATIVE APPROVAL: Use brackets to indicate Array. Use pipes to indicate list of possible types. Thus, "Number|Object" indicates a scalar that can be either a number or an object and "[Number|Object]" indicates an array whose elements can be either a number or an object.
defaultdefaultThis indicates the default for the instance property. 2008-01-24 TENTATIVE APPROVAL: include 'default' in OpenAjax Metadata
requiredrequiredThis indicates that the instance property in the instance object is required. This is false by default. 2008-02-05 TENTATIVE APPROVAL: Have a 'required' attribute with default of false
nullable(see Notes)This indicates that the instance property allows null. This is false by default.OpenAjax Metadata takes a different approach, saying that a field can be Null by allowing an array of datatypes, such as ["String","Null"].2008-02-05 TENTATIVE APPROVAL: Don't support nullable
unique(absent)This indicates that the instance property should have unique values. No other property with the same name in the instance object tree should have the same value.Should we add this to OpenAjax Metadata so tools know that the given value must be unique across the current document?2008-02-05 TENTATIVE APPROVAL: Don't support unique
minimumminThis indicates the minimum value for the instance property when the type of the instance value is a number, or it indicates the minimum number of values in an array when an array is the instance value.OpenAjax has same semantics for numerics and arrays, just different name, but also says that for strings it is the min length of the string.2008-02-15 TENTATIVE APPROVAL: Follow JSON Schema and have minimum/maximum (for numbers and dates), min_length/max_length (for strings), and min_items/max_items (for arrays)
maximummaxThis indicates the maximum value for the instance property when the type of the instance value is a number, or it indicates the maximum number of values in an array when an array is the instance value.OpenAjax has same semantics for numerics and arrays, just different name, but also says that for strings it is the max length of the string.2008-02-15 TENTATIVE APPROVAL: Follow JSON Schema and have minimum/maximum (for numbers and dates), min_length/max_length (for strings), and min_items/max_items (for arrays)
patternpatternWhen the instance value is a string, this provides a regular expression that a instance string value should match in order to be valid.For OpenAjax Metadata, for type 'String', indicates a JavaScript regular expression against which the string should match. This attribute SHOULD be supported by conforming tools and tools MUST only apply it to string values.2008-02-15 TENTATIVE APPROVAL: Support 'pattern'
length(see Notes)When the instance value is a string, this indicates maximum length of the string.OpenAjax metadata overloads 'min' and 'max' such that for strings they indicate the minimum and maximum length of a string. Isn't the OpenAjax approach better? It allows both a minimum and maximum string length.2008-02-15 TENTATIVE APPROVAL: Drop this - redundant with min/max attributes
options(see Notes)This provides an enumeration of possible values that are valid for the instance property.OpenAjax Metadata has an <enumValues> element modeled after Google Gadgets that allows both an internal value and a display value to facilitate creation of menus2008-02-15 TENTATIVE APPROVAL: Support <enumValues>
unconstrained(absent)When used in conjunction with the options property, this indicates a value can be used that is not in the list of options. This has no meaning when the options property is not a sibling.Could be added to OpenAjax Metadata as an extra 'unconstrained' attribute on <enumValues>2008-02-15 TENTATIVE APPROVAL: Support 'unconstrained' on <enumValues>
readonlyreadonlyThis indicates that the instance property should not be changed (this is only for interaction, it has no effect for standalone validation). 2008-02-15 TENTATIVE APPROVAL: Support 'readonly'
description<description> elementThis provides a description of the purpose the instance property. The value can be a string or it can be an object with properties corresponding to various different instance languages (with an optional default property indicating the default description).OpenAjax Metadata also has a <title> element. There has been discussion about whether arbitrary HTML markup should be allowed.2008-02-15 TENTATIVE APPROVAL: Support <description> and <title>
(absent)<title> element For OpenAjax Metadata, short description of this property, typically used as the label within property editor dialogs and/or tooltip within an editing environment. If not provided, then tools MAY use the property name within any UI that might have used this attribute.2008-02-15 TENTATIVE APPROVAL: Support <description> and <title>
format(see Notes)This indicates what format the data is among some predefined formats which may include:

date - a string following the ISO format address schema - a schema definition object person page

html - a string representing HTML
OpenAjax Metadata (OAM) has something similar, but different. 'Date' is there because OAM supports all of the datatypes from EMCA-262. OAM has some predefined higher-level datatypes (integer, CSS length, CSS color, CSS classname, CSS style, and a lat/long location) but none of the ones listed here. We talked about 'html' but decided to cut it until someone found a need for it.2008-01-31 TENTATIVE APPROVAL: Support 'format' instead of 'valueType'
transient(absent)This indicates that the property will be used for transient/volatile values that should not be persisted. This is false by default.Seems like OpenAjax Metadata should support this concept so that it knows which properties should not persisted into any property persistent engines (which will exist in the mashup space)2008-02-15 TENTATIVE APPROVAL: Support 'transient' and 'hidden'
(absent)scope In OpenAjax Metadata, only applicable to properties on JavaScript classes. Indicates whether this is a static property (i.e., on the object prototype) or an instance property.2008-02-21 TENTATIVE APPROVAL: Support 'scope' per Aptana format to indicate whether property applies to class or instance, add 'jsClass' to specify name of JavaScript class that corresponds to a widget.
(absent)hidden In OpenAjax Metadata, a boolean. If true, this property SHOULD be hidden from the user and therefore tools MUST not show display this property to the user in property editor dialogs. This attribute MUST be supported by conforming tools.2008-02-15 TENTATIVE APPROVAL: Support 'transient' and 'hidden'
(absent)onchange In OpenAjax Metadata, validation JavaScript to execute when the value changes. This attribute SHOULD be supported by conforming tools and tools MUST only apply it to string values. (??? Need to think this through - This might be moved into the set of APIs that support property setters and getters)2008-02-21 TENTATIVE APPROVAL: Postpone discussion until a comprehensive discussion of gadget APIs in general.
(absent)publish In OpenAjax Metadata, a boolean. Default value is 'false'. If true, indicates that whenever this property's value changes, an event will be published on the OpenAjax Hub. Attribute 'topic' indicates the name of the topic that is used when that event is published.2008-01-10 TENTATIVE APPROVAL: Include 'publish', 'subscribe' and 'topic'
(absent)listen In OpenAjax Metadata, a boolean. Default value is 'false'. If true, indicates that the widget subscribes to the OpenAjax Hub for the topic indicated by the 'topic' attribute, and that whenever such an event on the given topic is received, the value of this property will be updated appropriately.2008-01-10 TENTATIVE APPROVAL: Include 'publish', 'subscribe' and 'topic'
(absent)topic In OpenAjax Metadata, a string. Defaults to NULL. Identifies the topic name that is published to (if 'publish' is true) and/or subscribed to (if 'listen' is true) on the OpenAjax Hub. If the attribute is not specified, or is NULL or the empty string, and if 'publish' is true or 'listen' is true, then the value of the 'name' attribute is used as the topic name. (Note that providing a value to 'topic' has no effect if 'publish' is false and 'listen' is false.)2008-01-10 TENTATIVE APPROVAL: Include 'publish', 'subscribe' and 'topic'

Primitive datatypes: OpenAjax versus JSON Schema

The following table compares the primitive datatypes in OpenAjax Metadata versus JSON Schema. Colorization conventions:

  • Green-colored rows indicate that OpenAjax Metadata and JSON Schema have compatible names and definitions.
  • Yellow-colored rows indicate that there are differences that require discussion.


NOTE: 2008-01-24 TENTATIVE APPROVAL: We will use the ECMA-262 datatypes, which have an initial UC, as in "String", but we will also support lowercase versions for the 5 core datatypes in JSON Schema: "string", "number", "boolean", "object", "array".

JSON SchemaOpenAjaxNotesProposed decision or final decision
stringString 2008-01-24 TENTATIVE APPROVAL: Support both 'String' and 'string'
numberNumber 2008-01-24 TENTATIVE APPROVAL: Support both 'Number' and 'number'
booleanBoolean 2008-01-24 TENTATIVE APPROVAL: Support both 'Boolean' and 'boolean'
objectObject 2008-01-24 TENTATIVE APPROVAL: Support both 'Object' and 'object'
arrayArray 2008-01-24 TENTATIVE APPROVAL: Support both 'Array' and 'array'
any(absent)At a previous OpenAjax IDE telecon, we decided to not support 'any' and instead allow for a list of acceptable types, but changed our mind on 2008-01-24.2008-01-24 TENTATIVE APPROVAL: Support 'any' or 'Any' (didn't decide on which one)
(absent)Undefined(From ECMA-262)2008-01-24 TENTATIVE APPROVAL: Do not include 'Undefined'
(absent)Function(From ECMA-262)2008-01-24 TENTATIVE APPROVAL: Support 'Function'
(absent)Date(From ECMA-262)2008-01-24 TENTATIVE APPROVAL: Support 'Date'
(absent)RegExp(From ECMA-262)2008-01-24 TENTATIVE APPROVAL: Support 'RegExp'
(absent)Error(From ECMA-262)2008-01-24 TENTATIVE APPROVAL: Support 'Error'
(absent)void(From ECMA-262, only applies to return values)2008-01-24 TENTATIVE APPROVAL: Support 'void'
(absent)list of datatypes, eg, [String,Null] 2008-01-24 TENTATIVE APPROVAL: Support a list, but without quotes

JSON Schema 'format' versus OpenAjax 'valueType'

Here is a table that compares JSON Schema format versus OpenAjax Metadata valueType:

<td>integer</td><td>2008-02-05 TENTATIVE APPROVAL: Define a new attribute for integer, such as 'isInteger'</td>

<tr style="background-color:lightyellow"><td>(absent)</td><td>length(i.e., a CSS <length>)</td><td>2008-02-05 TENTATIVE APPROVAL: Support format='length', where data matches CSS definition</td></tr> <tr style="background-color:lightyellow"><td>(absent)</td><td>color (i.e., a CSS <color>)</td><td>2008-02-05 TENTATIVE APPROVAL: Support format='color', where data matches CSS definition</td></tr> <tr style="background-color:lightyellow"><td>(absent)</td><td>class (i.e., as in 'class' attribute)</td><td>2008-02-05 TENTATIVE APPROVAL: Support format='class', where data matches format of 'class' attribute</td></tr> <tr style="background-color:lightyellow"><td>(absent)</td><td>style(i.e., as in 'style' attribute)</td><td>2008-02-05 TENTATIVE APPROVAL: Support format='style', where data matches format of 'style' attribute</td></tr> <tr style="background-color:lightyellow"><td>(absent)</td><td>location (JavaScript object literal of the form {lat:<number>,long:</number>}.)</td><td>2008-02-05 TENTATIVE APPROVAL: Don't support format='location', but look at geospatial formats via extensibility</td></tr> <tr style="background-color:lightyellow"><td>(absent)</td><td>Extensibility via format types that use either reverse domain syntax (e.g., org.whatever.whatever) or URIs (e.g., http://www.whatever.com/whatever)</td><td>2008-02-05 TENTATIVE APPROVAL: Extensibility only via URI syntax</td></tr> <tr style="background-color:lightyellow"><td>(absent)</td><td>(absent)</td><td>What about 'email'? 2008-02-05 TENTATIVE APPROVAL: Don't support format='email'</td></tr> <tr style="background-color:lightyellow"><td>(absent)</td><td>(absent)</td><td>What about 'address', 'street', 'city', etc.? 2008-02-05 TENTATIVE APPROVAL: Don't support format='address'. Maybe do something via extensibility.</td></tr> </table>

JSON Schema formatOpenAjax Metadata valueTypeProposed decision or final decision for OpenAjax Metadata
Attribute name is 'format'attribute name is 'valueType'2008-01-31 TENTATIVE APPROVAL: attribute should be named 'format'
Any valid MIME type(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
attachment (binary data as base64)(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
date-time (ISO 8601)OpenAjax Metadata has Date datatype from ECMA-262, but that is an object created from a constructor, with ambiguous toString behaviors (see http://home.clara.net/shotover/datetest.htm)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
date(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
time(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
utc-millisec(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
regexOpenAjax Metadata has RegExp datatype from ECMA-262, with reliable toString behavior2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
phone (E.123)(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
uri(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
url(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
image (??? "should be an image-ref or image attachment")(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
image-ref (URL that references an image)(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
image-attachment (??? "MIME attachment with image as the attachment)(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
urn(absent)2008-01-31 TENTATIVE APPROVAL: don't include this type in OpenAjax Metadata 1.0
(integer is a candidate for a raw datatype in JSON Schema)</span>