How to create a schema bundle

This guide prepares the XSD files for a schema for Fonto's schema compiler. The schema compiler is used once, or when the XSD's are updated, to compile a web-optimized version of the schema into your editor. This enables the editor to perform real-time, client side validation.

What you need

To get started on a schema bundle you need the XSD files of a schema. If you do not have a schema you can use our example schema from GitHub, run:

Terminal

Shell

git clone https://github.com/FontoXML/training-schema-bundle.git --depth 1

If you do not have XSD schema files, but instead have DTD or RNG files. You can use a tool such as Oxygen to convert your files to XSD.

1

Create a fonto.json

The fonto.json file is used by the compiler to determine the repositories to place the compiled files in to and how a newly created Fonto Editor instance loads these for the relevant XML files.

Create a new file called fonto.json in the root folder of your schema. When using our example schema, the location for this file is training-schema-bundle/fonto.json. The contents of this file initially looks like this:

training-schema-bundle/fonto.json

JSON

{
    "rootSchemas": {}
}
2

Add your entry XSD files to rootSchemas property in the fonto.json

Add new properties to rootSchemas for every entry XSD your schema has, where the key is a relative file reference. When using the example schema, this is only the recipe.xsd file. If your XSD modules import or include other XSD modules, that will be handled automatically. Your fonto.json becomes:

training-schema-bundle/fonto.json

JSON

{
    "rootSchemas": {
        "xsd/recipe.xsd": {}
    }
}
3

Add packageName and locations properties to your fonto.json

Fill out the packageName and locations properties for every rootSchema. The package name affects the code structure generated by the schema compiler, so pick a descriptive name that does not contain special characters.

The locations property is used to match a given XML document with the schema. The value for this property can be found on the xs:schemaLocation or xsi:noNamespaceSchemaLocation attributes of the root element on one of the files you intend to use with your schema - the documentation of SchemaLocationToSchemaExperienceResolver has more information on where the location may be matched with.

When using a schema that has a single entry XSD you can choose to omit the locations property. This does require you to use the SingleSchemaExperienceResolver in your Fonto Editor instance.

When using the example schema we can find what is already used from the XML files in training-schema-bundle/test/. The fonto.json file becomes:

training-schema-bundle/fonto.json

JSON

{
    "rootSchemas": {
        "xsd/recipe.xsd": {
            "packageName": "recipe-sx-shell",
            "locations": ["urn:fontoxml:training:delicious:recipe.xsd"]
        }
    }
}
4

Check that it works, and commit

Your schema bundle is used to create new Fonto Editor applications, or update an existing configuration. If your schema bundle works well, both should work without errors. Please see also the fdt editor init and fdt editor schema compile commands, or continue to our next guide: Create a base editor!

To quickly check that the schema bundle works, you can create a new editor in a temporary folder with the following command;

Shell

mkdir tmp && fdt editor init tmp --schema . --non-interactive --version 7.13.1

In most cases it is recommended that you commit your fonto.json together with the XSD files into version control -- possibly as a sub-directory of the repository that also contains your editor configuration. You will need it again when the schema changes, or in some upgrades to a newer SDK.

The minimal folder structure should look like this:

Folder structure

Other

Training/
  training-schema-bundle/
    fonto.json
    xsd/
      recipe.xsd