JSOM/object reference

This page is a complete (work in progress) object reference for the JSOM (JSON Sword-of-Moonlight Object Model) schema. Anyone who wants to can participate in the drafting of this specification or whatever you might call it. It is open to whoever likes what they see / would like a little more. You can call it the JSON Scene Object Model if that makes you more comfortable. If the name is not already taken by some more respectable effort that is.

Overview

Main article: JSOM

More than anything else the "JSOM" schema as a creature of the popular JSON information exchange format. It is a JSON schema after all. JSON is a subset of the popular JavaScript programming language / ECMAScript standard. Minimalism is part and parcel of the JSON specification, which is another way of saying it is really very brief. Now is a good time to read about JSON if you've never heard of it before. Any code in this document is JSON. It's pretty simple stuff, so JSOM by extension is pretty simple. That's good and bad. In case you are wondering why things are so simple, well that is why. OK! Moving on.

The job of a JSOM (JSON) resource is to deliver graphics to an application that is probably programmed in JavaScript and running in a JavaScript engine of some kind, probably in a WWW browser. The application should be to display the graphics themselves, or combine them with other graphics in an interactive fashion if need be. This should be fast to do and not overly complicated. Animation is also very important. In theory every aspect of the JSOM resource should be able to be animated. Animation is not the same as interaction, however direct interaction and scripting is a desirable feature as well.

At the top level of a JSOM resource you will find several named arrays of objects with various characteristic names; externals, templates, images, sounds, arrays, attributes, elements, semantics, materials, graphics, keyframes, keygroups, tracks, are all core to the specification. 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 a namespace is more like 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 it a name property. If an item contains a property with the same name of its namespace 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" and so on. The only thing to remember is that this kind of "nesting" is strictly limited to the operative namespace. You cannot for instance add a sub-list of "images" to an item in the graphics namespace. Any property that looks like a sub-list from another namespace is more than likely an #index.

Indices, Index singular

Indices are always properties of items, or part of a multi-index array that is itself a property. Each index refers to an item in one of the aforementioned namespaces, if any item at all. The name of the property pre-determines the namespace the index belongs to. If you don't know for sure, then you just have to look it up. Eg. an index property named 'sound' is going to be made up of indices which refer to the 'sounds' namespace. Pretty straightforward. Sometimes however the name of the property does not correspond letter by letter to the name of the namespace. That is what this reference is for.

Now when indices are part an array, you can rest assured in the knowledge that all of the indices refer to items of just one of the multiple namespaces. And just to make things even simpler, you can always bet that a property is either an array (referring to 0 or more items) or not an array (referring to a single item) but never either or. The general rule is that if it would ever under any circumstance make sense to refer to more than one item by with a particular index property then that property is going to be a multi-index array. And before we are done with index arrays. In case you are wondering. An array may be the JSON null value, and it may be empty, and it may contain all null values, in any of these cases it is functionally equivalent to the index array not existing at all, which is the same as a non existent or null value non-array index property.

Index values come in five interchangeable flavors:

• A null value; 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 value; a number indicating a top-level item of the relevant namespace at resource scope. Indexes cannot refer to a scope above the resource in which they are defined. See #External Resources for details.

• An array of number values; each subsequent number indicating an item in a sub-list as explained in the #Items and Lists section. So think comma notation rather than dot notation, but an outline nonetheless.

• A JSON character "string" index. This is a non-numeric name proper index, Ex. "left leg". These global to a namespace, any string literal works.

• 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 bear in mind is that inline items can never be indexed into from other indexes. In case you are wondering, yes (in theory anyway) you can make a strictly serial JSOM resource consisting of pure inline notation.

External Resources

The content of a JSOM resource can pull in outside JSOM resources through the power of external references. This is great both for organization and not putting all of your eggs into one basket; so to speak. A typical JSOM resource also includes non-JSOM resources: a reference to a PNG image for example; but these types of resources are dead ends as far as the JSOM schema is concerned, so we will not speak of them again.

The inclusion mechanism is one-way, "downstream", which is to say, a resource can include references to sub-resources, but not vice versa. There is a way around this limitation to some degree, namely through the judicious use of #Templates (keep reading) except for that to say templates refer to or include anything would demonstrate a misconception of how the mechanism is supposed to work.

Unidirectional data flow is not a hard constraint. It is open to discussion. The arguments against it is a resource becomes more brittle if it can reference things upstream. An implementation would have to keep track of what is upstream in every context at the function level should the resource be shared. A special mechanism would need to be devised for upstream indexing. In general its comforting to know that your resources are functionally self contained units top to bottom. Conceptually a resource has direct knowledge of what lies below it. And no clue about what may lay above.

What can be a reference? In practice any item may be a reference. A reference to what? A reference to the namespace of another resource that bears the name of its own namespace. In fact the referenced namespace becomes one of those sub-lists we talked about. Except for one thing! A reference is a second-class item. Even though it has an address, it cannot be addressed; by an index for example. There is really no reason to do so. And either way the reference effectively becomes a placeholder for the first item of the included resource (or no item, if no such item exists) due to "lazy" indexing rules. Maybe you've heard of it. Oh you haven't?

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 can be referred to as the "underflow" rule--if you want. If the reference is the last item in its list then the remainder of a numeric index is used to index into the reference's sub-list. You can call this the "overflow" rule--if you will. Whether lazy indexing is technically "lazy" is up to debate. Dotted and named indexes may be unnecessary if you can refactor your resources about lazy indexing. You might even leverage such a scheme to shim in an extra layer of modularity to whatever it is you are doing. Just make sure you understand the rules and everyone involved understands when they are in play.

Template Expansion

A #templates item is a generic bag of properties. In and of itself without meaning. It is not a true item though the same indexing rules apply. Depending on the semantics of an index the properties of the template are usually conferred in some way to some other item either directly or indirectly. Whenever the transfer of properties does take place, it is what we are calling template expansion for our purposes here.

The most basic example of expansion is the universal 'template' property. Every item may have this property: which says that on top of what properties the item has, it will also have the properties of said template(s). Expansion happens at the latest just before the item is to be considered in terms of its properties, first index to last index the template(s) properties are copied into/over those of the item being expanded. Templates may index other templates, same rules apply. Properties are never added together or anything like that. Everything is strictly overwritten. Which in JavaScript normally means that only an object reference or a similarly irreducible literal will be copied. This can be used to your advantage if you need to keep memory overhead to a minimum. Ie. by sharing macro values whenever practical.

JavaScript is usually best at chewing up memory and slow about computing anything on the fly. What seems to work is to compute everything once and keep it in memory if speed is important. So if nothing else effectively managing said memory can be a considerate thing to do on behalf of what users you are able to sucker into whatever it is you are up to.

But that's not the end of templates. Templates are an integral part of the JSOM schema. Template indexes do occur in the wild and you will probably come across one sooner or later. You should just remember that templates do not do anything on their own. Their indexes are inert until expansion happens, and that does not necessarily happen inside the resource in which the template is defined. But what about #expand you ask? Glad that you asked... or ah no. Just kidding. That can be for homework.

Extensibility

You may come across properties not mentioned anywhere within this document. They may just be experimental, or they may be user defined properties. User defined properties are permitted. A resource might want to for instance, attach custom variables to a programmable shaders, or the properties might be purely ancillary to the JSOM aware application layer. Either way there are no considerations as of yet concerning the collision of custom properties and those added by future versions of any particular JSOM specification or whatever. Just saying you can go wild if you gotta.

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.