JSOM/object reference

This page is a complete (work in progress) object reference for the JSOM (JSON Sword-of-Moonlight Object Model) schema.

Overview

Before everything else, the JSOM schema is an animal of the popular JSON information interchange format, which is itself a subset of the widely implemented scripting programming language popularly known as JavaScript, more formally the ECMAScript standard. The organization is for the most part the logical conclusion of the minimal approach taken by the JSON standard. It is therefore important to be familiar with JSON if what you are after is an actual comprehension of this document. JSON is incredibly simple by design. Compared to the rest of this document it is nothing.

A JSON resource adhering to the JSOM specification at the top level consists of several named arrays of objects, each with a characteristic name; externals, templates, images, sounds, arrays, attributes, elements, semantics, materials, graphics, keyframes, keygroups, tracks, are all core to the spec. These are properly referred to as "namespaces" and they represent lists of items. The items themselves can contain sub-lists, so that the general structure of the namespace is that of an outline; Eg. item 0.1.1 refers to the first (zero-based) item at the top of the namespace, and then to the second item of its sub-list, and then to the second item of that item's sub-list. Items can be alternatively addressed by name, hence the term "namespace". Names within a namespace are assumed to be unique IDs, and are not hierarchically arranged, dotted or otherwise (should a name collision occur, the previous holder of the name is effectively disappeared.)

Items and Lists

A JSOM item is a top-level object in the namespace hierarchy. So-named because they are always an object item of a JSON array. Items in an array do not have names, but you can assign a name to an item by giving a it a name property. If an item contains a property with the same name of the name space it will form a sub-list. For examples, an item in the graphics namespace, may contain a 'graphics' property of its own. The graphics property can then contain a list of "sub-graphics". This methodology is strictly limited to the current namespace. You cannot for instance add a sub-list of "images" to an item in the graphics namespace. If you see such a property it is more than likely an index; indexes are described in the following section.

Indices, Index Singular

Items (and even properties) often contain properties which are characterized as "indices". The property may be a single index (singular of indices) or an array of indices. An index refers to an item of one of the namespaces. The property name itself determines which namespace. Eg. a 'sound' property that is made up of indices is understood to refer to the 'sounds' namespace. In the case of an index array, all indices in the array refer to the same namespace. A property is either an array (referring to 0 or more items) or it is not. Usually properties are array based unless under no circumstances would it make sense to be so. An empty array is equivalent to the property not existing, or the null index, explained and illustrated below.

The indices themselves can come in one of five interchangeable varieties:

• A null index; a null value, as described by the JSON specification. This is equivalent to the property not being defined in the first place.

• A single numeric index; a number indicating a top-level item of the relevant namespace at resource scope. Indexes cannot refer to a scope above the resource they reside in. See #External Resources for details.

• An array of numbers; each subsequent number indicating an item of a sub-list as explained in the #Items and Lists section.

• A JSON character "string" index. This is a non-numeric name proper index, Ex. "left leg".

• An inline item; rather than indexing an item, a new item can alternatively be defined on the spot. Often this is the right idea. The only thing to bare in mind is that such an item can never be indexed from outside the defining index.

External Resources

The content of a JSOM resource can conceptually include further JSOM resources by external references. A JSOM resource can also contain non-JSOM resources, such as a reference to PNG image, but that is a dead end as far as the JSOM schema is concerned. The inclusion mechanism is one-way, "downstream", which is to say, a resource can reference sub-resources, but not vice versa. The single exception to this is Templates, explained in the next section (however to say that templates refer to anything is a misunderstanding of how templates work.)

The rationale for limiting ourselves to a one-way architecture is an extension of the strengths and weaknesses of JavaScript implementations (which is a topic beyond the scope of this document.)

The only path to including an external resource is through any item of any namespace. We will call this item a reference. A reference is a second-class item. Even though it has an address, it cannot be addressed, and there is no reason to do so, because it is only a placeholder for the included resource. The sub-list of the item is populated with the items from the external resource which share the namespace of the reference. Due to "lazy" indexing syntax, the reference effectively becomes a placeholder for the first included item of the external resource.

Lazy indexing rules follow: whenever a reference is indexed. If an item in its sub-list is not indexed, then the index will indicate the first item included by the reference, or if that item is itself a reference, the first item included by that reference, and so on. This is referred to as the "underflow" syntax. If the reference is the last item in its namespace, then the remainder of numeric index will be used to index the references sub-list. This is referred to "overflow" syntax. In this way it is often the case that external resources may be indexed without resulting to named or arrayed indices.

Template Expansion

Template items are generic bags of properties which in and of themselves have no meaning. An index into the "templates" namespace bestows meaning to the template, however only in the instance of that particular index. This process is referred to template expansion. The most generic example of expansion can be seen in the 'template' property, which each and every item has access to, and by which an item may pull in values from any number of templates. Reasons for working with templates can be varied and under some circumstances necessary by design. They can make a resource more compact for instance, but compression can also achieve roughly the same results. Templates can be an organizational convenience when writing a JSOM file and also if used correctly lower the memory overhead of a resource as used by a JSOM aware application.

A typical application will want to expand templates as soon as possible. In a JavaScript execution environment this will most likely result in all items and indexes referencing a template growing by the number of properties in the template, barring cases where properties are accessed selectively. So on the face templates might come at a slightly greater memory overhead, assuming the ratio of templates to items is slight. However templates can be a memory win when the properties of templates are large macro objects. Any kind of array or object with multiple properties for example. Such objects are not themselves expanded, and therefore will result in shared memory. If you need multiple instances of a large object, this is a good strategy for economizing memory.

Finally its important to remember that the index properties of templates do not indicate items from the resource of which the template item itself is part. The index properties are those of the items taking part in the template expansion, and the indexes themselves will refer to the resource and sub-resources in which the expanded item resides. This behavior is normally desirable, however the rules of expansion can be changed on a per template basis using the templates #expand property.

Extensibility

In theory items can contain user defined properties not mentioned as part of this document. How these properties are to be interpreted and or used can vary according to circumstances. For instance, attaching custom variables to programmable shaders.

There are no real provisions at this time to preempt the collision of custom properties and those added by future revisions of any particular JSOM specification or whatever.

Universal properties

This section lists properties which are common to all items regardless of namespace. These properties do not take on special meaning under any circumstances.

name

The name property permits an alternative to numeric indexing, with the downside of needing to have names handy or some mechanism for generating them on the fly. Names should be unique unless the behavior you are looking for is to overriding of a named item by the later/possible inclusion of an item with the same name. A name is a character "string".

template

The template property is an array of indexes into the #templates namespace. All properties from the templates indexed will be added, first to last, to the item containing the template property, including any template properties contained within the templates themselves. Note that properties overwrite one another. They are never added together in any way. A template is an array of indices.

ref

The ref property is a name that refers to an undetermined external resource. The item containing a ref property is a reference according to #External Resources however the resource in question is to be determined by the JSOM client application, which will use the value of ref to determine which resource to use. A ref is a character "string".

url

The url property is a numeric index into the #externals namespace. It results in a reference item that is determined entirely by the resource (compare to #ref above) at the time of its creation. A url is a singular index number.

<namespace>

Where <namespace> is the same name as the current namespace, Eg. graphics for the graphics names, images for the images namespace. This property is an array of namespace item objects which will form a sub-list beginning at the current item of the current namespace. A <namespace> is an array of namespace item objects.

Namespace properties

Each heading of this section is representative of a namespace of the same name. Each section below each heading describes the function of the namespace and the non-extended (see #Extensibility) properties that are meaningful to the items of that namespace.