{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://brandkernel.ai/schema/v1.0.json",
  "title": "BrandKernel",
  "description": "A JSON Schema for machine-readable brand identity specifications for LLM inference-time processing. Design principle: minimal required core (meta, personality, voice) with explicit extension points. All other identity layers are optional to prevent ontology freezing at schema-definition time. Theoretical derivation: Burmann et al. (2021) identity-based brand management model; Halliday & Matthiessen (2014) interpersonal metafunction (metaframe); Hyland (2005) stance/engagement model and Martin & White (2005) Appraisal framework (voice layer operationalizations); Rosch (1978), Kelly (1955), Medin & Schaffer (1978). Full derivation: see companion paper.",
  "type": "object",
  "required": ["meta", "personality", "voice"],
  "additionalProperties": false,

  "properties": {

    "meta": {
      "description": "Administrative metadata. Required. Governs versioning, locale, and governance.",
      "type": "object",
      "required": ["brand_name", "schema_version", "language"],
      "additionalProperties": false,
      "properties": {
        "brand_name": {
          "type": "string",
          "description": "Official registered brand name."
        },
        "schema_version": {
          "type": "string",
          "description": "BrandKernel schema instance version (semantic versioning recommended).",
          "default": "1.0"
        },
        "created_date": {
          "type": "string",
          "format": "date",
          "description": "ISO 8601 date of schema instance creation."
        },
        "last_updated": {
          "type": "string",
          "format": "date",
          "description": "ISO 8601 date of last schema instance update."
        },
        "language": {
          "type": "string",
          "description": "BCP 47 primary language tag (e.g., en, de, en-US). Affects voice layer constraints."
        },
        "audience_primary": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["B2B", "B2C", "B2E", "D2C", "multi_stakeholder"]
          },
          "description": "Primary audience segment(s). Global constraint across all layers."
        },
        "governance_contact": {
          "type": "string",
          "description": "Person or role responsible for schema instance maintenance."
        },
        "notes": {
          "type": "string",
          "description": "Free-text notes on schema scope, known limitations, or deployment context."
        }
      }
    },

    "origin": {
      "description": "Markenherkunft — Brand Origin. Optional. Guiding question: Where do we come from? Historical, geographic, and cultural roots from which all other components derive credibility (Burmann et al., 2021, pp. 31–36).",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "founding_narrative": {
          "type": "string",
          "description": "Core founding or origin story in narrative form."
        },
        "geographic_roots": {
          "type": "string",
          "description": "Geographic or cultural location of brand origin."
        },
        "historical_milestones": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["year", "event"],
            "additionalProperties": false,
            "properties": {
              "year":         { "type": "integer" },
              "event":        { "type": "string" },
              "significance": { "type": "string" }
            }
          },
          "description": "Key events in brand evolution. Chronological order."
        },
        "heritage_concepts": {
          "type": "array",
          "items": { "$ref": "#/$defs/specification_primitive" },
          "description": "Meaning-laden origin concepts encoded as Specification Primitives."
        }
      }
    },

    "competencies": {
      "description": "Markenkompetenzen — Brand Competencies. Optional. Guiding question: What are our distinctive capabilities? Core capabilities and resources (Burmann et al., 2021, pp. 37–39). Component weighting is case-dependent (Burmann et al., 2021, pp. 46 f.).",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "core": {
          "type": "array",
          "items": { "$ref": "#/$defs/specification_primitive" },
          "description": "Core competency concepts. Each encoded as Specification Primitive."
        },
        "proof_points": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Concrete evidence that core competencies are real (certifications, measurable outcomes)."
        }
      }
    },

    "values": {
      "description": "Markenwerte — Brand Values. Optional. Guiding question: What do we believe? Normative guiding principles (Burmann et al., 2021, pp. 39–42). Note: schema encodes stated values; authentic enactment is not formalizable.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "guiding_principles": {
          "type": "array",
          "items": { "$ref": "#/$defs/specification_primitive" },
          "description": "Core value constructs. Each encoded as Specification Primitive."
        }
      }
    },

    "personality": {
      "description": "Markenpersönlichkeit — Brand Personality. Required. Guiding question: How does the brand express itself verbally and non-verbally? Determines the brand's verbal and non-verbal communication style (Burmann et al., 2021, p. 45). maxItems: 7 — constraint against trait inflation; Kelly (1955) Range Corollary: a finite, distinct construct set is more predictively valid than an exhaustive list.",
      "type": "object",
      "required": ["traits"],
      "additionalProperties": false,
      "properties": {
        "traits": {
          "type": "array",
          "items": { "$ref": "#/$defs/specification_primitive" },
          "minItems": 1,
          "maxItems": 7,
          "description": "Character traits that determine communication style. Each encoded as Specification Primitive."
        }
      }
    },

    "vision": {
      "description": "Markenvision — Brand Vision. Optional. Guiding question: Where are we going? Aspirational future state (Burmann et al., 2021, pp. 36–37).",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "aspiration":   { "type": "string", "description": "Aspirational future state description." },
        "horizon":      { "type": "string", "description": "Time horizon for vision (e.g., '2030', 'next decade')." },
        "direction":    { "$ref": "#/$defs/specification_primitive", "description": "Directional concept encoded as Specification Primitive." }
      }
    },

    "offerings": {
      "description": "Art der Markenleistungen — Brand Offerings. Optional. Guiding question: What do we offer? Product and service categories (Burmann et al., 2021, pp. 46–47).",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "categories": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Product or service category labels."
        },
        "positioning": {
          "$ref": "#/$defs/specification_primitive",
          "description": "Positioning concept encoded as Specification Primitive."
        }
      }
    },

    "voice": {
      "description": "Voice Layer — BrandKernel extension. Required. Formalizes the communicative dimension of Markenpersönlichkeit: the verbal and non-verbal communication style Burmann et al. (2021, p. 45) assigns to brand personality but leaves to practitioner translation. Grounded in Halliday & Matthiessen (2014) interpersonal metafunction; Hyland (2005) stance/engagement model (epistemic dimension) and Martin & White (2005) Appraisal framework (evaluative dimension) as operationalizations; Pennebaker (2011). Required fields: register, voice_exemplars, fallback.",
      "type": "object",
      "required": ["register", "voice_exemplars", "fallback"],
      "additionalProperties": false,
      "properties": {

        "register": {
          "type": "string",
          "description": "Overall register characterization (e.g., conversational-professional, plain-serious, technical-precise)."
        },

        "analyticity": {
          "type": "string",
          "description": "Degree and mode of analytical reasoning visible in text (e.g., claim-first, evidence-led, exploratory)."
        },

        "vocabulary_register": {
          "type": "string",
          "description": "Lexical register specification: vocabulary level and domain orientation (e.g., educated-general, technical-specialist, accessible-everyday, academic). Distinct from overall register: a technical subject can be treated in accessible vocabulary. Corresponds to Biber's (1988) lexical dimension of register variation."
        },

        "pronouns": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "preferred": { "type": "array", "items": { "type": "string" } },
            "avoided":   { "type": "array", "items": { "type": "string" } }
          },
          "description": "Pronoun preferences. Informs Hyland (2005) self-mention dimension."
        },

        "sentence_rhythm": {
          "type": "string",
          "description": "Sentence length distribution and structural pattern guidance."
        },

        "stance": {
          "type": "object",
          "additionalProperties": false,
          "description": "Hyland (2005) stance dimension: writer-oriented epistemic positioning in text. Encodes hedges (certainty_level), evidentiality (epistemic grounding mode), and attitude markers. Strictly writer-oriented — distinct from the reader-oriented engagement dimension.",
          "properties": {
            "certainty_level": {
              "type": "string",
              "enum": ["high", "moderate", "hedged"],
              "description": "Degree of epistemic commitment. high = boosters dominant; hedged = hedges dominant."
            },
            "evidentiality": {
              "type": "string",
              "description": "Mode of grounding claims: data-driven, experience-based, principle-based, narrative."
            },
            "attitude_markers": {
              "type": "string",
              "description": "How the brand signals affective stance toward its own content: neutral, enthusiastic, critical, cautious, committed."
            }
          }
        },

        "engagement": {
          "type": "object",
          "additionalProperties": false,
          "description": "Hyland (2005) engagement dimension: reader-oriented devices that construct relational presence in text. Parallel to stance (writer-oriented) but distinct: engagement encodes how the brand positions and addresses the reader.",
          "properties": {
            "reader_orientation": {
              "type": "string",
              "description": "How the brand positions the reader in the text: direct ('you'), inclusive ('we'), distanced ('one' / third-person)."
            },
            "interactivity_level": {
              "type": "string",
              "enum": ["high", "moderate", "low"],
              "description": "Degree to which the text actively draws the reader in through questions, shared knowledge appeals, and reader references. high = frequent reader address and rhetorical questions; low = expository mode."
            },
            "imperatives_use": {
              "type": "string",
              "enum": ["frequent", "occasional", "avoided"],
              "description": "Frequency of directives and imperatives — direct commands or invitations to the reader (e.g., 'Find yours:', 'Don't Buy This Jacket.')."
            }
          }
        },

        "rhetorical_strategy": {
          "type": "object",
          "additionalProperties": false,
          "description": "Argumentation architecture: how the brand structures claims, evidence, and counter-positions. A distinct style generator derived from epistemological stance (Abdulhai et al., 2026): argument pattern follows directly from conviction level and world view. Neither stance nor engagement captures this dimension.",
          "properties": {
            "argument_pattern": {
              "type": "string",
              "enum": ["claim-first", "evidence-first", "question-driven", "concession-led"],
              "description": "Primary argument structure: where the main claim appears relative to supporting evidence or reader address. claim-first: assert then justify; concession-led: acknowledge opposing view then assert."
            },
            "concession_style": {
              "type": "string",
              "enum": ["none", "minimal", "acknowledging", "leading"],
              "description": "How the brand handles opposing views or qualifications. none: no concessions; leading: concession as the opening rhetorical move before assertion."
            },
            "evidence_mode": {
              "type": "string",
              "description": "Preferred type of supporting evidence: concrete-specific, data-driven, anecdotal, principle-based, narrative."
            }
          }
        },

        "rhetorical_figures": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Specific rhetorical devices the brand employs (e.g., direct address, rhetorical question, concrete analogy, antithesis, understatement). See engagement for the structured Hyland engagement dimension; this field captures named devices beyond that taxonomy."
        },

        "anti_patterns": {
          "type": "array",
          "items": { "$ref": "#/$defs/anti_pattern" },
          "description": "Hyland (2005) stance boundary: constructions that suppress authorial presence. Named by positive form per contrastive logic of anti_definition. Each entry names the pattern, provides rationale, and optionally contrasts with a preferred alternative."
        },

        "systematic_exclusions": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Topical and argumentative frames the brand constitutively does not adopt. Distinct from anti_definition (concept-level semantic boundary) and anti_patterns (stylistic boundary). Captures communicative identity at the topic/frame level using contrastive-constructive formulation to avoid negation-induced rebound (Vrabcová et al., 2025)."
        },

        "voice_exemplars": {
          "type": "array",
          "items": { "$ref": "#/$defs/voice_exemplar" },
          "minItems": 1,
          "description": "Required. Annotated text samples. positive: target style anchor. negative: Specification Drift illustration for this brand. Empirical basis: concrete exemplars yield up to 23.5x higher stylistic fidelity vs. zero-shot (Wang et al., 2025)."
        },

        "fallback": {
          "$ref": "#/$defs/fallback_policy",
          "description": "Required. Interface error handling: declares model behavior when a task falls outside the range_of_convenience of the active specification."
        }
      }
    },

    "extensions": {
      "type": "object",
      "description": "Open extension block. Brand-specific metadata not covered by the core schema. No structural constraints. Use for deployment-specific, platform-specific, or experimental fields."
    }

  },

  "$defs": {

    "specification_primitive": {
      "description": "Specification Primitive: BrandKernel's foundational representation unit for interpretable brand concepts. Three constitutive semantic fields (definition, anti_definition, exemplar) plus identifier (label) and optional extensions. Theoretical grounding: Rosch (1978) prototype theory → definition field; Kelly (1955) bipolar constructs + Horn (1989) contrary opposition → anti_definition field; Medin & Schaffer (1978) exemplar theory → exemplar field.",
      "type": "object",
      "required": ["label", "definition", "anti_definition", "exemplar"],
      "additionalProperties": false,
      "properties": {
        "label": {
          "type": "string",
          "description": "Concept identifier. Not a semantic field — functions as a key for addressability."
        },
        "definition": {
          "type": "string",
          "description": "Prototypic characterization: what the concept typically looks like. Generic truth, not universal quantification (Hampton, 2006). Activates specific semantic clusters over generic adjective lists."
        },
        "anti_definition": {
          "type": "string",
          "description": "Contrastive semantic boundary: what the concept is not, formulated as a contrary (not a contradictory) per Horn (1989). Enables model orientation toward the correct semantic region. MUST be formulated constructively ('assertive without being combative'), not prohibitively ('not arrogant'), to avoid negation-induced reinstatement (Zhou et al., 2026; Mann et al., 2025)."
        },
        "exemplar": {
          "type": "string",
          "description": "Concrete communicative instance. Anchors the concept below the level of verbal description. Cognitively constitutive, not illustrative (Medin & Schaffer, 1978). Activates target style mechanistically through in-context learning (Wang et al., 2025)."
        },
        "counter_exemplar": {
          "type": "string",
          "description": "Optional. Negative instance: a text that violates this concept. Sharpens the anti_definition boundary through demonstration."
        },
        "range_of_convenience": {
          "type": "string",
          "description": "Optional. Scope limiter: contexts where this construct applies. Kelly (1955) Range Corollary. Use only where over-generalization risk is non-trivial and scope is not contextually evident."
        },
        "weight": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Optional. Relative salience weight (0–1) within its layer. Operationalizes Burmann et al. (2021, pp. 46 f.): component weighting can only be determined case-by-case."
        }
      }
    },

    "anti_pattern": {
      "description": "A voice anti-pattern entry. Named by its positive form (what the construction is), not as prohibition, per contrastive logic of the Specification Primitive anti_definition field.",
      "type": "object",
      "required": ["pattern", "rationale"],
      "additionalProperties": false,
      "properties": {
        "pattern": {
          "type": "string",
          "description": "Name of the stylistic pattern to avoid (positive form, e.g., 'nominalization of active commitments')."
        },
        "rationale": {
          "type": "string",
          "description": "Why this pattern undermines the brand's voice specification."
        },
        "example": {
          "type": "string",
          "description": "Optional. Contrast pair: DON'T / DO — showing the pattern and its preferred alternative."
        }
      }
    },

    "voice_exemplar": {
      "description": "Annotated voice text sample. Polarity enables both target-style anchoring (positive) and Specification Drift illustration (negative) within a single schema instance.",
      "type": "object",
      "required": ["text", "polarity", "context"],
      "additionalProperties": false,
      "properties": {
        "text":       { "type": "string", "description": "The exemplar text." },
        "polarity":   { "type": "string", "enum": ["positive", "negative"], "description": "positive: on-brand target. negative: Specification Drift illustration." },
        "context":    { "type": "string", "description": "Publication context or content type of this text." },
        "annotation": { "type": "string", "description": "Explanatory note on the voice features this exemplar demonstrates or violates." }
      }
    },

    "fallback_policy": {
      "description": "Out-of-scope behavior specification. Defines model behavior when a given task falls outside the range_of_convenience of all active schema layers. Required in voice. A brand identity schema is an interface: like any interface, it must define behavior for inputs outside its specification (interface error handling).",
      "type": "object",
      "required": ["out_of_scope_policy", "default_register"],
      "additionalProperties": false,
      "properties": {
        "out_of_scope_policy": {
          "type": "string",
          "enum": ["apply_default_register", "escalate_to_human", "decline_generation"],
          "description": "Policy applied when task exceeds specification scope."
        },
        "default_register": {
          "type": "string",
          "description": "Register applied when out_of_scope_policy is apply_default_register."
        },
        "escalation_contexts": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Task types that always trigger escalate_to_human regardless of primary policy."
        }
      }
    }

  }
}