Self-Describing Models with Embedded Metadata (LoRAs, Checkpoints & Embeddings in .safetensors)

Proposal: sd.artifact.v1 – Self-Describing Models with Embedded Metadata

(LoRAs, Checkpoints & Embeddings in .safetensors)

Core Principle (Non-Negotiable)

All useful metadata lives inside the .safetensors file itself — no sidecar JSON files, no external dependencies, no fragile platform pages.

If someone downloads/copies/renames/archives/shares the file offline, all important context survives forever.

Why This Matters

Most of us have dozens or hundreds of LoRAs, checkpoints and embeddings where we eventually forget:

• What the trigger words are

• Recommended weight / best samplers / VAE

• Whether it's SFW or NSFW

• How good it is supposed to be (quality tags)

• What an embedding actually does

• Any known issues or tips

When Civitai pages get updated, deleted or links die — the file becomes a mystery again.

External model cards are nice, but fragile. Embedded metadata is permanent.

Core Proposal

Embed one clean, versioned, optional JSON block in the safetensors header:

"sd.artifact.v1": "{\"name\":\"My LoRA\",\"type\":\"lora\", ...}"

(Stored as a stringified JSON — standard safetensors practice)

Supported Artifact Types

"type": "checkpoint" | "lora" | "embedding"

Essential Fields (minimum to make the model understandable)

{  
  "name": "Epic Fantasy Character",
  "type": "lora",
  "base_model": "Pony Diffusion V6 XL",
  "triggers": ["epicfantasy", "in epicfantasy style"]
}

Highly Recommended Fields (solve most daily pain points)

{
  "description": "High-detail fantasy warrior with glowing runes",
  "tags": ["fantasy", "character", "male", "detailed armor", "epic"],
  "nsfw": "sfw",                     // "sfw" | "suggestive" | "nsfw" | "explicit" | "none"
  "example": {
    "prompt": "epicfantasy, warrior standing on mountain, dramatic lighting, masterpiece",
    "negative_prompt": "blurry, low quality, deformed",
    "recommended_weight": 0.75
  },
  "vae": "sdxl_vae.safetensors",     // or ["sdxl_vae", "kl-f8-anime2"]
  "samplers": ["euler a", "dpm++ 2m karras"]
}

Very Useful Extras (great for power users & long-term use)

{
  "comments": [
    "Best at 25–40 steps",
    "Avoid with realistic bases – skin artifacts"
  ],
  "quality_tags": ["score_9", "score_8_up", "masterpiece"],
  "civitai": {
    "modelId": "123456",
    "versionId": "789012"
  },
  "training": {
    "resolution": "1024x1024",
    "steps": 12000,
    "rank": 64,
    "alpha": 32
  },
  "usage": {
    "recommended_weight_range": "0.6–0.9",
    "known_issues": ["hands may need fix above 0.95"]
  }
}

Embeddings-Specific Fields (they benefit the most from this!)

{
  "embedding_type": "positive",      // "positive" | "negative" | "style" | "concept"
  "tokenizer": "clip-vit-large-patch14",
  "embedding_dim": 768
}

Embedded Preview Image (strongly encouraged – solves instant identification)

"assets": {
  "preview_image": {
    "mime": "image/jpeg",
    "size": "512x512",
    "encoding": "base64",
    "data": "...base64 string here..."
  }
}

Kohya-ss Compatibility (Very Important)

Kohya-ss training metadata uses ss_* keys (ss_tag_frequency, ss_network_dim, ss_learning_rate, etc.).

Your "sd.artifact.v1" can live peacefully side-by-side with all existing ss_* keys — no conflict at all.

Recommended coexistence approach:

1. Keep all Kohya ss_* keys as they are (for A1111 / ComfyUI extensions that read them)

2. Add your structured data as one stringified JSON key:

"sd.artifact.v1": "{\"name\":\"...\",\"triggers\":[...],...}"

3. Optional: mirror the most important fields using ssmd_* style for current tools:

• "ssmd_name": "My Beautiful LoRA"

• "ssmd_description": "..."

• "ssmd_trigger_words": "trig1, trig2"

• "ssmd_nsfw_level": "explicit"

→ Kohya tools continue working normally

→ Future/new tools can prefer the clean "sd.artifact.v1" namespace

→ Gradual, zero-breakage adoption

How to Add It Today (already possible)

• Browser tools: https://lorainfo.tools/ or https://xypher7.github.io/lora-metadata-viewer/

• Python: safetensors library (very easy batch scripts)

• ComfyUI: SaveCheckpointWithMetadata node

• CLI: stInfo or similar utilities

Compatibility & Safety

• Purely additive — never touches tensor weights

• Ignored by tools that don't understand it

• Safe to add / remove / strip

• 100% optional — use exactly what you want

License

Public domain (CC0) — adopt, modify, extend, fork freely.

Final Thought

A model that only makes sense when connected to a website is already fragile.

Let's give every file the context it deserves — permanently.

What do you think, creators & users?

Would you start adding this to your uploads?

Missing any important field?

Any suggestions for improvement?

Let's discuss and make orphaned models a thing of the past! 🚀