minecraft-schemas 0.6.0

Structurally parse various JSON files used by Minecraft and Mojang

minecraft-schemas

English | 简体中文

A Python library that helps you structurally parse various JSON files used by Minecraft and Mojang.

Disclaimer: Although this project's name contains the word "minecraft", it is not endorsed by Mojang Studios or Microsoft. If you encounter any issues while using this project, please open an Issue in the project repository to report them; avoid reporting to the aforementioned entities.

Features

• Open Source: Released under the MulanPSL-2.0 license
• Easy Installation: Simply run pip install minecraft-schemas
• Broad Support: Supports multiple JSON file patterns, accompanied by comprehensive Schema definitions
• Easy to Use: Built-in converter APIs for parsing and constructing JSON files
• Type Safe: All public APIs and Schema definitions include type annotations
• High Performance: Converter APIs are based on cattrs, and Schema definitions use attrs
• Built-in Utilities for common needs:
  • Command-line argument/dependency filtering tools for client manifest files
  • Version query and filtering tools for version manifest files

Limitations

• This project is not, and does not intend to be, a Minecraft launcher; it focuses solely on file structure parsing and utility functions.
• The project's update pace may not keep up with the latest changes from Mojang and Minecraft.

Project Stability Statement

This project follows Semantic Versioning. Prior to version 1.0.0, to accelerate iteration speed, any API in this project may change in the next release without any deprecation process. Since the APIs are fully typed, your type checker and/or IDE can help you adapt to any API changes.

Breaking changes will be detailed in the changelog whenever possible.

For Users/Developers from minecraft-schemes

This project is a direct rename of minecraft-schemes. Since then, the project's structure and APIs have undergone significant changes.

As the project author, I do not have sufficient time and energy to design a migration plan. I sincerely apologize for any inconvenience this may cause.

minecraft-schemas

English | 简体中文

一个帮助你结构化解析多种 Minecraft 和 Mojang 使用的 JSON 文件的 Python 库。

免责声明：尽管本项目的名称带有“minecraft”这个单词，但此项目未受到来自 Mojang Studios 或微软公司的任何支持。若使用本项目时碰到任何问题，请在项目仓库开 Issue 反馈问题，避免向上述实体反馈。

特性

• 开源：基于 MulanPSL-2.0 许可证发布
• 易于安装：只需运行 pip install minecraft-schemas
• 支持广泛：支持多种 JSON 文件模式，附带详尽的 Schema 定义
• 易于使用：内置用于解析和构建 JSON 文件的转换器 API
• 类型安全：所有公开 API 和 Schema 定义均附带类型注解
• 高性能：转换器 API 基于 cattrs，Schema 定义使用 attrs
• 内置实用工具，针对常见需求：
  • 用于客户端清单文件的命令行参数/依赖库信息过滤工具
  • 用于版本清单文件的版本查询和过滤工具

限制

• 本项目不是且无意成为 Minecraft 启动器，仅聚焦于文件结构解析和辅助功能。
• 项目的更新速度可能无法跟上 Mojang 和 Minecraft 的最新变化。

项目稳定性声明

本项目遵循语义化版本控制。在 1.0.0 版本之前，为加快迭代速度，本项目的任何 API 都可能会在下次版本发布时产生变化，且没有弃用流程。由于 API 是完全类型化的，你的类型检查器和/或 IDE 可以帮助你适应任何 API 变更。

破坏性变更将尽可能在更新日志中详细说明。

面向来自 minecraft-schemes 的用户/开发者

本项目直接重命名自 minecraft-schemes。在此之后，本项目的结构和 API 都出现了重大变更。

作为项目作者，我没有充分的时间和精力设计迁移方案。对此带来的不便，我深表歉意。

History

This document records all notable changes to this project.

The format of this document follows the guidelines of Keep a Changelog.

This project adheres to Semantic Versioning.

Note: Prior to version 1.0.0, any API in this project may change with the next release due to rapid iteration, without a deprecation process. Breaking changes will be documented in detail in the changelog whenever possible.

[Unreleased] - TBD

[0.6.0] - 2026-05-16

Changes for type annotations of URL fields

Added

• Added new dependency yarl.
• Added (un-)structuring support for yarl.URL.

Changes

• [Breaking Change] Changed the type annotation for all Schema fields used for URLs from str to the dedicated type yarl.URL.
  • yarl.URL is a handy URL class for URL parsing and changing. We believe that using yarl.URL instead of str is more beneficial for structured parsing and processing of URL fields.
  • Starting from this version, tools that handle these fields as strings may encounter issues. If you are affected, please take action as soon as possible.

Others

Added

• Now all symbols exposed via __all__ in mcschemas.models.enums can be accessed directly through mcschemas. This change is to facilitate the direct use of utility functions in mcschemas.tools that require specific enumeration members as parameters.

[0.5.0] - 2026-05-11

Added

• Added support for schema definition and parsing of launcher_profiles.json
• Added convenience functions for querying version manifests, accessible via mcschemas.tools:
  • findLatestVersions(manifest_or_iterable: VersionManifest | Iterable[VersionManifestItem], /) -> _LatestVersions:
  • versionsFilter( manifest_or_iterable: VersionManifest | Iterable[VersionManifestItem], /, *version_filters: VersionFilterType, exclude: bool = False ) -> Iterator[VersionManifestItem]
  • filterVersionByAnyTypes(*version_type: VersionType | str) -> Callable[[VersionManifestItem], bool]
  • filterVersionByIdPattern( substring_or_pattern: str | re.Pattern[str], /, *, fullmatch: bool = False, case_insensitive: bool = True ) -> Callable[[VersionManifestItem], bool]
• Added the VersionType.UNOBFUSCATED enum value, representing the unobfuscated versions released in small numbers prior to game version 26.0
• Added the following destructuring and serialization functions, exported at the top-level package mcschemas:
  • build[T]( build_as: ConvertionDefinition[T], obj: T, /, *, converter: SchemaConverter = ..., force: bool = False ) -> Any
    • Destructuring function that converts obj into the object specified by build_as and returns it
    • It is allowed this kind of conversion only at build_as.isSupportsBuild is True
      • Pass force=True to forcefully allow the conversion, but it is strongly recommended for testing purposes only
  • dumps[T]( build_as: ConvertionDefinition[T], obj: T, /, *, converter: SchemaConverter = ..., force: bool = False, **underlying_kwargs: Any ) -> str
    • Serialization function that converts obj into the object specified by build_as, serializes it to a JSON string, and returns it
    • Other parameters are identical to build()
  • dump[T]( build_as: ConvertionDefinition[T], obj: T, writable: Writer[str], /, *, converter: SchemaConverter = ..., force: bool = False, **underlying_kwargs: Any ) -> None
    • Same as dumps(), but writes the serialization result directly to the file object writable
    • Other parameters are identical to build()

Changed

• [Breaking Change] Multiple class names have been renamed, partly to correct erroneous Entry usage: RuleOSEntry → RuleRequiredOSInfo, RuleEntry → Rule, ArgumentEntry → CommandLineArgument, Arguments → SeparatedCommandLineArguments, VersionManifestItem → ClientManifestFileInfo
• [Breaking Change] The type of the RuleRequiredOSInfo.version field has been changed from re.Pattern[str] to str, which affects the structuring process
• [Breaking Change] Split mojangjava into mojangjremanifest (Mojang JRE Manifest) and mojangjrefilesmanifest (Mojang JRE Files Manifest)
  • Similar to versionmanifest and clientmanifest, the two do not have a direct containment relationship in structure (the latter needs to be downloaded via a link provided by the former). Therefore, splitting mojangjava makes the project structure clearer and more consistent.

Removed

• [Breaking Change] Converter API: The mcschemas.parser module has been removed, replaced by the redesigned mcschemas.schemas module
  • The original mcschemas.parser module used an enum class to hold supported schemas, which required a large amount of @overload boilerplate code; otherwise, type checkers would be confused about the return type when encountering code like mcschemas.loads(s, mcschemas.Schemas.VERSION_MANIFEST) and could not infer it correctly. To simplify the implementation, mcschemas.parser has been removed.
  • Many symbols from the redesigned mcschemas.schemas module are exported at the top-level package mcschemas:
    • S_* constants, representing all supported file structures
    • deserialization function load、loads and structuring function parse
    • serialization function dump、dumps and destructuring function build
• [Breaking Change] Removed support for serialization and deserialization of re.Pattern
  • The only previous use of this feature was to directly convert $.arguments.<game|jvm>[].rules[].os.version from client.json into re.Pattern objects during structuring. Due to a change in design intent, this feature has been removed; now, re.fullmatch() should be used directly to check the operating system version.
• Removed the class-level structuring/destructuring logic from CommandLineArgument (formerly ArgumentEntry), which has been integrated into the converter API
• [Breaking Change] Removed the class-level custom structuring/destructing mechanism
  • The only previous use of this feature was to convert elements of $.arguments.<game|jvm>[] in client.json into the original ArgumentEntry objects during structuring. Since the conversion logic has been integrated into the converter API, this feature has been removed.
• [Breaking Change] LibraryDependencyMavenInfo class and LibraryDependencyInfo.splitLibraryName() method
• [Breaking Change] Removed the standalone rule-checking functions under tools.rules: isAllowed, isTotallyAllowed, isArgumentCanBeAppended, isLibraryDependencyCanBeAppended, replaced by the dedicated rule checker class RulesChecker
  • These functions would automatically infer information such as operating system identifiers, versions, and architectures at runtime. Using RulesChecker requires developers to provide this information themselves.
• [Breaking Change] Removed the Sequence interface implementation from AssetIndex and the Mapping interface implementation from VersionManifest

Fixed

• Fixed spelling errors in documentation and comments.

[0.4.2] - 2026-03-04

Added

• Typing: Added UnsignedUUIDType type alias to mark a uuid.UUID object should be serialized to a dash-free hexadecimal string.
  • Corresponding unstructure hook is registered in mcschemas.parser.converters.DedicatedConverter.configure().

Fixed

• Schema: Handled an edge case where availableProfiles is null in the response from remote server in Yggdrasil authentication response.
• Parsing: Fixed uuid.UUID (un-)structuring support in mcschemas.parser.converters.DedicatedConverter.configure().
• Parsing: Fixed the lacked type check for path-like objects in mcschemas.parser.loadVersionAttrsFromClientJar().

Changes

• Parsing: DedicatedConverter.configure() now accepts a keyword-only argument skip_preconf_configures to skip applying cattrs.preconf.json.configure_converter() on the existed converter passed in.
• Typing: All imports from typing module are now replaced with typing_extensions for better compatibility.
• Typing: Removed unnecessary @abstractmethod decorator from SupportsCustomStructure.__structure__() and SupportsCustomUnstructure.__unstructure__() methods.

[0.4.1.post1] - 2026-02-21

Removed

• Parsing: mcschemas.parser.createConverter() has been removed; it had previously been declared deprecated.
  • This function was removed at the code level in the previous release, but this was not mentioned in the previous release's changelog. Therefore, this release is specifically for correcting this oversight.

[0.4.1] - 2026-02-21

Added

• Schema: Supported to parse the response format of Yggdrasil APIs compatible with authlib-injector.
  • Corresponding model declarations at mcschemas.models.yggdrasil.
• Schema: Added the method filterVersions() for mcschemas.models.versionmanifest.VersionManifest to help filtering version entries by version type/ID.

Changes

• Project metadata: Overhauled and updated the README.
• Schema: Registered mcschemas.models.versionmanifest.VersionManifest as a collections.abc.MutableSequence by implementing required abstract methods. In short, mcschemas.models.versionmanifest.VersionManifest now is a mutable sequence.
  • Its __getitem__ method behaves a little differently from a regular sequence: when a string is passed in, it iterates through the internal list of version entries, searches for and returns the entry whose version ID exactly matches the string.
• Schema: Registered mcschemas.models.assetindex.AssetIndex as a collections.abc.MutableMapping by implementing required abstract methods. In short, mcschemas.models.assetindex.AssetIndex now is a mutable mapping.
  • Its __getitem__, _setitem__ and __delitem__ method behaves a little differently from a regular mapping: when a string is passed as the first argument after the self, it is first converted into apathlib.Path instance before being passed to the internal asset objects mapping.

[0.4.0] - 2026-02-09

This release focuses on renaming package and reorganizing the package internal structure.

Due to limited time and energy, I am unable to design a complete backward compatibility solution for this release. Sorry for the inconvenience.

Backwards-incompatible Changes

• Organizational: The package is renamed to mcschemas (formally mcschemes), and this project is renamed to minecraft-schemas (formally minecraft-schemes).
  • Since the word "scheme" [Merriam-Webster] does not accurately reflect the content and objectives of this project, using "schema" [Merriam-Webster] is clearly more appropriate.
• Organizational: Package structure changed:
  • All sub packages and modules including schema declarations are moved to mcschemas.models, detailed below:
    • mcschemes.assetindex -> mcschemas.models.assetindex
    • mcschemes.clientmanifest -> mcschemas.models.clientmanifest
    • mcschemes.mojangjava -> mcschemas.models.mojangjava
    • mcschemes.versionattrs -> mcschemas.models.versionattrs
    • mcschemes.versionmanifest -> mcschemas.models.versionmanifest
    • mcschemes.enums -> mcschemas.models.enums
    • mcschemes.specials -> mcschemas.models.specials
  • Parser submodule mcschemes.tools.parser is moved to mcschemas.parser.

Changes

• Project metadata: Fixed typos in this version history file and README: scheme -> schema.

[0.3.0.post1] - 2026-02-09

Deprecated:

• Announced the abandonment of the old package name mcschemes and the old project name minecraft-schemes.
  • The obsolete parts are kept in a separate branch 0.3.0-announced-deprecation.

[0.3.0] - 2026-01-31

Added

• Schema: Added support for parsing version information files (the version.json embedded within client.jar).
• Schema: Added parse support for index file of Mojang Java Runtimes, and file manifest of each java runtime.
• Parsing: Added a dedicated converter class in mcschemes.tools.parser.Converter.DedicatedConverter.
  • This is intended to replace the mcschemes.tools.parser.createConverter().

Backwards-incompatible Changes

• Schema: mcschemes.assetindex.AssetIndex now use the Path object from the standard library's pathlib module to represent file relative paths in asset index files.

  1. Previously, it will use str to represent file relative paths, so you can access information (e.g. hash, size) by the following way:

     from mcschemes.models.assetindex import AssetIndex
     
     asset_index: AssetIndex = ...  # Some operations to obtain the json and structure it to the AssetIndex instance
     file_info = asset_index.objects['icons/icon_128x128.png']
     
     [...]  # Do your operations for file_info
     

  2. Now, you need to use a pathlib.Path object as the key to access the corresponding information:

     from pathlib import Path
     from mcschemes.models.assetindex import AssetIndex
     
     asset_index: AssetIndex = ...  # Some operations to obtain the json and structure it to the AssetIndex instance
     file_info = asset_index.objects[Path('icons/icon_128x128.png')]
     
     [...]  # Do your operations for file_info
     

Deprecations

• Parsing: mcschemes.tools.parser.createConverter() is now marked as deprecated and will be removed in future versions.
  • Now pass a converter class based on cattrs.Converter to the kw-only argument converter_class is no longer determines the type of the returned dedicated converter instance.

Changes

• Project metadata: This version history file has been revised to conform to the format described in Keep a Changelog.
• Project metadata: Fully updated the README file:
  • Added a summary of the main features and benefits.
  • Added a summary of file structures supported by this library.
  • Usage example are now more useful and better represent typical use cases.
• Organizational: Reorganized the project structure:
  • mcschemes.tools.parser now is a package.
    • Sub-package mcschemes.tools.parser.converters is added to contains dedicated converters.
• Typing: typing-extensions was used instead of stdlib typing for better backward-compatibility for type annotation.
• Schema: Several changes for SHA-1 hexdigest container:
  • The comparison between two mcsehemes.specials.Sha1Sum instances now is based on the case-insensitive form of the hexdigest attribute of both.
  • The exception class mcschemes.specials.ChecksumMismatch is now exposed.
• Parsing: mcschemes.tools.parser.parse() now will check the second argument scheme in more robust way.

Fixed

• Tooling: Fixed a mistake when comparing the OS name in the function mcschemes.tools.rules.isAllow().

[0.2.0] - 2025-12-11

Added

• Project metadata: Added MANIFEST.in for setuptools.
• Schema: Added an SHA-1 hexdigest container type for sha1/hash fields (un-)structuring. Its definition can be found at: mcschemes.specials.Sha1Sum.
• Tooling: Added some tool functions to calculate a set of rules (iterable of mcschemes.clientmanifest.nodes.RuleEntry instances) means allow or disallow some operation, such as append an argument or download a library file.

Changes

• Project metadata: Declared build backend setuptools into pyproject.toml.
• Project metadata: According to PEP 561, an empty py.typed is added into the root directory of package.
• Project metadata: Corrected the date format for all tier-2 titles in this version history file.
• Organizational: Moved typings.py to the root directory of package.

[0.1.0.post1] - 2025-12-05

Changes

• Project metadata: Added project urls into pyproject.toml.
• Project metadata: Added disclaimer in README.md.

[0.1.0] - 2025-12-04

Added

The initial release.

变更日志

本文件记录了本项目所有值得注意的更改。

本文件的格式遵循《如何维护更新日志》 的规定（但使用中文）。

本项目遵循语义化版本控制。

注意：在 1.0.0 版本之前，为快速迭代，本项目的任何 API 都可能会在下次版本发布时产生变化，且没有弃用流程。破坏性变更将尽可能在更新日志中详细说明。

[未发布版本] - 待定

[0.6.0] - 2026-05-16

URL 字段的类型标注变更

新增

• 添加了 yarl 作为依赖项。
• 添加了对 yarl.URL 的结构化和去结构化支持。

变更

• [破坏性] 将所有 Schema 用于 URL 的字段的类型标注从 str 换成了专用类型 yarl.URL。
  • yarl.URL 是一个便捷的 URL 类型，用于 URL 解析和修改。我们认为使用 yarl.URL 取代 str 更有助于 URL 字段的结构化解析和处理。
  • 自此版本开始，将这些字段作为字符串处理的工具可能会遇到问题。如果你受到影响，请尽快采取措施。

其它

新增

• 现在 mcschemas.models.enums 所有通过 __all__ 公开的符号都可直接通过 mcschemas 访问。此项变更是为了方便直接使用 mcschemas.tools 中某些需要特定枚举的成员作为参数的工具函数。

[0.5.0] - 2026-05-11

新增

• 新增对 launcher_profiles.json 的 Schema 定义与解析和去结构化/序列化支持
• 新增版本清单查询便利函数，可通过 mcschemas.tools 访问：
  • findLatestVersions(manifest_or_iterable: VersionManifest | Iterable[VersionManifestItem], /) -> _LatestVersions:
  • versionsFilter( manifest_or_iterable: VersionManifest | Iterable[VersionManifestItem], /, *version_filters: VersionFilterType, exclude: bool = False ) -> Iterator[VersionManifestItem]
  • filterVersionByAnyTypes(*version_type: VersionType | str) -> Callable[[VersionManifestItem], bool]
  • filterVersionByIdPattern( substring_or_pattern: str | re.Pattern[str], /, *, fullmatch: bool = False, case_insensitive: bool = True ) -> Callable[[VersionManifestItem], bool]
• 新增 VersionType.UNOBFUSCATED 枚举值，代表游戏版本 26.0 之前少量释出的未混淆版本
• 新增下列去结构化函数和序列化函数，已在顶层包 mcschemas 导出：
  • build[T]( build_as: ConvertionDefinition[T], obj: T, /, *, converter: SchemaConverter = ..., force: bool = False ) -> Any
    • 去结构化函数，将 obj 转换为 build_as 规定的对象并返回
    • 只有 build_as.isSupportsBuild 为 True 时才允许此类转换，否则会引发 UnsupportedToBuild
      • 可以传入 force=True 强制允许转换，但强烈建议仅用于测试用途
  • dumps[T]( build_as: ConvertionDefinition[T], obj: T, /, *, converter: SchemaConverter = ..., force: bool = False **underlying_kwargs: Any ) -> str
    • 序列化函数，将 obj 转换为 build_as 规定的对象后序列化为 JSON 字符串并返回
    • 其他参数的含义与 build() 一致
  • dump[T]( build_as: ConvertionDefinition[T], obj: T, writable: Writer[str], /, *, converter: SchemaConverter = ..., force: bool = False **underlying_kwargs: Any ) -> None
    • 和 dumps() 作用相同，但直接将序列化结果写入文件对象 writable
    • 其他参数的含义与 build() 一致

变更

• [破坏性] 多个类名重命名，部分是为了修正错误的 Entry 用法：RuleOSEntry → RuleRequiredOSInfo、RuleEntry → Rule、ArgumentEntry → CommandLineArgument、Arguments → SeparatedCommandLineArguments、VersionManifestItem → ClientManifestFileInfo
• [破坏性] RuleRequiredOSInfo.version 字段的类型从 re.Pattern[str] 改为 str，这会影响结构化过程
• [破坏性] 将 mojangjava 拆分为 mojangjremanifest（Mojang JRE 清单）和 mojangjrefilesmanifest（Mojang JRE 文件清单）
  • 类似于 versionmanifest 和 clientmanifest，两者在结构上并没有直接包含的关系（后者需要通过前者提供的链接下载得到）。故将 mojangjava 拆分后项目结构更清晰、更具有一致性。

已移除

• [破坏性] 转换器 API：mcschemas.parser 模块已被移除，使用重新设计的 mcschemas.schemas 模块取而代之
  • 原始的 mcschemas.parser 模块使用一个枚举类容纳支持的 Schema，这需要大量 @overload 重复代码，否则类型检查工具在碰到形如 mcschemas.loads(s, mcschemas.Schemas.VERSION_MANIFEST) 的代码时会对返回值的类型感到困惑，无法正确推断。为简化实现，移除了 mcschemas.parser。
  • 重新设计的 mcschemas.schemas 模块中的大量符号已在顶层包 mcschemas 导出：
    • S_* 常量，代表所有支持的文件结构
    • 反序列化函数 load、loads 和结构化函数 parse
    • 序列化函数 dump、dumps 和去结构化函数 build
• [破坏性] 移除了 re.Pattern 的序列化与反序列化支持
  • 该功能先前的唯一用途是在结构化期间将 client.json 的 $.arguments.<game|jvm>[].rules[].os.version 直接转换为 re.Pattern 对象。由于设计意图发生变化，该功能被移除，现在应直接使用 re.fullmatch() 检查操作系统版本。
• 移除了 CommandLineArgument（原 ArgumentEntry）的在类级定义的结构化/去结构化逻辑，其已被整合进转换器 API
• [破坏性] 移除了类级自定义结构化/去结构化机制
  • 该功能先前的唯一用途是在结构化期间将 client.json 的 $.arguments.<game|jvm>[] 的元素转换为原 ArgumentEntry 对象。由于转换逻辑被整合进转换器 API，该功能被移除。
• [破坏性] LibraryDependencyMavenInfo 类与 LibraryDependencyInfo.splitLibraryName() 方法
• [破坏性] 移除了 tools.rules 下的独立规则检查函数：isAllowed、isTotallyAllowed、isArgumentCanBeAppended、isLibraryDependencyCanBeAppended ，使用专门的规则检查器类 RulesChecker 取而代之
  • 这些函数在运行时会根据需要自行推断操作系统标识符、版本、架构等信息。使用 RulesChecker 则需要开发者自行提供这些信息。
• [破坏性] 移除了 AssetIndex 的 Sequence 接口实现与 VersionManifest 的 Mapping 接口实现

问题修复

• 修复了文档和注释中的拼写错误。