The goal: build the best community resource site for learning about ontologies and Microsoft Fabric IQ Ontologies. Fully static, deployable to Azure Static Web Apps or GitHub Pages.

The current RDF export is inline in ImportExportModal.tsx and there is no RDF import. RDF should become a first-class serialization format.

• Create src/lib/rdf/serializer.ts — move the existing exportAsRDF() logic out of ImportExportModal.tsx into a pure function serializeToRDF(ontology, bindings) → string
• Create src/lib/rdf/parser.ts — implement parseRDF(rdfXmlString) → { ontology, bindings } using a lightweight XML parser (browser DOMParser; no heavy deps)
• Support OWL classes → EntityTypes, DatatypeProperties → Properties, ObjectProperties → Relationships
• Round-trip fidelity: parse(serialize(ontology)) must produce an equivalent ontology

• In ImportExportModal.tsx, accept .rdf and .owl files in the file input
• Detect format by extension and/or XML prologue, route to the RDF parser
• Show validation errors inline if the RDF is malformed

• Set up Vitest (vitest, @testing-library/react, @testing-library/jest-dom)
• Unit tests for serializer.ts:
  • Empty ontology
  • Ontology with all property types (string, integer, decimal, date, etc.)
  • Ontology with relationship attributes
  • XML special character escaping (& < > " ')
  • Data bindings preservation in comments
• Unit tests for parser.ts:
  • Valid RDF/OWL input → correct Ontology shape
  • Missing required fields → descriptive error
  • Namespace handling (custom prefixes, default namespace)
  • Malformed XML → graceful error
• Round-trip tests: serialize → parse → deep-equal for every sample ontology in sampleOntologies.ts and cosmicCoffeeOntology
• Integration test: import an RDF file via the modal, verify store state
• Add "test": "vitest run" and "test:watch": "vitest" to package.json scripts

The app currently proxies /api to an Azure Functions backend. The site must work as a pure static build with zero server-side dependencies. Azure SWA is the primary deployment target; GitHub Pages support is for forks.

• The Azure OpenAI feature is already behind VITE_ENABLE_AI_BUILDER — confirm the build produces zero /api calls when the flag is off
• Audit all fetch() calls; ensure none target a dynamic backend when running in static mode
• Guard the Vite dev proxy (server.proxy) behind VITE_ENABLE_AI_BUILDER so it doesn't confuse static deployments

The existing workflow .github/workflows/azure-static-web-apps-green-plant-0bb1d2910.yml handles build + deploy. Adapt it for the new build pipeline:

• Add npm run catalogue:build step before the SWA deploy action (once §3.2 is done)
• Verify staticwebapp.config.json is correct for the static-only build (remove api_location if the API feature flag is off)
• Ensure the output_location: "build" matches Vite's outDir
• Keep the existing PR preview environment support (staging URLs on PRs)

• Add a separate GitHub Actions workflow .github/workflows/deploy-ghpages.yml:
  • Trigger on push to main
  • npm ci && npm run catalogue:build && npm run build
  • Deploy build/ via actions/deploy-pages
  • Disabled by default (forks enable it by setting the Pages source)
• Set base in vite.config.ts dynamically from an env var (VITE_BASE_PATH) so it works at / (Azure SWA) and /<repo-name>/ (GitHub Pages)
• Copy index.html → build/404.html for SPA fallback on GitHub Pages
• Document both deployment paths in README

A curated + community-driven catalogue of ontologies, compiled at build time into a static JSON file.

• Create catalogue/ directory at repo root
• Define a folder convention:

  catalogue/
    official/
      cosmic-coffee.rdf
      e-commerce.rdf
      ...
    community/
      <github-username>/
        <ontology-slug>.rdf
        metadata.json    ← { name, description, author, tags, ... }
  

• Create a JSON Schema for metadata.json to validate contributions
• Existing sample ontologies in src/data/sampleOntologies.ts should be migrated to catalogue/official/ as RDF files with metadata

• Write a build script (scripts/compile-catalogue.ts) that:
  1. Reads all catalogue/**/*.rdf files
  2. Parses each via the RDF parser from §1
  3. Reads associated metadata.json
  4. Emits public/catalogue.json — a single JSON file with all ontologies, metadata, and category info
• Add an npm script: "catalogue:build": "tsx scripts/compile-catalogue.ts"
• Integrate into npm run build: "build": "npm run catalogue:build && tsc -b && vite build"
• On build failure (invalid RDF, missing metadata), fail loudly with a helpful error message

• Add LICENSE file — MIT License (standard for Microsoft OSS projects)
• Add CONTRIBUTING.md following the Microsoft Open Source Contributing Guide:
  • Contributor License Agreement (CLA) requirement — add the Microsoft CLA bot to the repo
  • Fork → add RDF + metadata.json under catalogue/community/<username>/
  • Open PR → CI validates the RDF and metadata schema
  • On merge, the next build includes the new ontology
• Add CODE_OF_CONDUCT.md — use the Microsoft Open Source Code of Conduct
• Add SECURITY.md — use the Microsoft Security Policy template
• Add a GitHub Actions CI job that validates PRs touching catalogue/:
  • Parse RDF, verify round-trip, check metadata schema
  • Run the full test suite
• Consider also accepting GitHub Gist URLs in metadata.json ("source": "gist:<gist-id>") and fetching them at build time (optional, evaluate complexity vs. value)
• RDF validation in CI — use npm run validate (backed by scripts/validate-rdf.ts) in a GitHub Actions step to gate community PRs. The script already validates all catalogue RDF files and can validate specific files via npm run validate -- path/to/file.rdf. Wire it into the PR validation workflow so invalid ontologies are rejected before merge.
• Contribution CTA link — Add a "Want to contribute? See CONTRIBUTING.md" button/link in the gallery or footer that points directly to the GitHub repo fork/PR flow. Link should be: https://github.com/microsoft/Ontology-Playground/fork (for forking) or the CONTRIBUTING.md file, so contributors can start the process without manual navigation.

• Refactor GalleryModal to load from catalogue.json instead of hardcoded sampleOntologies.ts
• Add category filters: Official / Community, plus domain tags (retail, healthcare, etc.)
• Add search/filter by name, author, tags
• Show author + contributor info for community ontologies
• Add "View RDF source" button for each ontology (links to the raw file in the repo or displays inline)
• Add pagination or virtual scroll if the catalogue grows large

Allow embedding an interactive ontology viewer in external pages (blogs, tutorials, docs) — similar to how CodePen or GitHub Gist embeds work.

• Create a separate Vite entry point src/embed.tsx that renders a minimal, self-contained ontology viewer:
  • Cytoscape graph visualization (read-only)
  • Entity/relationship inspector on click
  • Tab to toggle between graph view and RDF source view
  • Accepts ontology data via:
    • data-ontology-url attribute (URL to a .rdf or .json file)
    • data-ontology-inline attribute (inline JSON, base64-encoded)
    • data-catalogue-id attribute (loads from the published catalogue.json)
• Build as a single JS + CSS bundle: ontology-embed.js + ontology-embed.css
• Add Vite build config for the embed target:

  // vite.config.embed.ts
  build: {
    lib: { entry: 'src/embed.tsx', formats: ['iife'], name: 'OntologyEmbed' },
    rollupOptions: { output: { assetFileNames: 'ontology-embed.[ext]' } }
  }

• Keep bundle size under 150KB gzipped (Cytoscape is ~90KB gz, must account for it)

• Usage pattern for external pages:

  <div class="ontology-embed"
       data-catalogue-id="cosmic-coffee"
       data-theme="dark"
       data-height="500px">
  </div>
  <script src="https://<site>/ontology-embed.js"></script>

• Support configuration: theme (light/dark), height, initial zoom, read-only mode
• Provide a "Copy embed code" button in the main app's gallery for each ontology

• In the embed widget, add a tabbed view: "Graph" | "RDF Source"
• RDF source tab shows syntax-highlighted RDF/XML (use a lightweight highlighter or simple regex-based coloring — no heavy deps)
• Add a "Copy RDF" button

• Create public/embed/samples.html — an article-style page that teaches ontology concepts using live embedded visualizations
• Cover all 6 official ontologies across 8 sections
• Include dark/light theme comparison (side-by-side Finance embeds)
• Embed usage instructions + copy-paste snippet at the end

These enhance the overall experience for a community learning resource.

• Add client-side routing (e.g., lightweight hash-based router)
• Support routes:
  • /#/ — home (current default ontology)
  • /#/catalogue — opens gallery
  • /#/catalogue/<ontology-id> — loads and displays a specific ontology
  • /#/embed/<ontology-id> — full-page embed view (useful for iframes)
• Shareable URLs: loading the app with a route pre-selects the ontology
• Persist catalogue category filter in URL: when user selects a category filter in the gallery, the selection should be saved in the URL query params (e.g., /#/catalogue?category=healthcare) so that navigating away and back (or sharing a link) preserves the filter state

• When loading a new ontology, optionally show a diff view: "You'll add 3 entities, remove 1 relationship..."
• Useful for reviewing community PRs or comparing versions

• Audit and fix keyboard navigation across all modals and panels
• Add ARIA labels to the graph visualization
• Ensure the app is usable on tablet-sized screens (responsive breakpoints)
• Test with screen readers (VoiceOver, NVDA)

• Add a service worker + web app manifest
• Cache catalogue.json and the main app shell for offline use
• Users can browse the full catalogue without a network connection

• Once feature/code churn stops, run a dedicated optimization pass for release artifacts:
  • profile bundle composition with rollup-plugin-visualizer
  • split/trim graph-heavy paths and embed runtime where possible
  • tighten long-term caching strategy and asset naming
  • re-baseline size targets for main app and embed bundle

• Add optional, privacy-respecting analytics (e.g., Plausible, or simple custom event tracking to a static endpoint)
• "Was this ontology helpful?" thumbs up/down on each catalogue entry
• Track which ontologies are most loaded to surface popular ones

• Add a /learn section with markdown-rendered educational content:
  • "What is an ontology?"
  • "Understanding RDF and OWL"
  • "Microsoft Fabric IQ Ontology concepts"
  • "Building your first ontology"
• Content stored as .md files in content/learn/, compiled at build time
• Each tutorial can embed an interactive ontology widget (from §4)
• Restructured into course-based catalogue with learning paths and hands-on labs (8 courses, 39 articles total)
• Interactive quizzes with instant correct/wrong feedback
• Presentation mode (slides split at ## headings)
• Progressive ontology catalogue entries for step-by-step learning (18 school entries + 6 IQ Lab entries)

A visual designer for creating ontologies from scratch or editing existing ones. The output is a valid RDF file that can be submitted to the catalogue via a one-click PR flow.

• Create OntologyDesigner component — a full-screen editor panel
• Entity creation: name, icon picker, color picker, description
• Property builder: add/remove/reorder properties with type selectors (string, integer, decimal, date, datetime, boolean, enum)
• Mark identifier properties
• Drag-and-drop reordering of entities and properties

• Visual relationship creation: select source entity → target entity
• Set relationship name, cardinality (1:1, 1:n, n:1, n:n), description
• Optional: relationship attributes (e.g., quantity on an order→product edge)
• Live preview: as relationships are added, the Cytoscape graph updates in real-time

• Split-pane layout: editor form on the left, live Cytoscape graph on the right
• Graph updates in real-time as entities and relationships are added/edited/removed
• Click a node or edge in the graph to select it in the editor

• "Export RDF" button generates valid RDF/OWL via the serializer from §1
• "Preview RDF" tab shows the live RDF output as you design
• Validate the ontology before export:
  • All relationships reference existing entity IDs
  • No duplicate entity/relationship IDs
  • At least one entity type exists
  • Each entity has at least one identifier property

• "Submit to Catalogue" button that:
  1. Serializes the ontology to RDF
  2. Prompts for metadata (name, description, tags, author GitHub username)
  3. Uses the GitHub API to: a. Fork the repo (if not already forked) into the user's account b. Create a branch catalogue/<username>/<ontology-slug> c. Commit the .rdf file + metadata.json to catalogue/community/<username>/ d. Open a PR against the upstream repo
  4. Show a link to the created PR
• Requires GitHub OAuth — add a "Sign in with GitHub" flow (client-side OAuth via GitHub's device flow or a lightweight OAuth proxy)
• For unauthenticated users, fall back to "Download RDF" + manual PR instructions
• Pre-fill the PR description with an ontology summary (entity count, relationship count, description)

• "Edit" button in the Gallery for any loaded ontology → opens the designer pre-populated with the ontology data
• "Edit" button in the embed widget for catalogue ontologies
• When editing a community ontology, the PR targets the original file path (update, not create)

• Add an undo/redo history stack to the designer store (track snapshots of the ontology state on each mutation)
• Wire Ctrl+Z / Cmd+Z (undo) and Ctrl+Shift+Z / Cmd+Shift+Z (redo) keyboard shortcuts
• Add undo/redo buttons in the designer toolbar
• Cap history depth (e.g., 50 steps) to limit memory usage

• Add syntax highlighting to the RDF source view in the designer's "Preview RDF" tab — color XML tags, attributes, namespaces, and values
• Use a lightweight regex-based highlighter (no heavy deps like Prism/highlight.js) to keep bundle size small
• Apply the same highlighting to the embed widget's RDF Source tab and the Gallery's "View RDF source" panel

• Add a "Download .rdf" button to the designer toolbar that saves the current ontology as an RDF/XML file (similar to the catalogue's existing RDF download)
• File name should be derived from the ontology name (slugified), e.g., my-ontology.rdf
• Validate before download — show validation errors if the ontology has issues, but allow download anyway with a warning

The app must be usable on phones and tablets. Shared links (Teams, Slack, social media) often land on mobile — if users can't interact, adoption stalls.

• Collapse icon buttons into a hamburger/overflow menu on small screens
• Stack logo + subtitle vertically on narrow viewports
• Hide gamification stats on mobile (or move to hamburger menu)

• Switch from the 3-column grid (inspector | graph | quest) to a single-column stacked layout below 768px
• Graph takes full width; inspector and quest panel become collapsible drawers or tabs below the graph
• Touch-friendly: larger tap targets, swipe to dismiss drawers

• Modals become full-screen sheets on mobile (no floating card)
• Scrollable content within the sheet
• Close button always visible at top

• Article cards stack single-column on narrow screens
• Article content uses fluid typography and responsive images
• Navigation buttons (prev/next) are full-width on mobile

• Gallery grid adapts: 1 column on phone, 2 on tablet, 3+ on desktop
• Filter bar wraps or collapses on narrow screens
• Search bar is full-width on mobile

• Stacked layout: entity/relationship form on top, graph preview below
• Toolbar wraps or uses overflow on narrow screens

• Cmd+K / Ctrl+K opens a command palette
• Type to navigate: ontologies, designer, learn, import/export
• Keyboard shortcuts for common actions (listed in Help modal)

• "Start from template" option when opening the designer empty
• Domain presets: Retail, Healthcare, Finance, IoT, Education
• Each template creates 2–3 entities with relationships pre-wired
• Lowers the "blank page" barrier

• Replace the static welcome modal with a 5-step guided tour
• Spotlight overlay highlights: header → graph → inspector → query bar → designer
• Dismissable, with "Don't show again" option
• First-time users get oriented in 30 seconds

• "Use in Fabric IQ" export wizard — A guided flow (validate → download RDF → show Fabric IQ upload instructions). Deferred until the Fabric IQ integration story is clearer and a native link/API may be available.
• Re-enable GitHub Pages workflow — enabled with repo-scoped behavior: push-triggered Pages deploy runs for microsoft/Ontology-Playground.