About X-definition

X-definition is registered technology of the Syntea software group a.s., for processing of the XML documents or JSON data.

For the purpose of describing the structure of XML documents or JSON data, their validation, processing and creation, this tool was developed by Syntea Software Group Inc. It allows the user to not only define the structure of XML documents or JSON data, but also to describe specifically their processing and construction.

Homepage: http://www.xdef.org

This project is an implementation for the platform Java 1.8+ (additional note: up to the version 41.0.4 for the platform Java 1.6+).

License

The source code for this project is licensed under Apache 2.0 license.

Examples

You can try the following examples online at: http://xdef.syntea.cz/tutorial/examples/validate.html

Example 1: Essential concepts

Let´s have the following XML data: <Employee FirstName = "Andrew" LastName = "Aardvark" EnterDate = "1996-03-12" Salary = "21700" > <Address Street = "Broadway" Number = "255" Town = "Beverly Hills" State = "CA" Zip = "90210" /> <Competence>electrician</Competence> <Competence>carpenter</Competence> </Employee>

This is the complete X-definition file with the model of the XML data on the left: <xd:def xmlns:xd="http://www.xdef.org/xdef/4.2" xd:root="Employee"> <Employee FirstName = "required string()" LastName = "required string()" EnterDate = "required date()" Salary = "optional decimal()" > <Address Street = "required string()" Number = "required int()" Town = "required string()" State = "required string()" Zip = "required int()" /> <Competence xd:script = "occurs 1..5"> required string() </Competence> </Employee> </xd:def>

Example 2: References

XML data: <Family> <Father GivenName = "John" FamilyName = "Smith" PersonalID = "7107130345" Salary = "18800" /> <Mother GivenName = "Jane" FamilyName = "Smith" PersonalID = "7653220029" Salary = "19400" /> <Son GivenName = "John" FamilyName = "Smith" PersonalID = "9211090121" /> <Daughter GivenName = "Jane" FamilyName = "Smith" PersonalID = "9655270067" /> <Residence Street = "Small" Number = "5" Town = "Big" Zip = "12300" /> </Family>

Model of the XML data: <xd:def xmlns:xd="http://www.xdef.org/xdef/4.2" xd:root="Family"> <Family> <Father xd:script = "occurs 0..1; ref Person" /> <Mother xd:script = "occurs 1..1; ref Person" /> <Son xd:script = "occurs 0..*; ref Person" /> <Daughter xd:script = "occurs 0..*; ref Person " /> <Residence xd:script = "occurs 1; ref Address" /> </Family> <Person GivenName = "string()" FamilyName = "string()" PersonalID = "long()" Salary = "optional int()" /> <Address Street = "string()" Number = "int()" Town = "string()" Zip = "int()" /> </xd:def>

Annotation

This document describes the programming language and the technology called “X‑definition“. X‑definition is designed for description and processing of data in the form of XML or JSON.

X-definition is a tool that provides the description of both the structure and the properties of data values in an XML document. Moreover, the X-definition allows the description of the processing of specified XML objects. Thus X‑definitions may replace existing technologies commonly used for XML validation - namely the DTD (Data Type Definition) or the XML schemas and Schematron. With X-definition it is also possible to describe the construction of XML documents (or the transformation of XML data). X-definitions provides also generation of JAVA class objects similar way as JAXB technology.

X-definition enables the merging in one source of both the validation of XML documents and processing of data (i.e. using actions assigned to events when XML objects are processed). Compared to the “classical” technologies based on DTD and XML schemas, the advantage of X-definitions is (not only) higher readability and easier maintenance. X‑definition has been designed for processing of XML data files of unlimited size, up to many gigabytes.

A principal property of X-definition is maximum respect for the structure of the described data. The form of X‑definition is an XML document with a structure similar to the described XML data. This makes possible quickly and intuitively describe given XML data and its processing. In many cases it requires just to replace the values in the XML data by the description written in the X‑definition X‑script language. You can also gradually add to your X‑script required actions providing data processing. You can take a step-by-step approach to your work.

It is assumed that the reader already knows the elementary principles of XML. To get the most out of this document, you should also have at least basic knowledge of the Java programming language.

X‑definition technology enables also to generate the source code of Java classes representing XML elements described by X‑definition. Such class is called X‑component. You can use the instances of XML data in the form of X‑components in Java programs (similar way as in the JAXB technology).

The term "X‑definition" we use in the two different meanings: either as a name of the programming language or as an XML element containing the code of X‑definition language.

For the complete documentation see the directory xdef/src/documentation.

You can try your examples online at:

• validation mode: http://xdef.syntea.cz/tutorial/examples/validate.html
• construction mode: http://xdef.syntea.cz/tutorial/examples/compose.html
• BNF-grammar: http://xdef.syntea.cz/tutorial/examples/BNF.html
• template: http://xdef.syntea.cz/tutorial/examples/template.html

Usage in other projects

Check and download available versions

Links:

• release versions from the central maven repository: https://search.maven.org/search?q=g:org.xdef
• release and snapshot versions from oss.sonatype.org: https://oss.sonatype.org/#nexus-search;gav~org.xdef

For maven projects

Configuration file pom.xml:

• dependency on release version in the central maven repository:

  <dependencies>
      <dependency>
          <groupId>org.xdef</groupId>
          <artifactId>xdef</artifactId>
          <version>[release version]</version>
      </dependency>
  <dependencies>

• dependency on release or snapshot version in oss.sonatype.org:

  <dependencies>
      <dependency>
          <groupId>org.xdef</groupId>
          <artifactId>xdef</artifactId>
          <version>[release or snapshot version]</version>
      </dependency>
  <dependencies>
  <distributionManagement>
      <snapshotRepository>
          <id>ossrh</id>
          <url>https://oss.sonatype.org/content/repositories/snapshots</url>
      </snapshotRepository>
      <repository>
          <id>ossrh</id>
          <url>https://oss.sonatype.org/service/local/staging/deploy/maven2</url>
      </repository>
  </distributionManagement>

Building this project

Source code at GitHub:

• link to the last stable version (to the branch "master"): https://github.com/Syntea/xdef

Prerequisities:

• download project X-definition, eg. from GitHub
• install java (at least version 8)
• install maven (at least version 3.6)
• configure:
  • configure the maven-plugin toolchains (see https://maven.apache.org/plugins/maven-toolchains-plugin/usage.html):
    • configuration the xml-file ~/.m2/toolchains.xml in the home directory
    • see the template-file configure/maven/toolchains.xml

Frequent building operations:

• cleaning before any compiling, building, deploying, etc.:

  mvn clean

• compile all java-resources, respectively all compilable resources:

  mvn compile

• build the snapshot package:

  mvn package

• build the snapshot package including javadoc, sources, documentation:

  mvn package -Pjavadoc,sources

• by using the "skipTests" profile, avoid junit-tests:

  mvn package -PskipTests

• by using the "testOnAllJvm" profile, junit-tests will be run on all configured Java platforms, i.e. Java-8 (it is run by default in xdef module), Java-11 (using the xdef-test11 module), Java-17 (using the xdef-test17 module), Java-21 (using the xdef-test21 module):

  mvn package -PtestOnAllJvm

• build the release package:

  mvn package -Prelease

• build the release package including javadoc, sources, documentation:

  mvn package -Prelease,javadoc,sources

Deploying to the maven central repository

Prerequisities:

• satisfy prerequisities for building
• install the pgp-managing software GnuPG (https://gnupg.org/)
• configure:
  • unlocking the appropriate pgp-key
    • insert the appropriate key to the the pgp-manager
    • enter the pgp-key-password for the pgp-key:
      • during the package build by the user when prompted by the pgp-agent
      • or beforehand to the environment variable MAVEN_GPG_PASSPHRASE (see https://maven.apache.org/plugins/maven-gpg-plugin/sign-mojo.html#passphraseEnvName)
  • authentication to the maven repository manager oss.sonatype.org (having id "ossrh" in the file xdef/pom.xml)
    • configure the maven-configuration-file in the home directory ~/.m2/settings.xml
    • see template-file configure/maven/settings.xml

Deploying:

• build and deploy the snapshot package to the repository oss.sonatype.org:

  mvn deploy -Pjavadoc,sources,dm-ossrh

• build and deploy the X-definition release package to the central maven repository (through the repository oss.sonatype.org):

  mvn deploy -Prelease,javadoc,sources,dm-ossrh