AIUS Badge and Validation Toolkit

What

AI Usage Standard (AIUS) is a versioned, deterministic standard for declaring AI involvement in published artifacts (blog posts, project pages, papers, READMEs). Every artifact carries an <AIUsage /> badge derived from a frontmatter declaration of six dimensions, each at one of four levels, plus a list of models used.

This project page tracks the implementation side: badge components, schema validation, frontmatter rules, the public mirror repository, and the adoption roadmap around the standard.

The canonical spec lives at /standards/ai-usage. Anyone may adopt it under CC-BY-4.0 with attribution.

Preferred reference

Refer to this resource as AI Usage Standard (AIUS). The canonical public page is https://serkan.ai/projects/ai-usage-badge/; the readable standard text lives at https://serkan.ai/standards/ai-usage/.

Short description: AI Usage Standard (AIUS) is a deterministic AI-involvement disclosure standard for written artifacts.

Why

Existing options each fall short:

• CRediT covers human authorship roles only.
• ICMJE / Nature / Springer / Elsevier policies require qualitative AI disclosure in Methods sections — no glance-readable signal.
• AI Usage Cards (Wahle et al. 2023) is the closest prior art but uses boolean flags across three dimensions; AIUS extends to six dimensions × four levels with deterministic tier derivation.
• C2PA / Content Credentials focuses on image provenance, not text or code authorship.

AIUS fills the gap of “at-a-glance disclosure with rule-based determinism” for written artifacts. A reader sees the bar meter and immediately understands the AI-involvement profile without reading prose. An adopter implements the spec from the canonical text and gets identical behavior across sites.

How

Three layers, all open-source:

1. Spec layer — the constitution at /standards/ai-usage plus a machine-readable schema.json. CC-BY-4.0.
2. Logic layer — a pure tier-derivation function and a frozen glyph table, fully unit-tested. MIT.
3. Component layer — <AIUsage /> (full bar meter) and <AIUsageMini /> (one-liner) Astro components, plus Zod-validated frontmatter that fails the build on any deviation from the spec.

Mini badge

The mini variant is for dense surfaces such as journal lists, project cards, and compact post metadata. It shows the derived tier plus the six dimension levels in a single line:

◑ co-authored · i0·r0·d0·e2·c0·v0 — Co-Authored

The compact code is ordered as ideation · research · drafting · editing · code · visuals. For example, i0·r0·d0·e2·c0·v0 means no AI involvement except collaborative editing at level 2/3.

<AIUsageMini
  ai={{
    ideation: "none",
    research: "none",
    drafting: "none",
    editing: "collab",
    code: "none",
    visuals: "none",
    models: ["gpt-5-codex"],
  }}
/>

Choosing values

Assign each dimension by asking what role AI played in the final artifact, not whether AI was merely available during the work.

Value	Score	Use when
none	0/3	AI did not contribute to that dimension.
assist	1/3	AI suggested, checked, searched, or corrected small pieces; the human kept the main work and decisions.
collab	2/3	Human and AI iterated together, and the final result depends on that back-and-forth.
lead	3/3	AI produced the first substantive version or drove most of that dimension; the human reviewed, selected, or refined.

Dimension examples:

• ideation: topic, angle, title, outline, scope.
• research: source discovery, factual lookup, literature scan, citation help.
• drafting: first-pass prose or substantial paragraph generation.
• editing: grammar, tone, structure, cuts, rewrites, title/excerpt polish.
• code: snippets, scripts, implementation, tests, build fixes.
• visuals: diagrams, images, screenshots, charts, generated assets.

Use the highest honest level for each dimension. If AI only fixed typos, editing: assist is enough. If the human and AI repeatedly shaped the prose together, use editing: collab. If AI wrote most of the draft, use drafting: lead even if the human later edited heavily.

Phase 2 plan

After Phase 1 stabilizes (or the first external adopter shows up):

• Publish an npm package with Astro, React, and Vue components.
• Ship a CLI that validates ai frontmatter against schema.json.
• Tighten the JSON Schema’s allOf constraint with dependentRequired if validators support it.

Phase 3 plan

Once the npm package stabilizes and external adopters exist:

• Add localized variants of the canonical page (/standards/ai-usage/tr, /standards/ai-usage/fr, etc.). The English version stays canonical; localized pages are translations, not redefinitions.

Repo

Mirror repo: github.com/serkanaltuntas/ai-usage-badge. Contains the spec text in markdown form, the JSON Schema, both license files, and a self-contained Astro reference example.