# Hallmark Data Model and Schema: The Complete 40-Field JSON Structure Explained

> Explore the complete Hallmark data model and schema. Understand the 40-field JSON structure used for design extraction and build steps. Learn how Hallmark uses a single structured-fields JSON schema as its source of truth.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: data-model
- Published: 2026-08-03

---

**Hallmark uses a single structured-fields JSON schema with approximately 40 fields defined in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md) as the source of truth for all design extraction and build steps.**

The **Hallmark data model** powers every stage of design analysis, from ingesting a screenshot or URL to generating a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) specification. According to the Nutlope/hallmark repository, this schema acts as a strict contract between the extraction engine, the diagnosis report, and the theme mapping layer.

## What Is the Hallmark Schema?

The Hallmark schema is a **flat JSON object** with nested sub-objects that completely describes a web page's visual DNA. It is stored in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) and serves as the **single source of truth** for downstream operations.

The schema is **mode-agnostic**: both image mode and URL mode populate the same fields, though URL mode fills "mode-conditional" fields with exact values extracted from fetched HTML/CSS.

### Schema Categories and Key Fields

| Category | Purpose | Example Fields |
|----------|---------|----------------|
| **Source** | Input provenance | `source_mode`, `source_url`, `refusal` |
| **Safety** | Security validation | `remote_safety` (sub-object with 7 flags) |
| **Macrostructure** | Page architecture | `macrostructure`, `hero`, `pitch`, `nav`, `footer` |
| **Typography** | Typeface roles and pairings | `display_role`, `body_face`, `pairing_logic` |
| **Colour** | Paper and accent values | `paper_band`, `accent_value`, `accent_footprint` |
| **Rhythm** | Visual density and motion | `density`, `asymmetry`, `motion_library` |
| **Provenance** | Audit trail for exports | `source_mode`-related flags |

## Complete Schema Structure (from [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md))

According to the Hallmark source code, the full schema definition resides in a fenced JSON code block within **[`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md)**:

```json
{
  "source_mode": "image | url",
  "source_url": "<the URL if source_mode=url, else null>",
  "source": "user-described | public-reference | unknown",
  "refusal": "ok | refused (paid-template) | soft-refusal (signature work)",
  "remote_safety": {
    "public_web_url": true,
    "scheme": "https | http | null",
    "ip_literal_detected": false,
    "redirects_checked": "true | false | fallback-requested | unknown | null",
    "fetched": ["html", "same-origin-css", "font-css"],
    "scripts_ignored": true,
    "prompt_injection_detected": false
  },
  "macrostructure": "<name from macrostructures.md>",
  "macrostructure_alt":"<second-closest, if it leans>",
  "hero": { "archetype":"H1‑Marquee …", "knobs":{ "<knob>":"<value>" } },
  "pitch":{ "archetype":"…", "knobs":{ … } },
  "nav":{ "archetype":"N1 …", "knobs":{ … } },
  "footer":{ "archetype":"Ft1 …", "knobs":{ … } },
  "display_role":"italic editorial serif | …",
  "display_face":"<exact font name in URL mode, else null>",
  "body_role":"neutral grotesque | …",
  "body_face":"<exact font name in URL mode, else null>",
  "label_role":"monospace | …",
  "label_face":"<exact font name in URL mode, else null>",
  "pairing_logic":"single family | two families | three families",
  "paper_band":"dark <30 | mid 30‑85 | light >85",
  "paper_value":"<exact oklch/hex/rgb in URL mode, else null>",
  "paper_hue":"warm | cool | neutral‑warm | neutral‑cool | chromatic‑<hue>",
  "accent_hue_band":"warm‑red | orange | yellow | green | teal | cyan‑blue | indigo | magenta | neutral",
  "accent_value":"<exact oklch/hex/rgb in URL mode, else null>",
  "accent_footprint":"small ≤5% | recurring 5‑15% | flood >15%",
  "density":"generous | medium | dense | unknown (URL mode)",
  "asymmetry":"centred | left‑biased | right‑biased | asymmetric‑grid | unknown (URL mode)",
  "treatments":["riso","grain‑overlay","…"],
  "reveal":"none | fade‑up | sweep | …",
  "motion_library":"framer‑motion | gsap | lottie | lenis | motion | none",
  "anti_patterns":["bouncy hover","transition‑all","…"]
}

```

All fields are **required** unless explicitly marked `"null"` or `"unknown (URL mode)"`.

## Mode-Conditional Field Behavior

The Hallmark schema handles two input modes with unified field names:

- **Image mode**: Populates descriptive bands (`paper_band`, `display_role`) with qualitative values like `"light >85"` or `"italic editorial serif"`. Mode-conditional fields return `null`.

- **URL mode**: Fills exact-value fields (`paper_value`, `display_face`) with precise data extracted from fetched CSS—e.g., `"oklch(96% 0.01 90)"` or `"Inter"`.

This design ensures **schema stability** across extraction methods while allowing precise reconstruction when source code is available.

## Practical Schema Usage

### Building a Schema Manually for Testing

```js
// example-schema.js
const hallmarkSchema = {
  source_mode: "url",
  source_url: "https://example.com",
  source: "public-reference",
  refusal: "ok",
  remote_safety: {
    public_web_url: true,
    scheme: "https",
    ip_literal_detected: false,
    redirects_checked: "true",
    fetched: ["html", "same-origin-css", "font-css"],
    scripts_ignored: true,
    prompt_injection_detected: false
  },
  macrostructure: "Split Studio",
  macrostructure_alt: null,
  hero: { archetype: "H2‑Split", knobs: { ratio: "6/6", right: "proof", divider: "hairline" } },
  nav: { archetype: "N1‑Standard", knobs: {} },
  footer: { archetype: "Ft3‑Index", knobs: { columns: "4" } },
  display_role: "italic editorial serif",
  display_face: "Inter",
  body_role: "neutral grotesque",
  body_face: "Inter",
  label_role: "monospace",
  label_face: null,
  pairing_logic: "two families",
  paper_band: "light >85",
  paper_value: "oklch(96% 0.01 90)",
  paper_hue: "warm",
  accent_hue_band: "neutral",
  accent_value: "#000000",
  accent_footprint: "small ≤5%",
  density: "generous",
  asymmetry: "centred",
  treatments: [],
  reveal: "none",
  motion_library: "framer-motion",
  anti_patterns: []
};

console.log(JSON.stringify(hallmarkSchema, null, 2));

```

### Generating [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) from Schema Data

```js
import fs from "fs";

function generateDesignMD(schema) {
  const header = `/* Hallmark · macrostructure: ${schema.macrostructure} · theme: studied-DNA */\n`;
  const system = `## System\n- Display: ${schema.display_role} (${schema.display_face || "candidate"})\n- Body: ${schema.body_role} (${schema.body_face || "candidate"})\n`;

  const tokens = `## Tokens\n- Paper: ${schema.paper_value || schema.paper_band}\n- Accent: ${schema.accent_value || schema.accent_hue_band}\n`;

  const provenance = `## Provenance\n- Source mode: ${schema.source_mode}\n- URL: ${schema.source_url || "N/A"}\n`;

  return header + system + tokens + provenance;
}

fs.writeFileSync("design.md", generateDesignMD(hallmarkSchema));

```

## Schema-Dependent Reference Files

The Hallmark data model references several canonical files in `skills/hallmark/references/`:

| File | Schema Role |
|------|-------------|
| [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md) | **Primary schema definition** and extraction protocol |
| [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) | 21 named macro-structures for the `macrostructure` field |
| [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md) | Archetype definitions and knob tables for `hero`, `nav`, `pitch`, `footer` |
| [`design-md.md`](https://github.com/Nutlope/hallmark/blob/main/design-md.md) | Output format specification for serialized schemas |
| [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) | Overview of the `hallmark study` verb and schema workflow |

## How the Schema Powers Hallmark's Pipeline

Once populated, the schema drives three downstream operations:

1. **Diagnosis report**: Compares extracted values against reference databases in [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) and [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md).

2. **Theme mapping**: Suggests named themes (e.g., *Studio*, *Midnight*, *Riso*) based on field combinations. This mapping is **non-binding**—users may override.

3. **[`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) export**: Serializes the complete schema to a portable, version-controlled specification.

## Summary

- **Hallmark's data model** is a **40-field JSON schema** defined in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md).
- The schema serves as a **strict contract** between extraction, analysis, and build phases.
- **Mode-conditional fields** handle both image and URL inputs with unified structure.
- Reference files ([`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md), [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md)) provide controlled vocabularies for key fields.
- The schema enables **reproducible design systems** through [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) export.

## Frequently Asked Questions

### What file contains the complete Hallmark schema definition?

The complete schema is defined in **[`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md)** within a fenced JSON code block. This file specifies all ~40 fields, their valid values, and extraction rules for both image and URL modes.

### Is the Hallmark schema the same for screenshots and URLs?

Yes. Both modes use **identical field names**, but URL mode populates "mode-conditional" fields (`*_value`, `*_face`, `motion_library`) with exact extracted data while image mode leaves these as `null` and relies on descriptive bands.

### What is the `remote_safety` sub-object used for?

The `remote_safety` field contains **7 security flags** that validate URL inputs: `public_web_url`, `scheme`, `ip_literal_detected`, `redirects_checked`, `fetched`, `scripts_ignored`, and `prompt_injection_detected`. This enables safe, auditable extraction from remote sources.

### How does Hallmark map schema data to themes?

After schema population, Hallmark suggests named themes (e.g., *Studio*, *Midnight*) based on field combinations. However, theme mapping is **advisory only**—the schema remains the authoritative source and users may override suggestions.