Skip to main content

Module description_yml

Module description_yml 

Source
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:

§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

FieldRequiredRules
extension.nameYesMust pass validate_extension_name
extension.descriptionYesNon-empty
extension.versionNoIf present, must pass validate_extension_version; the community build never reads it
extension.languageYesMust be "Rust" for Rust extensions
extension.buildYesMust be "cargo" for Rust extensions
extension.licenseYesNon-empty (licence accepted); a value validate_spdx_license rejects is a warning in DescriptionYml::warnings
extension.requires_toolchainsNoSemi-colon list; validate_rust_extension additionally requires "rust"
extension.excluded_platformsNoMust 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_platformsNoPlatforms to build that are not built by default; the parser warns about any name the build would ignore
extension.maintainersYesAt least one maintainer
repo.githubYesowner/repo, in the characters GitHub allows — not a URL
repo.refYesNon-empty git ref; anything but a commit hash is a warning
repo.ref_nextNoThe revision built against DuckDB main before a release
repo.variegata, repo.andiumNoNon-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

§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§

DescriptionYml
A validated representation of a DuckDB community extension description.yml.

Functions§

parse_description_yml
Parses and validates a description.yml string.
validate_description_yml_str
Validates a description.yml string and returns Ok(()) if it passes all checks.
validate_rust_extension
Validates that a Rust extension’s description.yml follows pure-Rust best practices.