Expand description
Validation of DuckDB community extension description.yml files.
Every extension submitted to the DuckDB community extensions repository must
include a description.yml metadata file. This module provides:
DescriptionYml— a structured representation of the file’s required fieldsparse_description_yml— parse from adescription.ymlstringvalidate_description_yml_str— validate adescription.ymlstring end-to-end
§description.yml Format
extension:
name: my_ext
description: A one-line description of the extension.
version: 0.1.0
language: Rust
build: cargo
license: MIT
requires_toolchains: rust;python3 # optional
excluded_platforms: "wasm_mvp;wasm_eh;wasm_threads" # optional
maintainers:
- Jane Doe
repo:
github: janedoe/duckdb-my-ext
ref: 4f1c2e9a7b3d5c8e1f0a2b4c6d8e0f1a3b5c7d9e§Required vs Optional Fields
| Field | Required | Rules |
|---|---|---|
extension.name | Yes | Must pass validate_extension_name |
extension.description | Yes | Non-empty |
extension.version | No | If present, must pass validate_extension_version; the community build never reads it |
extension.language | Yes | Must be "Rust" for Rust extensions |
extension.build | Yes | Must be "cargo" for Rust extensions |
extension.license | Yes | Non-empty (licence accepted); a value validate_spdx_license rejects is a warning in DescriptionYml::warnings |
extension.requires_toolchains | No | Semi-colon list; validate_rust_extension additionally requires "rust" |
extension.excluded_platforms | No | Must pass validate_excluded_platforms_str; a YAML list is accepted with a warning, and so is a group name such as wasm, which excludes nothing |
extension.opt_in_platforms | No | Platforms to build that are not built by default; the parser warns about any name the build would ignore |
extension.maintainers | Yes | At least one maintainer |
repo.github | Yes | owner/repo, in the characters GitHub allows — not a URL |
repo.ref | Yes | Non-empty git ref; anything but a commit hash is a warning |
repo.ref_next | No | The revision built against DuckDB main before a release |
repo.variegata, repo.andium | No | Non-empty if present: the revisions built for DuckDB v1.5.6 and v1.4.5 instead of ref; anything but a commit hash is a warning |
Any other repo: key is a warning (the community build ignores it). The
whole file — docs: included — must be YAML that PyYAML’s
yaml.safe_load accepts, since that is the community build’s first step;
see parse_description_yml for what is checked.
§Reference
- https://duckdb.org/community_extensions/documentation
- https://duckdb.org/community_extensions/development
§Example
use quack_rs::validate::description_yml::validate_description_yml_str;
let yml = r#"
extension:
name: my_ext
description: Fast analytics for DuckDB.
version: 0.1.0
language: Rust
build: cargo
license: MIT
requires_toolchains: rust;python3
maintainers:
- Jane Doe
repo:
github: janedoe/duckdb-my-ext
ref: 4f1c2e9a7b3d5c8e1f0a2b4c6d8e0f1a3b5c7d9e
"#;
assert!(validate_description_yml_str(yml).is_ok());Structs§
- Description
Yml - A validated representation of a
DuckDBcommunity extensiondescription.yml.
Functions§
- parse_
description_ yml - Parses and validates a
description.ymlstring. - validate_
description_ yml_ str - Validates a
description.ymlstring and returnsOk(())if it passes all checks. - validate_
rust_ extension - Validates that a Rust extension’s
description.ymlfollows pure-Rust best practices.