# Schema Changelog
## 0.3.19

Schema documentation:

- Added developer-facing `xs:annotation` / `xs:documentation` coverage across the bundled XSD set.
- Documented shared identity, canonical ID, checksum, provenance, reference, snapshot, validation, change-history, Quick Sheet, serialization, and media asset types.
- Documented Quick Item composition profiles, item category boundaries, enchanted/relic/supernatural/laboratory item overlays, and the first-class Weapon/Armor composition model.
- Documented root entity elements, domain payload types, and important enums for Character, Creature, Covenant, Laboratory, Item, Equipment, Book, Ability, Virtue/Flaw, rules-impact, and package-support schemas.

Versioning:

- Updated active XSD schema versions and shared serialization default from `0.3.18` to `0.3.19`.
- Kept `0.3.18` and older supported versions loadable for backward compatibility.
- No validation semantics, element names, order, occurrence rules, namespaces, gameplay automation, or mined package content changed in this documentation-only update.

## 0.3.18

Picture metadata support:

- Extended the existing `hf:mediaAssetType` pattern beyond Characters by adding optional repeatable `creatureArt`, `covenantArt`, `laboratoryArt`, and `itemArt` elements.
- Added the new art elements additively inside the corresponding structured data blocks without embedding binary media, base64 content, or copied image assets.
- Added validating examples that use placeholder relative media paths for Creature, Covenant, Laboratory, and Item records.

Versioning:

- Updated active XSD schema versions and shared serialization default from `0.3.17` to `0.3.18`.
- Kept `0.3.17` and older supported versions loadable for backward compatibility.

## 0.3.17

Quick Item schema groundwork:

- Added reusable shared Quick Item profile overlays in `foundry-common.xsd` for physical item details, arcane connections, casting tools/items, Hermetic enchantments, enchanted/supernatural effects, talismans, relics, other supernatural items, laboratory-linked item/features, shape/material bonuses, and flexible item stat blocks.
- Extended `entities/items.xsd` additively with `itemCategory` and optional profile overlays while preserving existing `itemKind`, `material`, `cost`, `load`, `availability`, `quantityNotes`, `effect`, `appearance`, and `sourceRulesText` records.
- Extended `entities/equipment.xsd` additively so `Equipment`, `Weapon`, and `Armor` records can carry the same optional overlays without collapsing Weapon or Armor into generic Item.
- Kept Book/Text as the separate existing `Book` entity. Quick Item v0.3.17 does not fold Books into generic Item and does not add Laboratory Text or Casting Tablet handling.
- Added schema examples for mundane items, arcane connections, casting tools/items, prepared/open devices with zero effects, invested devices with multiple effects, lesser enchantments, charged items, talismans, relics, other supernatural items, laboratory magic items/features, enchanted weapons, and supernatural armor.

Exclusions:

- Quick Item intentionally excludes Siege Engine / Large War Gear, Laboratory Text, Casting Tablet, and Raw Vis Stock in this pass.
- Laboratory Text and Casting Tablet remain future/system-specific work rather than Quick Item categories.

Versioning:

- Updated active XSD schema versions and shared serialization default from `0.3.16` to `0.3.17`.
- Kept `0.3.16` and older supported versions loadable for backward compatibility.

## 0.3.16

Quick Laboratory alpha schema/package preparation:

- Added optional structured Quick Laboratory data to `entities/laboratories.xsd`.
- Preserved existing simple `virtue` and `flaw` reference elements for older Laboratory XML.
- Added first-class storage for Laboratory name, manual/linked owner, manual/linked associated covenant, square feet, signed characteristics, refinement derivation notes, personality traits, Art/Activity specializations, selected package-backed or custom Laboratory Virtues and Flaws, enchanted item placeholders, and rich notes.
- Added shared `hf:positiveWholeNumberType`, `hf:dualFieldType`, Laboratory specialization enums, and Laboratory enchanted-item mode enum.
- Extended `entities/laboratory-features.xsd` with optional package-side parameter and specialization grant metadata while preserving the existing `modifier` rows used by the current core package.

Versioning:

- Updated active XSD schema versions and shared serialization default from `0.3.15` to `0.3.16`.
- Bumped the package cache index format from `8` to `9` so package-backed Laboratory Virtue/Flaw metadata is reindexed.

## 0.3.15

Quick Covenant alpha:

- Added optional structured Quick Covenant data to `entities/covenants.xsd`.
- Preserved existing Covenant reference elements: `charter`, `boon`, `hook`, `member`, `laboratory`, `visSource`, `situation`, `resourceProfile`, `ruleSection`, `procedure`, `organizationModel`, `financeModel`, and `loyaltyModel`.
- Added local selected-instance rows for Boons, Hooks, members, resources, library books, lab texts, casting tablets, vis sources/stocks, laboratories, finance lines, governance, and notes.
- Added optional `displayName` to structured Vis Stock rows so Quick Covenant can preserve user-facing stock names.
- Added `hf:covenantAccessiblePowerLevelEnum` for `Low`, `Medium`, `High`, and `Legendary` accessible power without changing the existing `hf:covenantPowerLevelEnum` used by resource profiles.

Versioning:

- Updated active XSD schema versions and shared serialization default from `0.3.14` to `0.3.15`.

## 0.3.14

Quick Creature combat:

- Added optional `hf:creatureCombatType` to `entities/creatures.xsd`.
- Added structured repeated Attack, Armor, and Weapon row types under `creatureData/combat`.
- Added rich-text `soak`, `fatigue`, and `woundPenalties` fields under creature combat.
- Kept combat stat fields flexible strings for source notation such as `+8`, `-4`, `0`, and `n/a`.

Versioning:

- Updated active XSD schema versions and shared serialization default from `0.3.13` to `0.3.14`.

## 0.3.13

Creature Power selected-row corrections:

- Changed selected Creature Power `mightCost` and `initiative` from non-negative integers to source-facing strings so values such as `variable`, `n/a`, `Qik-2`, and negative initiatives can round-trip.
- Added repeated `techniqueRequisite` and `formRequisite` entries to selected Creature Power rows.
- Added optional selected Creature Power `level`.
- Expanded shared power/spell R/D/T values with Range `Special` and Targets `Sight` and `Spectacle` for package-backed Creature Powers.

## 0.3.12

Quick Creature selected powers:

- Added `hf:creaturePowerLineType` to `entities/creatures.xsd`.
- Changed `creatureData/power` from a reference-only `hf:referenceType` entry to a structured selected-power row.
- A selected Creature Power now stores optional package `reference`, `name`, `mightCost`, `initiative`, `technique`, `form`, `range`, `duration`, `target`, and rich-text `effect`.
- Repeated `power` element document order is the manual order for selected creature powers.

Shared schema types:

- Added `hf:techniqueArtType` and `hf:formArtType` for controlled Ars Magica Arts selection.
- Added `hf:spellRangeType`, `hf:spellDurationType`, and `hf:spellTargetType` for controlled R/D/T values.
- Added `hf:nonNegativeWholeNumberType` for canonical non-negative UI-entered integer values such as Might Cost and Initiative.

Versioning:

- Updated active XSD schema versions and shared serialization default from `0.3.11` to `0.3.12`.


## 0.3.11

Formalized the Familiar reconciliation schema set version:

- Updated active XSD schema versions, shared serialization defaults, app serializer constants, validation metadata, and familiar regression fixtures from `0.3.10` to `0.3.11`.
- Preserved the v0.3.10 Familiar ownership model: Creature XML stores creature-side facts, while Magus Character XML stores familiar bond relationship data.
- No package/rules content or v0.3.10 armor package behavior changed.

## 0.3.10

Added magus-owned familiar bond reconciliation support:

- Added repeated `bondPower` entries to `hf:familiarBondType` in `entities/characters.xsd`.
- Kept `entities/creatures.xsd` creature-focused; familiar relationship values such as cords, bond qualities, bond powers, and relationship notes belong to the magus character's `magicProfile/familiarBond`.
- Retained existing optional familiar snapshot/stat fields under `hf:familiarBondType` for backwards compatibility with older character XML.
- Updated the shared serialization default schema version to `0.3.10`.

## 0.3.9

Added NPC/free-build support for character records:

- Added optional boolean `npc` to `hf:identityAndBackgroundType` in `entities/characters.xsd`.
- Documented that NPC/free-build mode reports character creation rule issues without blocking creation or save.
- Updated the shared serialization default schema version to `0.3.9`.

## 0.3.8

Added first-pass schema support for package-backed Spell Mastery as a specialized Ability:

- Added `hf:abilityKindType` with `Standard` and `SpellMastery` values to `entities/abilities.xsd`.
- Added optional `abilityKind`, `specialtyRequired`, and `spellMasteryDefinition` fields to Ability data.
- Kept Spell Mastery under the existing `Arcane` Ability category rather than adding a separate category.
- Added selected-character Spell Mastery data to `entities/characters.xsd`, including `masteredSpell`, selected `specialAbilities`, optional selected special ability references, snapshots, and notes.
- Updated the shared serialization default schema version to `0.3.8`.
- Added v0.3.8 Ability and Character fixtures for strict schema regression.

### v0.3.6 fix 1 — change history enum consistency

- Added `schemaUpgraded` to `changeActionEnum` so package/entity change-history records created during schema upgrades validate strictly against the schema.
- This is a compatibility bug fix for the v0.3.6 parameter-aware schema and does not introduce a new schema version number.

## 0.3.6

Added future-proof parameter-aware references for Virtue/Flaw eligibility and similar rules:

- Added `hf:parameterMatchOperatorEnum`, `hf:parameterMatchType`, and `hf:selectedParameterValueType` to `foundry-common.xsd`.
- Added optional `parameterMatch` children to `hf:entityReferenceType`, which means `hf:referenceType` usages such as `requires`, `prohibits`, `grants`, `source`, and `affectedContent` can constrain a referenced entity by selected parameter values.
- Added optional `stableId`, `canonicalId`, `ownerStableId`, and `scope` attributes to `hf:RulesParameterType`.
- Added `hf:RulesAllowedValueType` so parameter `allowedValue` entries may carry stable/canonical IDs and an entity type while remaining text-compatible with existing XML.
- Added optional top-level `parameter` definitions to Virtue/Flaw data for player-facing entity parameters such as Puissant Ability's chosen Ability or Student of a Realm's chosen Realm.
- Updated character `selectionParameter` entries to use `hf:selectedParameterValueType`, preserving the older key/value shape while adding durable parameter/value identifiers.
- Kept v0.3.5 entity XML backwards-compatible; existing simple `requires`, `prohibits`, and `rulesImpact` parameter records remain valid.

## 0.3.5

Expanded printable character-sheet support in `entities/characters.xsd`:

- Added structured `identityAndBackground` with saga name, setting, current year, associated covenant, character/player names, birth details, age, apparent age, Size, Confidence, biography fields, and background notes.
- Added optional `hermeticIdentity` for Order of Hermes characters, including House, Parens, Apprentice Covenant, Primus, Domus Magna, Wizard's Sigil, Covenant of Apprenticeship, and Hermetic notes.
- Added `characterArt` using a new shared `hf:mediaAssetType`.
- Added character-sheet sections for characteristics, Virtues/Flaws, Abilities, Arts, Experience, Decrepitude, Warping, Personality Traits, Reputations, Combat, Fatigue, Wounds, Inventory, Magic, derived values, and sheet notes.
- Added `experienceEvent` records to track XP gained during play.
- Added character inventory lines with quantity, unit load, total load, carried/equipped/stored state, total carried load, Burden, and Encumbrance.
- Added combat weapon lines that can reference weapons, shields, armor-derived stats, or unarmed combat modes.
- Added fatigue and wound profiles so Virtues/Flaws and Size can modify printed fatigue/wound bands without storing broad recovery/procedure rules as mined content.
- Added spell-known, raw vis, lab summary, longevity ritual, Twilight scars, and familiar bond sections needed by the standard character sheet.
- Retained legacy v0.2.x/v0.3.4 character Quick Sheet elements for migration.

Shared schema changes:

- Added reusable `hf:mediaAssetType` to `foundry-common.xsd` for character art and future media references.
- Updated serialization default schema version to 0.3.5.
- Version-aligned schema root attributes to 0.3.5 for this package.

Item/equipment changes:

- Confirmed and documented `load` as reusable equipment data in `entities/equipment.xsd`.
- Added optional `cost`, `load`, `availability`, `quantityNotes`, and `sourceRulesText` to `entities/items.xsd` for non-equipment items that still need physical/load metadata.

Fixtures:

- Added `examples/character-sheet-v0_3_5.example.xml`.
- Added `examples/character-basic-magus-v0_3_5.example.xml`.
- Added `examples/character-basic-companion-v0_3_5.example.xml`.
- Added `examples/character-basic-grog-v0_3_5.example.xml`.
- Updated the generic entity fixture serialization version to 0.3.5.

## 0.3.4

Added first-class Covenant schema support for the remaining staged Covenant material from Ars Magica Definitive Edition mining:

- `Covenant Rule Section`
- `Covenant Procedure`
- `Covenant Organization Model`
- `Covenant Finance Model`
- `Covenant Loyalty Model`

Added corresponding schemas under `entities/`:

- `entities/covenant-rule-sections.xsd`
- `entities/covenant-procedures.xsd`
- `entities/covenant-organization-models.xsd`
- `entities/covenant-finance-models.xsd`
- `entities/covenant-loyalty-models.xsd`

Updated `foundry-common.xsd` `entityTypeEnum` and `entities/covenants.xsd` references so covenant records can link these support entities directly.

## 0.3.3

Resolved schema gaps found during Ars Magica Definitive Edition mining:

- Added `Mythic Companion` and `Tainted` as top-level Virtue/Flaw categories in `entities/virtues-flaws.xsd`.
- Added `Covenant Situation` and `Covenant Resource Profile` to `foundry-common.xsd` `entityTypeEnum`.
- Added `entities/covenant-situations.xsd` for reusable covenant situation/template records built from Boons, Hooks, resource profiles, constraints, and Storyguide notes.
- Added `entities/covenant-resource-profiles.xsd` for reusable covenant resource packages and formulas such as Weak/Medium/Powerful base covenant resources.
- Updated `entities/covenants.xsd` so Covenant records can reference Covenant Situation and Covenant Resource Profile entities.
- Version-aligned `foundry-entity.xsd` and `foundry-package-manifest.xsd` to 0.3.3 for this schema set.

## 0.3.2

Added first-class mined-content schemas for Ars Magica PDF mining:

- Abilities
- Arts
- Virtues and Flaws
- Houses
- Mystery Initiation Components
- Covenant Boons and Hooks
- Laboratory Virtues and Flaws
- Creature Powers, Qualities, and Inferiorities
- Templates / presets
- Advancement Activities
- Tribunals
- House Rule Modules
- Equipment, Weapons, and Armor

Updated `foundry-common.xsd` `entityTypeEnum` with the corresponding entity types so these schemas can be referenced by base entity identity records, references, embedded snapshots, and package manifests.

## 0.3.2 layout correction

- Regenerated the addendum package to use the existing `entities/` schema subdirectory convention instead of the former incorrect subdirectory name.
- Updated documentation and validation report paths accordingly.
- Entity schema include paths remain `../foundry-entity.xsd`.
