Skip to content

Let modctl build populate provenance fields (authors, version, vendor, licenses) via Modelfile directives #702

Open

Description

@pavelanni

Summary

model-spec v0.0.7 defines a full set of provenance fields in ModelDescriptor (specs-go/v1/config.go): authors, version, vendor, licenses, title, description, docURL. All are omitempty, but modctl build never populates them — buildconfig.Model (pkg/backend/build.go) has no corresponding fields, and the Modelfile directive set (NAME, ARCH, FAMILY, FORMAT, PARAMSIZE, PRECISION, QUANTIZATION, ...) has no way to express them.

Today the only way to attach this metadata is post-hoc manifest surgery with external OCI tooling (fetch manifest with oras, add org.opencontainers.image.* annotations, re-push), which changes the digest and bypasses the config blob entirely.

Proposal

  1. Modelfile directives for the provenance fields, e.g.:

    AUTHORS panni@example.com
    VERSION 1.0.0
    VENDOR Example Corp
    LICENSES Apache-2.0

    Alternatively (or additionally), a generic LABEL key=value directive analogous to Docker's LABEL → OCI annotations mapping, which container users already know.

  2. Plumb into both destinations:

    • the model-spec config blob (ModelDescriptor fields), for spec-aware consumers (runtimes, policy engines);
    • standard org.opencontainers.image.* manifest annotations in manifestAnnotation() (pkg/backend/build.go), for registry UIs and standard OCI tooling.

Why both destinations

Registries and tools like skopeo/oras surface manifest annotations, while model-spec consumers read the config blob. A field set in only one place is invisible to the other audience — createdAt is visible in registry UIs today precisely because it lands in both. Mirroring the provenance fields into the standard OCI annotation keys would make ModelPack artifacts immediately readable by the existing container ecosystem (and its compliance/signing tooling).

Happy to contribute a PR if the maintainers agree on the directive design (dedicated directives vs. generic LABEL).

Activity

  1. pavelanni commented on Oct 28, 2026

    @pavelanni
    Author

    I've read through the relevant code and would like to propose a concrete
    directive design before writing a PR. I'm also correcting one claim in my
    original issue.

    Correction to the issue text

    I wrote that createdAt "is visible in registry UIs today precisely because it
    lands in both." That is wrong. manifestAnnotation() in pkg/backend/build.go
    returns exactly one key:

    anno := map[string]string{
        annotationModelfile: string(modelfile.Content()),
    }

    createdAt goes only into the config blob, via BuildModelConfig. Nothing in
    pkg/backend/build/ emits any org.opencontainers.image.* annotation. So
    there is no existing precedent for the mirroring I proposed — mapping
    created is part of the work, not a pattern to follow.

    Proposal: dedicated directives, with LABEL as a complement

    The issue offered a fork between dedicated directives and a generic LABEL.
    Having looked at the code I'd argue for dedicated directives as the primary
    mechanism, with LABEL added alongside for annotations only
    , rather than
    LABEL replacing them.

    The Docker MAINTAINER → LABEL precedent does not transfer cleanly.
    Docker's LABEL writes into Config.Labels, a map[string]string — a
    schemaless destination, which is exactly why a schemaless instruction suits
    it. ModelDescriptor is a typed struct with no labels map, so a LABEL-only
    design would need a hardcoded table mapping org.opencontainers.image.authors
    onto Descriptor.Authors, and any key outside that table would have nowhere
    in the config blob to live. It would work for a blessed handful of keys and
    silently half-work for the rest.

    Docker also kept ENV, EXPOSE, USER, and WORKDIR as dedicated
    instructions — all backed by typed config fields. The principle looks less
    like "generic beats dedicated" and more like "typed field, dedicated
    instruction; free-form metadata, LABEL". MAINTAINER was deprecated because
    author was a legacy untyped string.

    Two more observations from the code:

    • NAME and FAMILY are already dedicated directives writing into
      ModelDescriptor. Routing VERSION through LABEL while FAMILY stays a
      directive gives the Modelfile two mechanisms writing one struct, with no
      principle separating them.
    • Authors and Licenses are []string. Dedicated directives repeat and
      accumulate, as MODEL and DOC already do. The OCI annotation
      org.opencontainers.image.authors is a single free-form string, so a
      LABEL-only path forces a comma split that breaks on
      "Anni, Pavel <panni@example.com>".

    It is also worth noting that ModelDescriptor maps almost one-to-one onto
    OCI's pre-defined annotation keys (createdAt/created,
    docURL/documentation, sourceURL/source, plus authors, version,
    revision, vendor, licenses, title, description). The struct reads
    like a deliberate typed mirror of the annotation set.

    Concrete shape

    Seven typed directives, each writing one config field and one annotation:

    Directive Config field Annotation Cardinality
    AUTHORS Descriptor.Authors org.opencontainers.image.authors repeatable
    VERSION Descriptor.Version org.opencontainers.image.version once
    VENDOR Descriptor.Vendor org.opencontainers.image.vendor once
    LICENSES Descriptor.Licenses org.opencontainers.image.licenses repeatable
    TITLE Descriptor.Title org.opencontainers.image.title once
    DESCRIPTION Descriptor.Description org.opencontainers.image.description once
    DOCURL Descriptor.DocURL org.opencontainers.image.documentation once

    Plus three annotations backfilled from fields modctl already records, with no
    new directives: createdAt → created, sourceURL → source, revision →
    revision. (createdAt stays omitted under --no-creation-time, which must
    remain digest-reproducible.)

    And LABEL key=value for everything else, writing manifest annotations
    only, never the config blob
    — one writer per config field keeps the rules
    explainable:

    AUTHORS "Pavel Anni <panni@example.com>"
    VERSION 1.0.0
    VENDOR "Example Corp"
    LICENSES Apache-2.0
    LABEL com.example.component=qwen3-inference

    Consistency

    Because the Modelfile is embedded verbatim in org.cncf.modctl.modelfile, any
    disagreement between a directive and a label is permanently visible inside the
    artifact containing it. So LABEL would reject any key owned by a typed
    directive, whether or not that directive appears in the Modelfile:

    LABEL key "org.opencontainers.image.version" is reserved on line 7;
    use the VERSION directive instead
    

    Rejecting the key outright, rather than only on direct collision, avoids the
    case where a version annotation is set while config.version stays empty —
    which would reintroduce the exact invisible-to-one-audience problem this issue
    is about. org.cncf.modctl.modelfile would be reserved on the same footing,
    since overwriting it corrupts the embedded Modelfile.

    Two bugs this feature would expose

    Both verified against main; neither is caused by the proposal, but shipping
    provenance without fixing them would put modctl in a worse place than it is
    now.

    modctl attach would strip the config fields while keeping the
    annotations.
    pkg/backend/attach.go is a second call site of
    BuildModelConfig that rebuilds the config blob by hand-copying a fixed list
    of ten fields, then passes the source manifest's annotations through
    untouched. After this feature, build followed by attach yields an artifact
    whose manifest advertises all seven provenance annotations while its config
    blob has lost all seven — precisely the split this issue is about. Attach also
    passes neither NoCreationTime nor the source CreatedAt, so createdAt is
    re-minted via time.Now(); once org.opencontainers.image.created exists,
    attach will emit a blob dated "now" beside an inherited annotation dated at
    original build time.

    I'd rather fix this structurally — derive the config from the source
    descriptor instead of field-by-field, and recompute the annotations from the
    rebuilt config — than extend the copy list, since the hand-copy is what made
    the bug possible. Happy to split it into its own PR if you'd prefer to review
    it separately.

    The Modelfile annotation is not reproducible, and is lossy.
    manifestAnnotation calls modelfile.Content(), which re-serializes from the
    parsed struct rather than embedding the file. It drops DATASET (asserted on
    purpose in modelfile_test.go), would drop the new directives the same way,
    and unconditionally prepends # Generated at <RFC 3339 now>. Since that
    string lands in a manifest annotation, the manifest digest churns
    second-to-second even under --no-creation-time, which today stabilises only
    the config blob.

    My proposal is that modctl build annotate with the Modelfile's actual bytes
    from disk, keeping the regenerated form for modctl modelfile generate, which
    has no source file. That makes the new directives appear with no extra work
    and fixes the --no-creation-time reproducibility gap as a side effect. It
    does change annotation content for existing users — they'd see their Modelfile
    as written, comments and all — so it's worth your explicit agreement.

    Smaller things noticed while reading

    • isCommand() in pkg/modelfile/parser/parser.go uses
      strings.HasPrefix(line, cmd) with no word boundary, so DOCURL ... would
      prefix-match the existing DOC. It fails safe today (the default arm in
      parseCommandLine rejects it) but the error is confusing, and adding
      DOCURL makes the hazard live. Happy to include a word-boundary fix.
    • Node.AddAttribute / Node.GetAttributes already exist in
      pkg/modelfile/parser/ast.go, documented as "such as key-value pairs", and
      are referenced by nothing outside tests. LABEL fits that hook with no AST
      changes.
    • GenerateConfig.Version in pkg/config/modelfile/modelfile.go is declared,
      initialised to "", and never read, because modctl modelfile generate
      registers no --version flag. I'd add the full provenance flag set there —
      and deliberately no override flags on modctl build, since a flag that
      could disagree with a directive needs a precedence rule I'd rather not
      introduce.
    • modctl inspect's default output is a hand-rolled eleven-field struct, so
      the new fields would only appear under --config. I'd add them as
      omitempty fields.

    Scope I'd deliberately leave out: SPDX expression validation (needs a
    license-list dependency) and annotation keys for Name/Family (no standard
    OCI key exists; that's a spec conversation).

    Does this shape look right to the maintainers? If so I'll open a draft PR
    against it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions