GKC Wizard Documentation
Purpose: Document how GKC Wizards consume Entity Profiles to generate interactive, multi-step curation workflows for creating and editing entities across Wikidata, Wikimedia Commons, and other Global Knowledge Commons platforms.
Overview
GKC Wizards are profile-driven user interfaces that transform declarative YAML entity definitions into guided, step-by-step data entry workflows. Every aspect of the wizard—field labels, validation rules, input widgets, help text, and workflow organization—derives directly from the profile with zero hardcoded entity logic.
Key Characteristics:
- Fully declarative: All UI behavior comes from profile metadata
- Multi-entity capable: Can curate primary entity + related entities in single session
- Real-time validation: Feedback on every field blur, guided by profile constraints
- Graceful degradation: Follows Wikidata/Wikipedia philosophy—incomplete entities can be saved; enhancement happens iteratively
Wizard Architecture
Profile → UI Generation Pipeline
┌──────────────────────────────────────────────────────────┐
│ SpiritSafe Profile YAML (TribalGovernmentUS) │
│ - Entity metadata (labels, descriptions, aliases) │
│ - Statements with datatypes, constraints, guidance │
│ - Profile graph (links to OfficeHeldByHeadOfState) │
│ - SPARQL-driven allowed-items lists │
└──────────────────┬──────────────────────────────────────-┘
│ Load & parse
↓
┌──────────────────────────────────────────────────────────┐
│ GKC Spirit Safe Module │
│ - Parse YAML → Pydantic EntityProfile model │
│ - Discover profile graph (related profiles) │
│ - Hydrate SPARQL allowed-items caches │
└──────────────────┬──────────────────────────────────────-┘
│ Provide profile + graph
↓
┌──────────────────────────────────────────────────────────┐
│ Wizard Loader │
│ - Create GKC Curation Packet with placeholders │
│ - Primary entity: ent-001-primary │
│ - Related entities: ent-002-office, etc. │
└──────────────────┬──────────────────────────────────────-┘
│ Pass packet + profile to renderer
↓
┌──────────────────────────────────────────────────────────┐
│ Wizard Step Renderers │
│ - Step 1: Plan (from metadata.description) │
│ - Step 2: Identification (labels/desc/aliases) │
│ - Step 3: Statements (statement definitions) │
│ - Step 4: Sitelinks (sitelinks config) │
│ - Step 5: Review (completeness check) │
└──────────────────┬──────────────────────────────────────-┘
│ User interaction & data entry
↓
┌──────────────────────────────────────────────────────────┐
│ Curation Packet (updated with user data) │
│ - Saved to disk (draft) or shipped to Wikidata │
└──────────────────────────────────────────────────────────┘
The 5-Step Wizard Structure
Every wizard follows a consistent 5-step progression designed to match curator mental models:
Step 1: Plan of Action
Purpose: Orient curator to what they're about to create and what information they'll need
Content derived from profile:
- Entity type:
metadata.nameand profile top-levelnamefield - Description:
metadata.description(long form) orprofile.description(short form) - Required elements: Count of required statements, required languages
- Secondary entities: Lists profiles discovered via profile graph (e.g., "You may also create: Office Held by Head of State")
- Time estimate: Auto-calculated from statement count and complexity
- Preparation guidance: Any profile-level
preparation_guidancefield (future enhancement)
UI Elements:
- Entity type badge/icon
- Summary statistics ("5 required statements, 8 optional statements")
- List of related entity types that may need creation
- "Start curation" button to proceed to Step 2
Example Display:
┌─────────────────────────────────────────────────────────┐
│ Create Tribal Government (US) │
├─────────────────────────────────────────────────────────┤
│ Federally recognized Native American tribes in the │
│ United States. Comprehensive profile for documenting │
│ tribal nomenclature, federal recognition, governmental │
│ structure, and cross-platform links. │
│ │
│ REQUIRED ELEMENTS │
│ • Labels and descriptions in English │
│ • 3 required statements │
│ • At least 1 sitelink │
│ │
│ YOU MAY ALSO CREATE │
│ • Office Held by Head of State (optional) │
│ │
│ ESTIMATED TIME: 10-15 minutes │
│ │
│ [Start Curation →] │
└─────────────────────────────────────────────────────────┘
Step 2: Basic Identification (Labels, Descriptions, Aliases)
Purpose: Collect multilingual metadata that identifies the entity
Content derived from profile:
- Languages supported: Discovered by scanning
labels,descriptions,aliasessections in profile - Required vs optional languages: Inferred from
required: truein profile (future: explicitlanguagessection) - Input prompts:
labels.input_prompt,descriptions.input_prompt(or defaults) - Guidance text:
labels.guidance,descriptions.guidance
UI Structure:
- Single-language profiles: Simple form (Label, Description, Aliases)
- Multi-language profiles: Tabbed interface (one tab per language)
Field-Specific Behavior:
| Field | Cardinality | Validation | Profile Source |
|---|---|---|---|
| Label | 1 per language (max) | Required if language is required; max length ~250 chars | labels.en.input_prompt, labels.en.guidance |
| Description | 1 per language (max) | Required if language is required; must be distinctive | descriptions.en.input_prompt, descriptions.en.guidance |
| Aliases | 0-many per language | Optional; no duplicates within language | aliases.en.input_prompt, aliases.en.guidance |
Validation:
- Real-time: On field blur, check length constraints and required status
- Cross-field: Ensure description doesn't duplicate label
- Pre-advancement: Validate all required languages have non-empty label + description
Example Display (Multi-Language):
┌─────────────────────────────────────────────────────────┐
│ Basic Identification [EN] [CHR] [NV] │
├─────────────────────────────────────────────────────────┤
│ ENGLISH (REQUIRED) │
│ │
│ Label * │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Cherokee Nation │ │
│ └─────────────────────────────────────────────────────┘ │
│ ℹ️ Use the name the tribe uses to refer to itself │
│ │
│ Description * │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Federally recognized Native American tribe in OK │ │
│ └─────────────────────────────────────────────────────┘ │
│ ℹ️ Short, distinctive description (not just a repeat │
│ of the label) │
│ │
│ Aliases (Alternative Names) │
│ • Cherokee ✕ │
│ • Cherokee Tribe ✕ │
│ [+ Add another alias] │
│ │
│ [← Back] [Continue →] │
└─────────────────────────────────────────────────────────┘
Step 3: Statements
Purpose: Collect all property-value assertions about the entity
Content derived from profile:
- Statement list:
profile.statements[]array (rendered in order) - For each statement:
- Label:
statement.label - Input prompt:
statement.input_promptorstatement.value.input_prompt - Guidance:
statement.guidance - Datatype:
statement.value.type→ determines widget - Constraints:
statement.constraints[]→ validation rules - Allowed items:
statement.value.allowed_items→ choice lists - Qualifiers:
statement.qualifiers[]→ nested inputs - References:
statement.references→ source collection
Statement Rendering Order:
Wizard renders statements in the exact order specified in profile YAML. Profile designers should order statements logically (e.g., classification statements first, then descriptive, then relationships).
Widget Selection by Datatype:
| Datatype | Widget | Behavior |
|---|---|---|
item |
QID text input OR autocomplete | If allowed_items present, show searchable dropdown; else free QID entry |
entity_profile |
QID input + "Create new" button | Always shows both "Select existing" and "Create new [profile]" options |
string |
Text input | Single-line for short strings; multi-line if max_length > 200 |
url |
URL input | Validates URL format; shows protocol dropdown (http/https) |
time |
Date picker | Precision auto-detected from input format (YYYY vs YYYY-MM vs YYYY-MM-DD) |
quantity |
Number input + unit selector | Unit field shown if unit_behavior != "none" |
monolingualtext |
Text input + language dropdown | Language choices from allowed_items SPARQL or fallback list |
commonsMedia |
File upload widget | Uploads to Wikimedia Commons (requires auth) |
globe-coordinate |
Map picker | Click map to set lat/lon; or manual entry |
Skip Functionality:
Every statement can be skipped via explicit "Skip this statement" button. Philosophy: curators can save incomplete entities and enhance later.
Multi-Value Statements:
If statement.max_count > 1 or max_count: null, show "Add another [statement label]" button after each value.
Qualifiers:
Rendered as nested form under statement value. Each qualifier follows same widget selection rules as statements.
References:
Behavior determined by statement.references.behavior:
editable: Show reference collection UI (itemlist from SPARQL or manual entry)auto_derive: System generates references automatically (e.g., from statement value URL)fixed: References pre-populated from profile; user cannot edit
Example Display:
┌─────────────────────────────────────────────────────────┐
│ Statements (3 of 8 completed) │
├─────────────────────────────────────────────────────────┤
│ Instance of (classification) * │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Q7840353 - federally recognized Native American... │ │
│ └─────────────────────────────────────────────────────┘ │
│ ℹ️ Fixed value: This entity is always classified as a │
│ federally recognized tribe. │
│ │
│ REFERENCES (required: 1+) │
│ • Federal Register notice: Vol. 87, No. 18 ✕ │
│ [+ Add reference] │
│ ─────────────────────────────────────────────────────── │
│ │
│ Office held by head of state │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Q999888 - Principal Chief of the Cherokee Nation │ │
│ └─────────────────────────────────────────────────────┘ │
│ [Select existing QID] [Create new office →] │
│ ℹ️ The executive leadership position (not the person). │
│ │
│ [Skip this statement] │
│ ─────────────────────────────────────────────────────── │
│ │
│ [← Back] [Continue →] │
└─────────────────────────────────────────────────────────┘
Step 4: Cross-Platform Links (Sitelinks)
Purpose: Link entity to Wikipedia articles and other sister projects
Content derived from profile:
- Supported languages:
profile.sitelinks.languages[] - Supported projects: Per language (e.g.,
en: [wikipedia, wikivoyage]) - Input mode: Language+project+title dropdowns (current) or URL-based (future)
- Validation: Uniqueness constraints (one sitelink per language+project across all Wikidata)
Current UI Pattern:
- Select language (dropdown)
- Select project (dropdown: wikipedia, wikivoyage, etc.)
- Enter article title (text input)
- Validate: Check if sitelink already exists in Wikidata for another item (conflict detection)
Future Enhancement: URL-Based Entry:
Enter Wikipedia or Wikimedia URL:
┌─────────────────────────────────────────────────────┐
│ https://en.wikipedia.org/wiki/Cherokee_Nation │
└─────────────────────────────────────────────────────┘
✓ URL validated • Article exists • No conflicts
Relationship type:
◉ Primary article (exclusively about this entity)
○ Shared article (discusses multiple entities)
○ Contextual mention (entity appears in broader topic)
Sitelink List Display:
┌─────────────────────────────────────────────────────────┐
│ Cross-Platform Links │
├─────────────────────────────────────────────────────────┤
│ WIKIPEDIA ARTICLES │
│ • English: Cherokee_Nation ✕ │
│ • Cherokee: ᎳᎫᎿ_ᎠᏰᎲ ✕ │
│ │
│ [+ Add sitelink] │
│ │
│ [← Back] [Continue →] │
└─────────────────────────────────────────────────────────┘
Step 5: Review & Validate
Purpose: Show curator a complete summary of what will be created/edited; identify gaps
Content displayed:
- Entity overview: Labels, descriptions (all languages)
- Completeness score: "7 of 10 required elements complete (70%)"
- Statements summary: Grouped by completed vs skipped
- Secondary entities: If multi-entity packet, show related entities to be created
- Validation warnings: Missing required fields, constraint violations
Completeness Calculation:
required_fields = 2 (base for label+desc)
+ num_required_statements
+ (2 * num_required_languages)
completed_fields = count(non_empty required labels)
+ count(non_empty required descriptions)
+ count(statements with at least one value)
progress_pct = (completed_fields / required_fields) * 100
Action Options:
- Save Draft: Serialize packet to disk for later editing (allows incomplete entities)
- Ship to Wikidata: Validate completeness; if warnings present, show confirmation dialog
- Edit [Section]: Jump back to specific step to fix issues
Example Display:
┌─────────────────────────────────────────────────────────┐
│ Review: Cherokee Nation │
├─────────────────────────────────────────────────────────┤
│ COMPLETENESS: 8 of 10 required elements (80%) │
│ ████████████████░░░░ Ready to ship │
│ │
│ IDENTIFICATION ✓ │
│ • English label: Cherokee Nation │
│ • English description: Federally recognized tribe... │
│ • 2 aliases │
│ │
│ STATEMENTS │
│ ✓ Instance of: Q7840353 │
│ ✓ Office held by head of state: Q999888 │
│ ✓ Member count: 380,000 (2023) │
│ ⚠️ Headquarters location: MISSING │
│ ⚠️ Official website: MISSING │
│ │
│ CROSS-PLATFORM LINKS ✓ │
│ • enwiki: Cherokee_Nation │
│ │
│ RELATED ENTITIES TO BE CREATED │
│ • Office: Principal Chief of the Cherokee Nation │
│ │
│ ⚠️ WARNINGS │
│ • Headquarters location is highly recommended │
│ • Official website helps verify tribal government │
│ │
│ [← Back] [Save Draft] [Ship to Wikidata →] │
└─────────────────────────────────────────────────────────┘
Multi-Entity Curation Sessions
When a profile references other profiles via entity_profile statements, wizard creates a multi-entity curation packet and allows curator to work on multiple entities in one session.
Profile Graph Loading
Example: User launches wizard with TribalGovernmentUS profile
- Wizard loads
TribalGovernmentUSprofile - Discovers
office_held_by_head_of_statestatement withentity_profile: OfficeHeldByHeadOfState - Loads
OfficeHeldByHeadOfStateprofile - Creates packet with two entity placeholders:
ent-001-primary(TribalGovernmentUS)ent-002-office(OfficeHeldByHeadOfState)
UI Presentation Strategy
Sidebar Entity Navigator:
┌──────────────┬──────────────────────────────────────────┐
│ ENTITIES │ │
│ │ Step 2: Basic Identification │
│ ◉ Tribal Gov │ │
│ (primary) │ ENGLISH (REQUIRED) │
│ │ │
│ ○ Office │ Label * │
│ (related) │ ┌────────────────────────────────────┐ │
│ │ │ Cherokee Nation │ │
│ │ └────────────────────────────────────┘ │
│ │ │
│ ──────────── │ ... │
│ │ │
│ 80% complete │ [← Back] [Continue →] │
└──────────────┴──────────────────────────────────────────┘
Users can click side entities to switch between them at any time. Each entity maintains separate progress through the 5 steps.
Alternative: Tab-Based Navigation:
┌─────────────────────────────────────────────────────────┐
│ [Tribal Government ✓] [Office 40%] │
├─────────────────────────────────────────────────────────┤
│ │
│ Currently editing: Office Held by Head of State │
│ Step 3: Statements │
│ ... │
└─────────────────────────────────────────────────────────┘
Creating Related Entities
Workflow when curator clicks "Create new office":
- Wizard creates new entity placeholder in packet (
ent-002-office) - Sets
creation_path: primary.office_held_by_head_of_state - Switches active entity in UI to office
- Runs through 5 steps for office (Plan → Identify → Statements → Links → Review)
- On office completion:
- Returns focus to primary entity
- Populates
office_held_by_head_of_statestatement value with"ent-002-office" - Shows office as "Related entity (completed)" in sidebar/tabs
Cardinality Enforcement:
If statement has max_count: 1 and office is already created, "Create new office" button is disabled.
If max_count: null, curator can create multiple offices; wizard assigns ent-002-office, ent-003-office, etc.
Review Stage for Multi-Entity Packets
Review step shows all entities in packet with expandable sections:
┌─────────────────────────────────────────────────────────┐
│ Review: Multi-Entity Packet │
├─────────────────────────────────────────────────────────┤
│ PRIMARY ENTITY: Cherokee Nation │
│ Profile: TribalGovernmentUS │
│ Completeness: 80% │
│ │
│ [▼ Show details] │
│ │
│ RELATED ENTITIES (1) │
│ │
│ [▶ Office: Principal Chief of the Cherokee Nation] │
│ Profile: OfficeHeldByHeadOfState │
│ Completeness: 60% │
│ [Edit] [Remove] │
│ │
│ SHIPPING ORDER │
│ 1. Office (no dependencies) │
│ 2. Tribal Government (references office) │
│ │
│ [← Back] [Save Draft] [Ship to Wikidata →] │
└─────────────────────────────────────────────────────────┘
Profile-Driven UI Generation
Guidance Text Rendering
Profile guidance fields appear as:
- Inline help icons (ℹ️) with tooltip on hover
- Expandable help sections for longer guidance
- Contextual captions below input fields
Example from profile:
- id: native_name
guidance: >
Use the tribe's preferred self-designation in their native language(s).
Consult tribal language preservation resources or official communications.
Rendered in wizard:
Native Name
┌─────────────────────────────────────────────────────┐
│ ᎳᎫᎿ ᎠᏰᎲ │
└─────────────────────────────────────────────────────┘
ℹ️ Use the tribe's preferred self-designation in their
native language(s). [Learn more ▼]
Input Prompt Customization
Default input prompts:
- Labels: "Enter the primary name for this entity"
- Descriptions: "Enter a short, distinctive description"
- Statements: "Enter [statement label]"
Profile can override:
labels:
input_prompt: Use the name the tribe uses in referring to itself
Rendered as placeholder text or caption.
Allowed Items: Choice List Rendering
Behavior by list size:
| List Size | UI Widget |
|---|---|
| < 10 items | Dropdown (simple select) |
| 10-50 items | Searchable select with type-ahead |
| 50-200 items | Autocomplete with lazy loading |
| 200+ items | Autocomplete with server-side search |
UI hint override:
allowed_items:
source: sparql
query_ref: queries/federal_register_issues.sparql
ui_hint: searchable_select # Force specific widget
Fallback behavior:
If SPARQL query fails or returns empty, wizard uses fallback_items from profile:
allowed_items:
source: sparql
query_ref: queries/languages.sparql
fallback_items:
- id: Q1860
label: English
- id: Q1567
label: Cherokee
Future: QID Loading & Entity Editing
Post-MVP enhancement: Load existing Wikidata items into wizard for editing
Workflow
- User provides QID (e.g.,
Q5093) + profile name - Wizard fetches Wikidata JSON via
wbgetentitiesAPI - Transforms Wikidata JSON → GKC Entity JSON (reverse serialization)
- Populates curation packet with existing data
- User edits via normal 5-step workflow
- On ship, only changed statements are sent to Wikidata (diff-based updates)
Related Entity Auto-Loading
If profile references other profiles, wizard:
- Checks existing entity for related statements (e.g., P1906 office held by head of state)
- Fetches referenced QID (e.g., Q999888)
- Loads it into packet as related entity
- Presents multi-entity editing session
Example:
User loads Q5093 (Cherokee Nation) with TribalGovernmentUS profile
→ Wizard finds P1906 = Q999888 (Principal Chief office)
→ Loads OfficeHeldByHeadOfState profile for Q999888
→ Packet contains both entities; user can edit either
Depth-1 Loading Strategy
Current design: Load direct children only (one hop)
- Primary entity → Related entities (via entity_profile statements)
- Does not recursively load links-of-links
Future: Configurable depth in metadata:
profile_graph:
edges:
- target_profile: OfficeHeldByHeadOfState
max_depth: 2 # Load office + its related entities
Validation & Error Handling
Real-Time Validation
- On field blur: Check datatype, constraints, required status
- On statement completion: Validate qualifiers, references, cardinality
- Before step advancement: Check all required fields in current step are complete
Validation Severity Levels
| Severity | Behavior | Example |
|---|---|---|
| Error | Blocks progression; must fix | Missing required label |
| Warning | Allows progression; shows in review | Missing recommended statement |
| Info | Non-blocking suggestion | "Consider adding aliases for discoverability" |
Constraint Violation Messaging
Profile constraints generate user-friendly error messages:
Profile constraint:
constraints:
- type: format
pattern: "^Q\\d+$"
error_message: Must be a valid QID (e.g., Q123456)
Rendered error:
✗ Must be a valid QID (e.g., Q123456)
You entered: "Cherokee Nation" (not a valid format)
Related Documentation
- GKC Architecture Overview — How wizards fit in GKC pipeline
- GKC Entity Profiles — Profile schema and structure reference
- GKC Entity JSON Schema — Curation packet format
- Profile Graphs & Multi-Entity Linking
Last Updated: March 3, 2026
Status: Stable (Phase 0 documentation; implementation evolving in Wizard MVP)