Three.js: Formal specification document for JSON Scene Format v4?

[dkushner]

I'm trying to write a few converters in my languages of choice to translate various output formats into the JSON Scene Format v4 but I cannot seem to find an exhaustive, formal specification document anywhere. Does one exist, even in draft status?

For instance, in strongly typed languages (and generally for validation) it would be useful to know exactly what field values may be expected. Would it be possible to build a formal schema based on the JSON schema specification for this purpose?

[satori99]

There is no spec. AFAIK, apart from an example document on the wiki

[dkushner]

@satori99, ah, that's a shame. Perhaps this is something the community can collaborate on? I think it is a valuable specification not only for THREE but for web-based management and distribution of this sort of data generally.

I'd be more than happy to head up the effort, but the issue of what shape it should take and who should be involved remains.

[dkushner]

Coming back to this after some thought, I think it would be a very good idea to set up a separate repository with the specification documents and a JSON schema definition that we can automate tests against. In addition, this would make a good arena to showcase/index various loaders and converters that have been contributed by the community.

I'd be more than happy to set it up with the blessing of the venerable @mrdoob.

[looeee]

@dkushner why a separate repo?

[dkushner]

@looeee no reason other than that the scope of the specification is a bit beyond THREE alone and is a worthwhile effort in its own right. It's quite common to spin off a specification arrived upon by way of another development effort (e.g. Facebook's GraphQL or the JSON Schema spec itself).

If @mrdoob would like to set it up and take contributions, that'd be optimal. I'd not want to step on toes.

[looeee]

@dkushner I'd imagine the scope of this would be considerably smaller than the projects you linked though. The JSON schema should presumably aim to be a 1-1 mapping of Three API elements to JSON names.

Then loaders, converters and exporters would have the task of mapping the JSON schema elements to equivalent or closest elements in other formats. At the moment this is probably done in a fairly higgledy piggledy way as whoever wrote the current loaders and exporters had no formal schema to work from.

So I'd see there being a couple of tasks involved:

1. Create the formal schema
   This in itself is no small task as the Three API itself changes fairly rapidly so any fixed schema will quickly become out of date. This is probably one of the main reasons that no one has made one so far.

   I've actually been thinking about ways this could be partly automated over the last while (in the context of documentation) - perhaps the API could be scanned with each new release and a document highlighting things that have changed could be created, this could then be quickly checked against the schema and documentation?

2. Make current files consistent with the new schema
   Starting with the core, obviously - I'd say there are quite a few "toJSON" methods with inconsistencies. At the very least they'd need to be checked, then moving onto the loaders, exporters and converters.

[dkushner]

@looeee, solid points and no this effort is nowhere near the scale or scope of those other projects.

However, my point stands that the specification, in and of itself, is not strictly coupled to THREE. This is a useful representation of a generic scene graph for many applications. I raise this issue solely because we are developing a product enabling users to collaborate on data best represented in 3D. In order to allow these users to collaborate on multiple devices (browsers and native applications alike) it would be tremendously useful to have consistent interchange format. The web being what it is, JSON is a perfectly viable candidate.

If I may respond to your points in brief:

1. I agree, and specifications may easily be made open-ended for this purpose. With an established JSON schema, validating THREE's serialization behaviour is as simple as stringifying the scene graph and then using any number of existing validators against that schema. However, there's no reason to strongly couple the format definition of objects to THREE's code definition. Buffer geometry is buffer geometry, shader materials are shader materials, etc. Whether these are rendered in WebGL or OpenGL in a native application context, a portable format should be (and currently is) entirely agnostic to the presentation layer.

2. Precisely, and this is exactly why I think it'd be worthwhile to separate the specification effort so that it can evolve independently of THREE. The JSON Schema standard allows for inter-version enhancement of the schema by way of extensions. This is a perfect candidate for allowing those inconsistencies you mention while still maintaining strict schema validity.

[looeee]

it would be tremendously useful to have consistent interchange format.

My feeling on this is that there are already lots of interchange formats (gltf, collada, x3d and so on). In fact glTF is already in JSON format , and maintained by the Khronos Group (collada and x3d are XML).

Perhaps a better approach would be to adopt one of these as the official Three format and then direct our efforts towards developing that rather than creating yet another standard. Preferably this would be glTF as it's already in JSON, but I don't enough about it to comment on whether it is suitable.

[mrdoob]

Yeah... Spec-wise, I would focus on gltf support instead.

I agree with @looeee, I wouldn't stress too much about the json format at this point as that way we'll be free-ish to iterate a bit more on it. Having said that, I think it would be nice to expact the wiki pages a bit more.

[looeee]

@mrdoob would you like me to move the wiki pages into the docs? Seems overcomplicated to maintain references in two places

[mrdoob]

Hmm, I think the wiki is a better place for the specs. But, the wiki definitely needs some clean up.

[looeee]

Fair enough. Perhaps a link to the wiki could be added on the main site though?

[looeee]

Related issue here #6020

[dkushner]

@mrdoob, @looeee: Hey, I know when to quit.

What progress has been made on supporting glTF de/serialization in THREE? Where can I contribute to the effort?

[mrdoob]

@dkushner GLTFLoader is looking good. Unfortunately, the glTF format doesn't map 1:1 to three.js internal structure, so we still need our own format.

[nachoBevilacqua]

Hi, does anybody know if there has been any progress on this? Is there any documentation-schema to be found explaining JSON scene format v4?
Thanks!

[Mugen87]

Are you looking for something like this:

https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4

Apart from the wiki pages, I'm not aware of other documentation.

[satori99]

I used pure Object Format 4 JSON for a demo scene some time back which contains skeleton and animation data:

https://gist.githubusercontent.com/satori99/4d1265b22278741edf49700e6d32f7ba/raw/f2929fce22ace8167c730b3062d3bb3ac4e81f1f/human_scene.json

[nachoBevilacqua]

Thank you guys!