Validation package metadata

Every validation package starts with YAML frontmatter. The script language determines how that YAML is enclosed; the metadata contract is otherwise the same. New canonical frontmatter carries the immutable v1 schema URI. Readers select that schema entirely offline; the URI is not fetched during parsing.

The versioned schema is also served directly by AVPR at /schemas/v1/validation-package-frontmatter.schema.json.

F# frontmatter

An F# script may place frontmatter in a multiline comment:

(*
---
$schema: "https://avpr.nfdi4plants.org/schemas/v1/validation-package-frontmatter.schema.json"
Name: my-package
MajorVersion: 1
MinorVersion: 0
PatchVersion: 0
Summary: My package validates an ARC.
Description: A longer explanation of the validation behavior.
---
*)

Binding it to the literal PACKAGE_METADATA is recommended so the script can reuse the same metadata:

let [<Literal>] PACKAGE_METADATA = """(*
---
$schema: "https://avpr.nfdi4plants.org/schemas/v1/validation-package-frontmatter.schema.json"
Name: my-package
MajorVersion: 1
MinorVersion: 0
PatchVersion: 0
Summary: My package validates an ARC.
Description: A longer explanation of the validation behavior.
---
*)"""

For example, a script using the portable model and codecs can extract it without repeating the package identity:

#r "nuget: ValidationPackage.Model"
#r "nuget: ValidationPackage.Codecs"

open ValidationPackage.Codecs

let metadata =
    ValidationPackageYaml.extractOrFail
        FrontmatterLanguage.FSharp
        PACKAGE_METADATA

The binding must be at the start of the file and use the exact name PACKAGE_METADATA with the [<Literal>] attribute.

Python frontmatter

A Python script uses its initial triple-quoted string:

"""
---
$schema: "https://avpr.nfdi4plants.org/schemas/v1/validation-package-frontmatter.schema.json"
Name: my-package
MajorVersion: 1
MinorVersion: 0
PatchVersion: 0
Summary: My package validates an ARC.
Description: A longer explanation of the validation behavior.
---
"""

Binding the string is likewise recommended:

PACKAGE_METADATA = """
---
$schema: "https://avpr.nfdi4plants.org/schemas/v1/validation-package-frontmatter.schema.json"
Name: my-package
MajorVersion: 1
MinorVersion: 0
PatchVersion: 0
Summary: My package validates an ARC.
Description: A longer explanation of the validation behavior.
---
"""

Schema and editor association

The schema describes the extracted YAML metadata mapping, not the surrounding F# multiline comment or Python string. Frontmatter extraction and package publication checks remain separate stages: a schema-valid mapping can still fail language-specific extraction, filename/identity checks, or publication policy.

YAML-aware editors can validate an extracted mapping by associating the versioned AVPR route with a local YAML file. For example, VS Code with the YAML extension accepts:

{
  "yaml.schemas": {
    "https://avpr.nfdi4plants.org/schemas/v1/validation-package-frontmatter.schema.json": [
      "**/*.validation-package.yml"
    ]
  }
}

Copy only the YAML between the frontmatter delimiters into a matching *.validation-package.yml editor buffer. Canonical mappings also retain their top-level $schema field when copied.

Mandatory fields

Canonical documents also require $schema with the exact value shown above. The codec retains an explicit schema-less legacy reader for immutable published packages, but canonical writers always emit $schema first.

Optional fields

Publish defaults to false; collection and string fields default to empty values. Omitting Inputs is backwards compatible and produces an empty input collection.

Nested objects

Author

Ontology annotation

Complete example

$schema: "https://avpr.nfdi4plants.org/schemas/v1/validation-package-frontmatter.schema.json"
Name: my-package
MajorVersion: 1
MinorVersion: 0
PatchVersion: 0
Summary: My package validates an ARC.
Description: |
  A longer explanation of the package and its validation behavior.
Publish: true
Authors:
  - FullName: Jane Doe
    Email: jane@example.org
    Affiliation: Example University
    AffiliationLink: https://example.org
Tags:
  - Name: validation
  - Name: my-tag
    TermSourceREF: my-ontology
    TermAccessionNumber: MO:12345
ReleaseNotes: Initial release.
CQCHookEndpoint: https://example.org/cqc-hook
Inputs:
  - id: verbose
    type: boolean?
    label: Verbose logging
    doc: Enable verbose logging
    inputBinding:
      prefix: --verbose

Wrap this YAML using the F# or Python form above. See submitting a validation package for naming, versioning, and publication rules. The standalone Draft 2020-12 schema is shipped at schemas/validation-package-frontmatter.schema.json in every ValidationPackage.Codecs package and is byte-identical to the versioned AVPR schema route.