You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Let modctl build populate provenance fields (authors, version, vendor, licenses) via Modelfile directives #702
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
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.
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).
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:
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.
Activity
pavelanni commentedon Oct 28, 2026
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 itlands in both." That is wrong.
manifestAnnotation()inpkg/backend/build.goreturns exactly one key:
createdAtgoes only into the config blob, viaBuildModelConfig. Nothing inpkg/backend/build/emits anyorg.opencontainers.image.*annotation. Sothere is no existing precedent for the mirroring I proposed — mapping
createdis 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
LABELadded alongside for annotations only, rather thanLABELreplacing them.The Docker
MAINTAINER→LABELprecedent does not transfer cleanly.Docker's
LABELwrites intoConfig.Labels, amap[string]string— aschemaless destination, which is exactly why a schemaless instruction suits
it.
ModelDescriptoris a typed struct with no labels map, so aLABEL-onlydesign would need a hardcoded table mapping
org.opencontainers.image.authorsonto
Descriptor.Authors, and any key outside that table would have nowherein 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, andWORKDIRas dedicatedinstructions — 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".
MAINTAINERwas deprecated becauseauthorwas a legacy untyped string.Two more observations from the code:
NAMEandFAMILYare already dedicated directives writing intoModelDescriptor. RoutingVERSIONthroughLABELwhileFAMILYstays adirective gives the Modelfile two mechanisms writing one struct, with no
principle separating them.
AuthorsandLicensesare[]string. Dedicated directives repeat andaccumulate, as
MODELandDOCalready do. The OCI annotationorg.opencontainers.image.authorsis a single free-form string, so aLABEL-only path forces a comma split that breaks on
"Anni, Pavel <panni@example.com>".It is also worth noting that
ModelDescriptormaps almost one-to-one ontoOCI's pre-defined annotation keys (
createdAt/created,docURL/documentation,sourceURL/source, plusauthors,version,revision,vendor,licenses,title,description). The struct readslike a deliberate typed mirror of the annotation set.
Concrete shape
Seven typed directives, each writing one config field and one annotation:
AUTHORSDescriptor.Authorsorg.opencontainers.image.authorsVERSIONDescriptor.Versionorg.opencontainers.image.versionVENDORDescriptor.Vendororg.opencontainers.image.vendorLICENSESDescriptor.Licensesorg.opencontainers.image.licensesTITLEDescriptor.Titleorg.opencontainers.image.titleDESCRIPTIONDescriptor.Descriptionorg.opencontainers.image.descriptionDOCURLDescriptor.DocURLorg.opencontainers.image.documentationPlus three annotations backfilled from fields modctl already records, with no
new directives:
createdAt→created,sourceURL→source,revision→revision. (createdAtstays omitted under--no-creation-time, which mustremain digest-reproducible.)
And
LABEL key=valuefor everything else, writing manifest annotationsonly, never the config blob — one writer per config field keeps the rules
explainable:
Consistency
Because the Modelfile is embedded verbatim in
org.cncf.modctl.modelfile, anydisagreement between a directive and a label is permanently visible inside the
artifact containing it. So
LABELwould reject any key owned by a typeddirective, whether or not that directive appears in the Modelfile:
Rejecting the key outright, rather than only on direct collision, avoids the
case where a version annotation is set while
config.versionstays empty —which would reintroduce the exact invisible-to-one-audience problem this issue
is about.
org.cncf.modctl.modelfilewould 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 shippingprovenance without fixing them would put modctl in a worse place than it is
now.
modctl attachwould strip the config fields while keeping theannotations.
pkg/backend/attach.gois a second call site ofBuildModelConfigthat rebuilds the config blob by hand-copying a fixed listof ten fields, then passes the source manifest's annotations through
untouched. After this feature,
buildfollowed byattachyields an artifactwhose 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
NoCreationTimenor the sourceCreatedAt, socreatedAtisre-minted via
time.Now(); onceorg.opencontainers.image.createdexists,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.
manifestAnnotationcallsmodelfile.Content(), which re-serializes from theparsed struct rather than embedding the file. It drops
DATASET(asserted onpurpose in
modelfile_test.go), would drop the new directives the same way,and unconditionally prepends
# Generated at <RFC 3339 now>. Since thatstring lands in a manifest annotation, the manifest digest churns
second-to-second even under
--no-creation-time, which today stabilises onlythe config blob.
My proposal is that
modctl buildannotate with the Modelfile's actual bytesfrom disk, keeping the regenerated form for
modctl modelfile generate, whichhas no source file. That makes the new directives appear with no extra work
and fixes the
--no-creation-timereproducibility gap as a side effect. Itdoes 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()inpkg/modelfile/parser/parser.gousesstrings.HasPrefix(line, cmd)with no word boundary, soDOCURL ...wouldprefix-match the existing
DOC. It fails safe today (thedefaultarm inparseCommandLinerejects it) but the error is confusing, and addingDOCURLmakes the hazard live. Happy to include a word-boundary fix.Node.AddAttribute/Node.GetAttributesalready exist inpkg/modelfile/parser/ast.go, documented as "such as key-value pairs", andare referenced by nothing outside tests.
LABELfits that hook with no ASTchanges.
GenerateConfig.Versioninpkg/config/modelfile/modelfile.gois declared,initialised to
"", and never read, becausemodctl modelfile generateregisters no
--versionflag. I'd add the full provenance flag set there —and deliberately no override flags on
modctl build, since a flag thatcould 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, sothe new fields would only appear under
--config. I'd add them asomitemptyfields.Scope I'd deliberately leave out: SPDX expression validation (needs a
license-list dependency) and annotation keys for
Name/Family(no standardOCI 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.