Skip to content

Migrating

Jump to bottom
Kirill Dunchenko edited this page Sep 15, 2026 · 2 revisions

From 1.x.x to 2.0.0

hitori 2.0.0 introduces a new module metadata format.

In hitori 1.x.x, module metadata was stored in a hitori.properties file. Starting with hitori 2.0.0, this file has been replaced by hitori.module.json.

This guide explains how to migrate your module metadata from the old format to the new one.

1. Before and After

hitori 1.x.x

A typical hitori.properties file looked like this:

key=docs:example
version=1.0
description=Example module for hitori documentation
main=docs.example.ExampleModule
package=docs.example

hitori 2.0.0

The equivalent metadata is:

{
  "key": "docs:example",
  "version": "1.0.0",
  "main": "docs.example.ExampleModule",
  "packages": [
    "docs.example"
  ],
  "description": "Example module for hitori documentation"
}

The most important changes are:

  • hitori.properties → hitori.module.json
  • Properties syntax → JSON syntax
  • package → packages
  • packages is now an array
  • Version values must use proper SemVer
  • hitori 2.0.0 adds several new optional metadata fields

2. Field Migration

The following table shows how fields from hitori 1.x.x map to hitori 2.0.0.

hitori 1.x.x hitori 2.0.0 Required Description
key key Yes Unique module identifier
version version Yes Module version in SemVer format
description description No Human-readable module description
main main Yes Fully qualified name of the module's main class
package packages Yes Base package(s) used by the module
— authors No Module authors and their links
— website No Module website or project URL
— bootstrap No Fully qualified name of the module bootstrap class
— build No Build-related metadata
— depends Yes Module and runtime dependencies

3. key

The key field works the same way as it did in hitori 1.x.x.

{
  "key": "hitori:template"
}

It is the unique identifier of your module.

The value follows the same concept as an Adventure Key.

For example:

hitori:template
docs:example
myproject:core

Migration

No changes are required other than moving the value into JSON:

key=docs:example

becomes:

"key": "docs:example"

4. version

The version field is still used to specify the module version, but it now follows standard SemVer formatting.

{
  "version": "2.0.0"
}

Examples:

1.0.0
2.1.3
0.1.0
0.1.0-build13

Migration

If your old metadata contains:

version=1.0

it should be changed to a valid SemVer version, for example:

"version": "1.0.0"

Important: Make sure the version you specify is compatible with the versioning rules expected by hitori 2.0.0.

5. description

The description field remains essentially unchanged.

hitori 1.x.x

description=Example module for hitori documentation

hitori 2.0.0

"description": "Example module for hitori documentation"

The value is a human-readable description of your module.

This field is optional.

6. main

The main field remains unchanged in purpose.

It contains the fully qualified class name of your module's main class.

{
  "main": "su.hitori.template.TemplateModule"
}

Migration

main=docs.example.ExampleModule

becomes:

"main": "docs.example.ExampleModule"

No structural changes are required.

7. package → packages

This is one of the important changes in the new metadata format.

hitori 1.x.x used a single package property:

package=docs.example

hitori 2.0.0 uses packages, which is an array:

{
  "packages": [
    "docs.example"
  ]
}

This allows a module to declare multiple packages.

For example:

{
  "packages": [
    "su.example.core",
    "su.example.api",
    "su.example.internal"
  ]
}

Migration

Change:

package=docs.example

to:

"packages": [
  "docs.example"
]

If you previously had only one package, simply put it into the array.

8. authors

authors is a new optional field introduced with the JSON metadata format.

It contains a mapping of author names to their URLs.

{
  "authors": {
    "just_lofe": "https://github.com/justlofe",
    "StreamVersus": "https://github.com/StreamVersus"
  }
}

The key is the author's name or identifier, while the value is a URL associated with that author.

For example:

"authors": {
  "Alice": "https://github.com/alice",
  "Bob": "https://github.com/bob"
}

If your module does not need author metadata, this field can be omitted.

9. website

website is another new optional field.

It specifies the project's website, repository, documentation page, or another relevant project URL.

{
  "website": "https://github.com/modoruru/hitori-template"
}

For a GitHub project, this can simply be the repository URL.

If your project has no website, you can omit the field.

10. bootstrap

hitori 2.0.0 introduces the optional bootstrap field for specifying a module bootstrap class.

{
  "bootstrap": "su.hitori.template.TemplateBootstrap"
}

The value is the fully qualified class name.

Unlike main, this field is specifically intended for the module's bootstrap class.

If your module does not define a bootstrap class, omit the field.

11. build

The build object contains metadata about how the module was built.

Example:

{
  "build": {
    "ide": false,
    "commit": "fc68e151"
  }
}

It can contain the following fields:

Field Type Description
ide Boolean Indicates whether the module was built from an IDE
commit String Git commit associated with the build

build.ide

"ide": false

This is a boolean value, so it must not be written as a string.

Correct:

"ide": false

Incorrect:

"ide": "false"

build.commit

"commit": "fc68e151"

This identifies the Git commit associated with the build.

The entire build object is optional.

12. depends

The depends object declares requirements for the module.

The following dependencies are required:

  • java — required Java version
  • hitori — required hitori version

For example:

{
  "depends": {
    "java": ">=25",
    "hitori": ">=2.0.0"
  }
}

Additional hitori modules can also be declared inside depends.

Version requirements support the following operators:

Operator Description
> Version must be greater than the specified version
= Version must exactly match the specified version
>= Version must be greater than or equal to the specified version

Examples:

{
  "depends": {
    "java": ">=25",
    "hitori": ">=2.0.0"
  }
}
{
  "depends": {
    "java": "=25",
    "hitori": ">2.0.0"
  }
}

A version requirement must include one of the supported operators.

12.1 Java Dependency

The java dependency specifies the required Java version.

This dependency is required and must always be present in the depends object.

"java": ">=25"

For example:

{
  "depends": {
    "java": ">=25",
    "hitori": ">=2.0.0"
  }
}

This declares that the module requires Java 25 or newer.

Other valid examples include:

"java": ">25"
"java": "=25"
"java": ">=25"

12.2 hitori Dependency

The hitori dependency specifies the required hitori version.

This dependency is required and must always be present in the depends object.

"hitori": ">=2.0.0"

For a module migrated to hitori 2.0.0, the recommended value is:

{
  "depends": {
    "java": ">=25",
    "hitori": ">=2.0.0"
  }
}

This ensures that the module requires hitori 2.0.0 or newer.

Other valid examples include:

"hitori": ">2.0.0"
"hitori": "=2.0.0"
"hitori": ">=2.0.0"

12.3 Module Dependencies

Other hitori modules can be declared using their module key.

For example:

"hitori:ux": {
  "type": "soft",
  "version": ">=1.0.0"
}

The dependency key is the target module's key:

hitori:ux

The dependency can specify:

  • type
  • version

The version field supports the same version operators:

>
=
>=

For example:

"hitori:ux": {
  "type": "soft",
  "version": ">=1.0.0"
}

Dependency Type

The type field defines the dependency type.
Possible values include: soft and hard.

Example:

"type": "soft"

Dependency Version

The version field specifies the required version:

"version": ">=1.0.0"

Supported operators are:

>   Greater than
=   Exactly equal to
>=  Greater than or equal to

13. Complete Metadata Example

A complete hitori 2.0.0 module metadata file can look like this:

{
  "key": "hitori:template",
  "version": "0.1.0-build13",
  "main": "su.hitori.template.TemplateModule",
  "packages": [
    "su.hitori.template"
  ],
  "description": "Template module for hitori framework",
  "authors": {
    "just_lofe": "https://github.com/justlofe",
    "StreamVersus": "https://github.com/StreamVersus"
  },
  "website": "https://github.com/modoruru/hitori-template",
  "bootstrap": "su.hitori.template.TemplateBootstrap",
  "build": {
    "ide": false,
    "commit": "fc68e151"
  },
  "depends": {
    "java": ">=25",
    "hitori": ">=2.0.0",
    "hitori:ux": {
      "type": "soft",
      "version": ">=1.0.0"
    }
  }
}

14. Minimal Metadata Example

You do not have to use every available field.

A minimal module can use only the required metadata:

{
  "key": "docs:example",
  "version": "1.0.0",
  "main": "docs.example.ExampleModule",
  "packages": [
    "docs.example"
  ],
  "depends": {
    "java": ">=25",
    "hitori": ">=2.0.0"
  }
}

Optional fields such as description, authors, website, bootstrap and build can be added when needed.

15. Quick Migration Example

Before

key=docs:example
version=1.0
description=Example module for hitori documentation
main=docs.example.ExampleModule
package=docs.example

After

{
  "key": "docs:example",
  "version": "1.0.0",
  "description": "Example module for hitori documentation",
  "main": "docs.example.ExampleModule",
  "packages": [
    "docs.example"
  ],
  "depends": {
    "java": ">=25",
    "hitori": ">=2.0.0"
  }
}

The main structural change is the transition from a flat properties file to a structured JSON document. hitori 2.0.0 also extends the metadata format with author information, project links, bootstrap classes, build information, and dependency declarations.

Clone this wiki locally