Configuring the VO-DML Gradle Plugin

Latest published version

In general, a new data model should be started in its own git repository and configured as below (see ProposalDM for a complete example separate from this repository). If starting a completely new data model then the Template DM Project is probably the easiest way to get going.

If adapting an existing data model repository then

Edit a build.gradle.kts file with reference to the plugin (note substitute below)
```
plugins {
    id("net.ivoa.vo-dml.vodmltools") version "0.x.x"
}
```
create a settings.gradle.kts - it is possible just to copy the template version and just edit the rootProject.name.
create the binding file for the model (see below) for more detail (in fact if you only want to run validation, then the binding file is not necessary).

There is nothing else that needs to be done if the VO-DML files in the default place (see sample build file for some more hints on how gradle flexibility allows finding of the files to be configured in a variety of ways).

If the configuration is successful then

gradle vodmlValidate

will attempt to validate the model and print any errors.

If the validation is successful you can produce various derived products. Developing your VO-DML model further is discussed here.

Detailed configuration

The vodml tools are all configured within a

vodml {

}

section in the build.gradle.kts file.

The various sub-properties that can be set are

vodmlDir - the default is src/main/vo-dml
```
vodmlDir.set(file("vo-dml"))
```
will set the directory to be vo-dml
vodmlFiles - this is set by default to be all the *.vo-dml.xml files in the vodmlDir, but can be individually overridden.
bindingFiles - the files that specify the mapping details between the models and the generated code. N.B. there is no default for this setting - if generating code it must be specified.
outputDocDir - where the generated documentation is created by the gradle vodmlDoc command- default build/generated/docs/vodml/.
outputSiteDir - where the mkdocs suitable model description is created by the gradle vodmlSite command - default build/generated/docs/vodml-site.
outputJavaDir - where the generated Java is created - the default is build/generated/sources/vodml/java/ and it should not be necessary to ever alter this as gradle will integrate this automatically into the various source paths.
outputSchemaDir - where the XML and JSON schema are generated to - the default is build/generated/sources/vodml/schema/ - this is automatically included in the classpath and the output jar.
catalogFile - in general it is not necessary to set this, as the plugin will create a catalogue file automatically from the vodmlDir and vodmlFiles properties (as well as including files in any dependencies that also contain VO-DML models) A catalogue file is necessary as the rest of the tooling is designed to use only the filename (no path) for inclusions and references. If it is desired to create a file manually for a special purpose, then the file should have the format as below - it should be noted that all references to model files will have to be specified if this is done.
```
<?xml version="1.0"?>
<catalog  xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">  
   <group  prefer="system" >
       <uri
               name="IVOA-v1.0.vo-dml.xml"
               uri="src/main/vo-dml/IVOA-v1.0.vo-dml.xml"/>
   </group>
</catalog>
```

Binding Files

The binding file is used to set up some properties for various functions on the model - the most basic of which is that it provides a connection between the model name and the filename which contains the VO-DML model.

<m:mappedModels xmlns:m="http://www.ivoa.net/xml/vodml-binding/v0.9.1">
<!-- ========================================
This is a minimal sample file for mapping VO-DML models to XSD or Java using the gradle tooling
 -->

<model>
<name>sample</name>
<file>Sample.vo-dml.xml</file>
<java-package>org.ivoa.dm.sample</java-package>
<xml-targetnamespace prefix="simp" >http://ivoa.net/dm/models/vo-dml/xsd/sample/sample</xml-targetnamespace>
</model>
</m:mappedModels>

The schema for the binding file shows what elements are allowed. The binding file for the base IVOA model shows extensive use of the binding features, where it is possible to ignore the automated code generation entirely and substitute hand-written code.