Skip to main content

parse_description_yml

Function parse_description_yml 

Source
pub fn parse_description_yml(
    content: &str,
) -> Result<DescriptionYml, ExtensionError>
Expand description

Parses and validates a description.yml string.

Returns a validated DescriptionYml if all required fields are present and correct.

§What is validated

  • extension.name — must pass validate_community_extension_name: well formed, and not a DuckDB alias (s3) or core extension name (json)
  • extension.description — non-empty
  • extension.version — optional; if present, must pass validate_extension_version
  • extension.language, extension.build — non-empty
  • extension.license — non-empty (licence: is accepted, with a warning). A value validate_spdx_license does not accept is a warning, not an error: the community build does not read the field, and published extensions use BSL 1.1, GPL-3.0 and free text
  • extension.excluded_platforms — if present, must pass validate_excluded_platforms_str; a YAML list is validated too, and warned about. A platform group name (wasm, windows, …) passes, with a warning: the community build compares exact platform names, so a group excludes nothing
  • extension.opt_in_platforms — if present, a warning for each name the build would ignore: a group, an unknown name, or a platform that is built without opting in
  • extension.maintainers — at least one name
  • repo.github — owner/repo, in the characters GitHub allows (not a URL)
  • repo.ref — non-empty; anything but a commit hash is a warning
  • repo.variegata, repo.andium — if present, non-empty (the revisions the community build checks out for DuckDB v1.5.6 and v1.4.5); anything but a commit hash is a warning
  • any other repo: key but ref_next and canonical_name is a warning: the community build ignores it
  • no key may appear twice in a section

§Errors

Returns ExtensionError on the first validation failure with a descriptive message.

§Note on parsing

quack-rs has no YAML dependency, so this reads description.yml with a small hand-written reader, held to what PyYAML’s yaml.safe_load — the first thing the community build runs on the file — accepts: a file it refuses is refused here too, docs: and every other section included. That covers the plain-scalar rules (no : , no leading @, `, % or - , no tab), tabs, control characters, block-scalar headers and indentation, quoted and flow scalars across lines, anchors and aliases, and dates PyYAML cannot construct. Checked against the 395 published descriptors (all accepted, every field as PyYAML reads it but block scalars, which are trimmed) and 41,423 mutants of them (none accepted that PyYAML refuses).

It is stricter than PyYAML in a few places no published file needs: quoted or repeated keys in extension: and repo:, and anywhere tags, explicit ? key entries, directives, anchors on keys and a second document.

§Example

use quack_rs::validate::description_yml::parse_description_yml;

let yml = "extension:
  name: my_ext
  description: My extension.
  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
";

let desc = parse_description_yml(yml).unwrap();
assert_eq!(desc.name, "my_ext");
assert_eq!(desc.version.as_deref(), Some("0.1.0"));
assert_eq!(desc.license, "MIT");
assert_eq!(desc.github, "janedoe/duckdb-my-ext");
assert_eq!(desc.maintainers, vec!["Jane Doe"]);
assert!(desc.warnings.is_empty());