2025-03-10 · 3 min read

Adapter Metadata Fields That Matter

Metadata is the contract between the registry and the user. If the adapter card omits important fields, users have to guess whether the artifact is compatible, current, or worth downloading. A useful registry should make the metadata rich enough that the download decision is almost mechanical.

The core fields are straightforward. Every adapter should have a stable slug, a human-readable name, a version, a base model, a task type, a file format, a precision mode, a size, a checksum, and a visibility flag. Those fields let the catalog render a usable card and let API clients verify that they are looking at the right object.

{
  "slug": "watercolor-style-v2",
  "name": "Watercolor Style Adapter",
  "version": "2.0.1",
  "base_model": "stabilityai/stable-diffusion-xl-base-1.0",
  "task": "image",
  "format": "safetensors",
  "precision": "fp16",
  "size_bytes": 423857216,
  "license": "CreativeML OpenRAIL-M",
  "sha256": "a4f12c...",
  "public": true
}

The slug matters because it is the stable identifier in URLs and API calls. The name matters because humans read it. Version matters because users need to know whether a newer release is available. Base model matters because compatibility is not optional in practice. A LoRA trained for one family of models cannot be treated like a universal artifact.

Task type is useful because the registry may hold text, image, or multimodal adapters in the same catalog. That one field helps search, filtering, and UI rendering. It also lets the site use different sample sections or preview widgets for different artifact families.

Format and precision are especially important to serving and loading workflows. A user who sees GGUF expects a different runtime than a user who sees safetensors. A user who sees fp16 expects different memory usage than a user who sees int8. Hiding those fields creates confusion that could have been avoided in one glance.

License deserves a place on the card because it determines whether the artifact can be reused, redistributed, or modified. A registry that treats license as a footnote will eventually create user confusion. Users should not have to inspect the raw JSON just to know what they are allowed to do.

The size_bytes field may look unimportant, but it is one of the fastest ways to help users plan downloads and memory budgets. A 90 MB adapter and a 900 MB adapter are not the same operationally even if both are LoRAs. Size should be visible before the click.

Checksums are part of the contract too. A user downloading the same version twice should get the same bytes. If the file changes, the version should change. That is the simplest rule, and it makes support and caching much easier.

required = ["slug", "name", "version", "base_model", "task", "format", "precision", "size_bytes", "sha256"]

def validate(meta):
    missing = [k for k in required if k not in meta]
    if missing:
        raise ValueError(f"missing metadata: {missing}")

Extra fields can be useful, but only if they add real value. Good examples are tags, sample_prompts, sample_images, recommended_weight, rank, alpha, train_dataset, and updated_at. Bad fields are vague labels that only repeat what the card already says. The rule is simple: if the field changes how the user uses the artifact, keep it. If it does not, drop it.

It also helps to keep metadata typed and predictable. A field that is sometimes a string and sometimes a number is a quiet source of bugs. If size_bytes is always an integer, and public is always a boolean, the UI and API clients can trust the schema. Small registries benefit a lot from this kind of boring consistency.

Another useful field is compatibility, but only if it is specific. A list like ["transformers", "peft"] is better than a vague works on most systems. For image adapters, specify the model family, not just diffusion. The more exact the compatibility note, the fewer downloads are wasted on guesswork.

ModelForgeLab should expose these fields consistently across the UI and the API. The catalog, detail page, download endpoint, and job outputs should all agree on the same identifiers. That consistency is what makes a small registry feel polished instead of improvised.