[Discuss] Arduboy Game Format (.arduboy) Guide

(Scott) #122

Just a very minor possible reason:
It could make it a bit easier for an author who was creating a JSON file by editing a blank template that might be made available. The author would be able to skip optional strings by leaving them null, instead of needing to delete the entire objects. Of course, ideally a program or form would be made available to authors, instead of a raw template. However, I think your “it’s liable to be a mistake” argument holds more weight towards the desirability of requiring at least one character.

I don’t think so. Keep in mind that the schema is just something that can be used by some kind of validator (or form generator) program to assure that a corresponding JSON file is correct. That validator can choose to do whatever it wants with the information provided in the schema.

Also, unless a loader program actually uses the schema to validate info.json, it can’t automatically trust info.json to be correct. The loader program must itself assure that the data provided is compliant with what it expects.

This is why I’d like to also provide maximum string length limits. Even if it’s just enforced manually by the author browsing the schema, it will prevent problems like “How was I to know that the loader would reject my title because it’s 700 characters long? You didn’t specify a limit!”. We should agree upon and document the maximum allowed length of all string fields.

(Scott) #123

Yes, “schemaVersion” has been added. The best way to determine what’s in the current info.json schema, is by looking at it.

Note that even though the info.json has changed in non backwards compatible ways since its inception, the current version is still considered to be Version 1 and including a “schemaVersion” field is optional. So yes, “old” versions are broken without a straightforward way of determining this.

This is because there currently exists .arduboy files with either old or new info.json files that both don’t contain the “schemaVersion” field. We don’t want to have to again go back and add “schemaVersion” to new format files. So, we’re already in a situation where there’s no “schemaVersion” field to determine if it’s the old or new format.

We’re currently in a chaotic situation where an info.json file with no “schemaVerson” field is considered to be Verson 1. The old non-compatible versions are considered to be beta.

A loader can choose to either reject an info.json that isn’t in the current format, or support the older beta format as well as the new V1 format, by checking and handling the differing field types within in the incompatible fields (“binaries” and “screenshots”).

In the future, if info.json becomes non backwards compatible, “schemaVersion” would be changed to require a value of 2 and be made a “required” field.

(Timothy) #124

Sorry I’m busy with my dayjob mostly :slight_smile:

(Mike) #125

Last time I looked into json schema, the projects were pretty much dead. But you can do a lot more than validation & form generation with a good schema - look into the things people are doing with XML schema, like schema-aware editors and automatic test generation. Be nice to have something like the RNG compact format to, but that’s off topic.

If we use maximum length, it ought to be long. Loaders potentially have to deal with a hex file, so 64K doesn’t seem excessive.

BTW, thanks for doing the schema. Using a validator on generation means I can be sure my output is correct, and using it on input means my code gets simpler as I can assume a valid document everywhere else, and the user gets consistent, hopefully high quality error messages on invalid input! That there are people who don’t even create them for XML - which was born with schemas - still boggles me.

(Mike) #126

I would say making it optional is a mistake. Sure, for maximum backwards compatibility, you have to check the template explicitly if it doesn’t validate, but that’s true anyway, since not all “old” formats will validate now. If you use a validator (recommended) and it fails, you can either reject that file with an error message, or give it special handling. If you’re going to do the special handling, dealing with both isn’t a lot harder. If you’re not, then you now reject a few more files.

On the other hand, making schemaVersion optional means that the number of files without a schemaVersion is potentially much larger. Better to bite the bullet now while the problem is small and people are actively engaged in working on things.

(Scott) #127

Are we talking about the same thing here? I’m proposing that we use the “maxLength” schema keyword to specify an agreed upon maximum allowable length for each individual string field in info.json, the same as we want the minimum length of each to be 1. (They don’t all have to have the same maximum length.)

If I’m writing a loader and trying to determine what layout I’m going to use to present all the images and information in the .arduboy file, I think I’d want to know the maximum length of, say, “title” so that my layout can fit it in the space I’ve allotted, without having to truncate. Likewise, do you think users of the loader would want to see “author”, “publisher”, “idea”, etc. fields that were hundreds of words long?

Again, I’d be interested in knowing if the current loaders have such restrictions and what they are. How do the loaders read and display each provided info string, and what do they do if, say, a binary file’s title is 5000 bytes long?

(Scott) #128

I believe @crait, and possibly @delegatevoid and/or @JO3RI, have already created “new format” info.json files without including “schemaVersion”.

If you can convince them to “bite the bullet” once more and change them all again, to include “schemaVersion”, then we can indeed make “schemaVersion” a required field. If this is done, I suggest that at the same time we designate the current schema as version 2.

(Mike) #129

[quote=“MLXXXp, post:127, topic:2685”]

[quote=“mwm”]If we use maximum length, it ought to be long. Loaders potentially have to deal with a hex file, so 64K doesn’t seem excessive.

Are we talking about the same thing here? I’m proposing that we use the “maxLength” schema keyword to specify an agreed upon maximum allowable length for each individual string field in info.json, the same as we want the minimum length of each to be 1. (They don’t all have to have the same maximum length.)

Well, I thought you wanted a maximum length so programmers could allocate buffers, not for UI design purposes. But we are talking about the same lengths. I’ve watched users (and companies) abuse text fields and blow length limits on email multiple times: VMS users tended to use hundreds of characters of subject and an empty body, and when MS started line wrapping text formatted email, among the many things that broke were every mailer in the world that expected people to pay attention to the maximum line length for email in RFC 822.

My only opinion about UI-based limits is that, since we’re moving to voice interfaces you may want to specify it in phonemes :grin:

(Mike) #130

I took the statement that some were already out there to mean that some new format info.json files had been created without a schema version field. Files without schema versions are almost certainly going to have issues at some point in the future. If you can’t think of a reason to create such a file now that it’s in the schema, then it might as well be required. Yeah, that means those who created files recently will have to fix them sooner, but it will prevent it from happening to more people later on.

The more users we have, the more people will be affected by a breaking change, the harder they become to introduce. Once the schema version is required, there are no “breaking changes”, there are only “unsupported versions”. So the sooner this gets done, the fewer people it will negatively impact and the easer it is to do.

(Scott) #131

No, It’s more the case of wanting the schema to be self-documenting for game authors who are creating info.json files, to be sure that what they enter is what’s going to be displayed.

If I’m creating info.json for my game and I post a message here asking: “What is the maximum length allowed for the string that I put in the “description” field, to be assured that it will be handled and displayed properly by all game loaders?”, what would be the answer? (By the looks of it, I wouldn’t get a reply, but that’s beside the point :frowning2:)

Having a “maxLength” keyword associated with “description” (and other strings) would answer the above question without the need to ask it here or elsewhere. It would also allow the length to be automatically constrained by a form or program built using the schema as input.

Of course, having these maximum lengths specified would also benefit someone designing the presentation part of a new loader.


@MLXXXp @mwm

No to maxLength
Yes to schemaVersion required field.

This is it. Let’s fix these decisions to version 2. Wrap it up. And we can start creating .arduboy files.

(Scott) #133

What about “minLength”? should it be 1 for all string fields or just “requried” fields?


@MLXXXp no minLength either. A gameloader will not benefit from the fact there is a minLength. Even if is HAS minLength = 1 and you don’t fill out the field you have a false .arduboy file.

(Scott) #135

It’s not for the benefit of the game loader. It’s for the benefit of the info.json creator. If a field is “requried” then there should be something in it.

I’m going to put "minLength": 1 on only “required” fields. This will help prevent an empty “required” field that is present.


@MLXXXp okay ! that will be the last change.

I’m updating the guide and linking to the Github page itself in the guide. Also making the guide a lot shorter, because the schema is now self explaining.

We call this schemaVersion 2 and it is now closed for changes !!!

(Scott) #137

From the guide:

@JO3RI, The arduboy-json-schema.json is not an info.json example/template. It’s a schema containing metadata with instructions on how to create an actual info.json file. It would be quite difficult to use arduboy-json-schema.json itself as a base to create an actual info.json file.

I suggest that we provide an actual info.json template that could be used along with arduboy-json-schema.json as a reference document. The template could contain either blank fields or fields with typical example data that could be replaced. It might be a good idea to provide two templates; one being a bare minimum example with only the required fields, and a second containing all the possible fields.

As an alternative or addition (until something better is available), I suggest that the guide include the following link to Jeremy Dorn’s JSON editor example, pre-set with the info.json schema. Authors could go to this link, fill in the form, and then copy the resulting JSON Output that appears in the box at the top right.

Form to create JSON data for an info.json file:


With Firefox at least, I find it easiest to double or triple click on the URL (to select it all) and then right-click and select Open Link (whatever).

(Holmes) #138

@JO3RI, you should embed an example info.json file into code tags so people can copy/paste the content. It’s fine to have the schema there, but I have been using that thread to quickly grab the example file.

(Scott) #139

@crait, If you were grabbing the example file as a template to create a new info.json, you can use the link to the example form I provided above. Until you add values to the form, the JSON Output box contains the text for a blank, but complete info.json file.

Or, fill in all the form fields before copying the output, for a completed info.json file. Use the form’s Properties buttons to remove any unwanted optional fields.


@MLXXXp fair enough ! I will add both the Jeremy Dorn’s example and a proper info.json example link to the guide.

@crait Yep will do, I’ll add en example info.json too


@MLXXXp @crait DONE !