lutaml-openapi 0.1.2 → 0.1.3

data/frontend/package.json

@@ -16,12 +16,13 @@
     "vue-router": "^4.3.0"
   },
   "devDependencies": {
-    "@vitejs/plugin-vue": "^5.0.0",
+    "@vitejs/plugin-vue": "^6.0.10",
+    "axe-core": "^4.14.0",
     "jsdom": "^29.1.1",
     "terser": "^5.46.2",
     "typescript": "^5.3.0",
-    "vite": "^5.4.0",
-    "vitest": "^4.1.5",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
     "vue-tsc": "^2.0.0"
   }
 }

data/frontend/src/App.vue

@@ -1,8 +1,9 @@
 <script setup lang="ts">
-import { computed, ref, provide } from 'vue'
+import { computed, ref, provide, onMounted } from 'vue'
 import OverviewView from './components/OverviewView.vue'
 import PathsView from './components/PathsView.vue'
 import SchemasView from './components/SchemasView.vue'
+import { t, tf, initLocaleFromUrl, localeLabel, nextLocale, setLocale } from './i18n'
 
 const props = defineProps<{ openapi: Record<string, any> }>()
 provide('openapi', props.openapi)
@@ -10,11 +11,17 @@ provide('openapi', props.openapi)
 const filter = ref('')
 const view = ref<'overview' | 'paths' | 'schemas'>('overview')
 const views = [
-  { id: 'overview', label: 'Overview' },
-  { id: 'paths', label: 'Paths' },
-  { id: 'schemas', label: 'Schemas' },
+  { id: 'overview', label: 'nav.overview' },
+  { id: 'paths', label: 'nav.paths' },
+  { id: 'schemas', label: 'nav.schemas' },
 ] as const
 
+onMounted(() => initLocaleFromUrl())
+
+function switchLocale() {
+  setLocale(nextLocale())
+}
+
 const info = computed(() => (props.openapi.info as any) || {})
 const schemaCount = computed(
   () => Object.keys(((props.openapi.components as any)?.schemas as any) || {}).length,
@@ -25,18 +32,18 @@ const pathCount = computed(() => Object.keys((props.openapi.paths as any) || {})
 <template>
   <div class="docs">
     <header class="docs-header">
-      <h1>{{ info.title || 'OpenAPI document' }}</h1>
+      <h1>{{ info.title || t('app.titleFallback') }}</h1>
       <p v-if="info.version" class="version">
-        {{ info.title ? 'version' : '' }} {{ info.version }}
+        {{ info.title ? t('app.version') : '' }} {{ info.version }}
       </p>
       <input
         v-model="filter"
         class="filter"
         type="search"
-        placeholder="Filter…"
-        aria-label="Filter sections"
+        :placeholder="t('app.filterPlaceholder')"
+        :aria-label="t('app.filterAria')"
       />
-      <nav aria-label="Sections">
+      <nav :aria-label="t('nav.sections')">
         <button
           v-for="v in views"
           :key="v.id"
@@ -44,9 +51,16 @@ const pathCount = computed(() => Object.keys((props.openapi.paths as any) || {})
           :class="{ active: view === v.id }"
           @click="view = v.id"
         >
-          {{ v.label }}
+          {{ t(v.label) }}
         </button>
       </nav>
+      <button
+        class="nav-btn locale-btn"
+        :title="t('app.switchLocale')"
+        @click="switchLocale"
+      >
+        {{ localeLabel(nextLocale()) }}
+      </button>
     </header>
     <main>
       <OverviewView v-if="view === 'overview'" :filter="filter" />
@@ -54,7 +68,7 @@ const pathCount = computed(() => Object.keys((props.openapi.paths as any) || {})
       <SchemasView v-else :filter="filter" />
     </main>
     <footer class="docs-footer">
-      <span>{{ schemaCount }} schemas · {{ pathCount }} paths</span>
+      <span>{{ tf('footer.stats', { schemas: schemaCount, paths: pathCount }) }}</span>
     </footer>
   </div>
 </template>

data/frontend/src/__tests__/i18n.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+// @vitest-environment jsdom
+import {
+  t,
+  tf,
+  setLocale,
+  locale,
+  locales,
+  localeLabel,
+  isLocale,
+  nextLocale,
+  directionFor,
+  applyDocumentLocale,
+  initLocaleFromUrl,
+} from '../i18n'
+import { messages } from '../i18n/messages'
+
+describe('i18n', () => {
+  beforeEach(() => setLocale('en'))
+
+  it('looks up strings in the active locale', () => {
+    expect(t('nav.overview')).toBe('Overview')
+  })
+
+  it('falls back to English, then to the key itself', () => {
+    expect(t('nav.paths')).toBe(messages.en['nav.paths'])
+    // @ts-expect-error — deliberate unknown key at runtime
+    expect(t('nav.doesNotExist')).toBe('nav.doesNotExist')
+  })
+
+  it('interpolates parameters', () => {
+    expect(tf('footer.stats', { schemas: 3, paths: 7 }))
+      .toBe('3 schemas · 7 paths')
+    expect(tf('schemas.propertiesOf', { name: 'thing' }))
+      .toBe('Properties of thing')
+  })
+
+  it('switches locales', () => {
+    setLocale('en')
+    expect(locale()).toBe('en')
+  })
+
+  it('maps locales to writing directions', () => {
+    expect(directionFor('en')).toBe('ltr')
+    expect(directionFor('ar')).toBe('rtl')
+  })
+
+  it('mirrors lang and dir onto the document element', () => {
+    applyDocumentLocale('en')
+    expect(document.documentElement.lang).toBe('en')
+    expect(document.documentElement.dir).toBe('ltr')
+  })
+
+  it('translates every key in Arabic and mirrors RTL for it', () => {
+    setLocale('ar')
+    expect(locale()).toBe('ar')
+    expect(t('nav.schemas')).toBe('الأنماط')
+    expect(tf('footer.stats', { schemas: 2, paths: 5 }))
+      .toBe('2 أنماط · 5 مسارات')
+    expect(document.documentElement.dir).toBe('rtl')
+    expect(document.documentElement.lang).toBe('ar')
+    setLocale('en')
+  })
+
+  it('falls back to English for keys a locale has not translated', () => {
+    const ar = messages.ar as Record<string, string>
+    const en = messages.en as Record<string, string>
+    const untranslated = Object.keys(en).find((k) => !(k in ar))
+    if (untranslated) {
+      setLocale('ar')
+      expect(t(untranslated as never)).toBe(en[untranslated])
+      setLocale('en')
+    }
+  })
+
+  it('exposes the locale list, labels, and the cycle', () => {
+    expect(locales()).toEqual(['en', 'ar'])
+    expect(localeLabel('ar')).toBe('العربية')
+    expect(nextLocale()).toBe('ar')
+    setLocale('ar')
+    expect(nextLocale()).toBe('en')
+    setLocale('en')
+  })
+
+  it('guards isLocale against unknown values', () => {
+    expect(isLocale('ar')).toBe(true)
+    expect(isLocale('xx')).toBe(false)
+    expect(isLocale(null)).toBe(false)
+  })
+
+  it('boots the locale from ?locale=, else keeps the default', () => {
+    initLocaleFromUrl('?locale=ar')
+    expect(locale()).toBe('ar')
+    expect(document.documentElement.dir).toBe('rtl')
+    setLocale('en')
+    initLocaleFromUrl('?locale=xx')
+    expect(locale()).toBe('en')
+    expect(document.documentElement.dir).toBe('ltr')
+    initLocaleFromUrl('')
+    expect(locale()).toBe('en')
+  })
+})

data/frontend/src/components/OverviewView.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { inject, computed } from 'vue'
+import { t } from '../i18n'
 
 const openapi = inject<Record<string, any>>('openapi') || {}
 const props = defineProps<{ filter: string }>()
@@ -14,10 +15,10 @@ const shown = computed(() => {
 </script>
 
 <template>
-  <section aria-label="Overview">
-    <h2>Overview</h2>
+  <section :aria-label="t('overview.heading')">
+    <h2>{{ t('overview.heading') }}</h2>
     <p v-if="info.description">{{ info.description }}</p>
-    <h3 v-if="shown.length">Servers</h3>
+    <h3 v-if="shown.length">{{ t('overview.servers') }}</h3>
     <ul>
       <li v-for="s in shown" :key="s.url">
         <code>{{ s.url }}</code> — {{ s.protocol || 'https' }}

data/frontend/src/components/PathsView.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { inject, computed } from 'vue'
+import { t } from '../i18n'
 
 const openapi = inject<Record<string, any>>('openapi') || {}
 const props = defineProps<{ filter: string }>()
@@ -31,8 +32,8 @@ const entries = computed(() => {
 </script>
 
 <template>
-  <section aria-label="Paths">
-    <h2>Paths</h2>
+  <section :aria-label="t('paths.heading')">
+    <h2>{{ t('paths.heading') }}</h2>
     <div v-for="e in entries" :key="e.path" class="path">
       <h3><code>{{ e.path }}</code></h3>
       <div v-for="op in e.operations" :key="op.method" class="op">
@@ -41,6 +42,6 @@ const entries = computed(() => {
         <p v-if="op.description">{{ op.description }}</p>
       </div>
     </div>
-    <p v-if="!entries.length">No paths match the filter.</p>
+    <p v-if="!entries.length">{{ t('paths.noMatch') }}</p>
   </section>
 </template>

data/frontend/src/components/SchemasView.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { inject, computed } from 'vue'
+import { t, tf } from '../i18n'
 
 const openapi = inject<Record<string, any>>('openapi') || {}
 const props = defineProps<{ filter: string }>()
@@ -30,15 +31,15 @@ const entries = computed(() => {
 </script>
 
 <template>
-  <section aria-label="Schemas">
-    <h2>Schemas</h2>
+  <section :aria-label="t('schemas.heading')">
+    <h2>{{ t('schemas.heading') }}</h2>
     <div v-for="e in entries" :key="e.name" class="schema">
       <h3>{{ e.name }}</h3>
       <p v-if="e.description">{{ e.description }}</p>
       <table v-if="e.properties.length">
-        <caption>Properties of {{ e.name }}</caption>
+        <caption>{{ tf('schemas.propertiesOf', { name: e.name }) }}</caption>
         <thead>
-          <tr><th>Name</th><th>Type</th><th>Description</th></tr>
+          <tr><th>{{ t('schemas.name') }}</th><th>{{ t('schemas.type') }}</th><th>{{ t('schemas.description') }}</th></tr>
         </thead>
         <tbody>
           <tr v-for="p in e.properties" :key="p.name">
@@ -49,6 +50,6 @@ const entries = computed(() => {
         </tbody>
       </table>
     </div>
-    <p v-if="!entries.length">No schemas match the filter.</p>
+    <p v-if="!entries.length">{{ t('schemas.noMatch') }}</p>
   </section>
 </template>

data/frontend/src/i18n/index.ts

@@ -0,0 +1,84 @@
+import { ref } from 'vue'
+import { messages, type Locale, type MessageKey } from './messages'
+
+// The locale rides a Vue ref so every rendered string is a reactive
+// dependency: flipping the locale re-renders exactly the components
+// that showed translated text.
+const activeLocale = ref<Locale>('en')
+
+/** Native names, shown on the switch button for the TARGET locale. */
+const LOCALE_LABELS: Record<Locale, string> = {
+  en: 'English',
+  ar: 'العربية',
+}
+
+/** Writing direction per locale — RTL locales must mirror the layout. */
+const RTL_LOCALES: readonly string[] = ['ar', 'he', 'fa', 'ur']
+
+export function locale(): Locale {
+  return activeLocale.value
+}
+
+export function locales(): Locale[] {
+  return Object.keys(messages) as Locale[]
+}
+
+export function localeLabel(id: Locale): string {
+  return LOCALE_LABELS[id]
+}
+
+export function isLocale(value: unknown): value is Locale {
+  return typeof value === 'string' && locales().includes(value as Locale)
+}
+
+/** The locale the switch button would move to (single-step cycle). */
+export function nextLocale(): Locale {
+  const all = locales()
+  return all[(all.indexOf(activeLocale.value) + 1) % all.length]
+}
+
+export function directionFor(id: Locale): 'ltr' | 'rtl' {
+  return RTL_LOCALES.includes(id) ? 'rtl' : 'ltr'
+}
+
+/** Mirror <html lang/dir> so layout, fonts and scrollbars follow the locale. */
+export function applyDocumentLocale(id: Locale = activeLocale.value): void {
+  if (typeof document === 'undefined') return
+  document.documentElement.lang = id
+  document.documentElement.dir = directionFor(id)
+}
+
+/** Boot-time locale: an explicit `?locale=` wins, else the default. */
+export function initLocaleFromUrl(
+  search: string = typeof window === 'undefined' ? '' : window.location.search,
+): void {
+  const requested = new URLSearchParams(search).get('locale')
+  if (isLocale(requested)) {
+    setLocale(requested)
+  } else {
+    applyDocumentLocale()
+  }
+}
+
+export function setLocale(next: Locale): void {
+  activeLocale.value = next
+  applyDocumentLocale(next)
+}
+
+/** Look up a UI string in the active locale, falling back to English. */
+export function t(key: MessageKey): string {
+  const table = messages[activeLocale.value] as Record<string, string>
+  const english = messages.en as Record<string, string>
+  return table[key] ?? english[key] ?? key
+}
+
+/** Interpolated variant: t('search.noResultsFor', { query: 'foo' }) */
+export function tf(
+  key: MessageKey,
+  params: Record<string, string | number>,
+): string {
+  return Object.entries(params).reduce(
+    (text, [name, value]) => text.replaceAll(`{${name}}`, String(value)),
+    t(key),
+  )
+}

data/frontend/src/i18n/messages.ts

@@ -0,0 +1,63 @@
+// UI string catalog. `en` is the source of truth; additional locales add
+// entries under their own key. Keys are flat and namespaced per component.
+// A missing key in any locale is a type error against messages.en.
+export const messages = {
+  en: {
+    'app.titleFallback': 'OpenAPI document',
+    'app.version': 'version',
+    'app.filterPlaceholder': 'Filter…',
+    'app.filterAria': 'Filter sections',
+    'app.switchLocale': 'Switch locale',
+
+    'nav.overview': 'Overview',
+    'nav.paths': 'Paths',
+    'nav.schemas': 'Schemas',
+    'nav.sections': 'Sections',
+
+    'overview.heading': 'Overview',
+    'overview.servers': 'Servers',
+
+    'paths.heading': 'Paths',
+    'paths.noMatch': 'No paths match the filter.',
+
+    'schemas.heading': 'Schemas',
+    'schemas.propertiesOf': 'Properties of {name}',
+    'schemas.name': 'Name',
+    'schemas.type': 'Type',
+    'schemas.description': 'Description',
+    'schemas.noMatch': 'No schemas match the filter.',
+
+    'footer.stats': '{schemas} schemas · {paths} paths',
+  },
+
+  ar: {
+    'app.titleFallback': 'وثيقة OpenAPI',
+    'app.version': 'الإصدار',
+    'app.filterPlaceholder': 'تصفية…',
+    'app.filterAria': 'تصفية الأقسام',
+    'app.switchLocale': 'تبديل اللغة',
+
+    'nav.overview': 'نظرة عامة',
+    'nav.paths': 'المسارات',
+    'nav.schemas': 'الأنماط',
+    'nav.sections': 'الأقسام',
+
+    'overview.heading': 'نظرة عامة',
+    'overview.servers': 'الخوادم',
+
+    'paths.heading': 'المسارات',
+    'paths.noMatch': 'لا توجد مسارات مطابقة للتصفية.',
+
+    'schemas.heading': 'الأنماط',
+    'schemas.propertiesOf': 'خصائص {name}',
+    'schemas.name': 'الاسم',
+    'schemas.type': 'النوع',
+    'schemas.description': 'الوصف',
+    'schemas.noMatch': 'لا توجد أنماط مطابقة للتصفية.',
+
+    'footer.stats': '{schemas} أنماط · {paths} مسارات',
+  },
+} as const
+
+export type Locale = keyof typeof messages
+export type MessageKey = keyof typeof messages.en

data/lib/lutaml/openapi/corpus_audit.rb

@@ -73,11 +73,12 @@ module Lutaml
         raw = Lutaml::Openapi.parse_raw(File.read(path))
         # The model is JSON-keyed: YAML integer keys (unquoted response
         # codes) stringify through the pipeline, so compare against the
-        # JSON-normalized raw. to_hash is the serialization contract:
-        # 3.0 sources denormalize back on it. Hash == is deep and
+        # JSON-normalized raw. The wire is the losslessness contract:
+        # to_json re-emits mapped sections in dialect shape and the
+        # extensions catch-all verbatim. Hash == is deep and
         # key-order-insensitive.
         normalized = JSON.parse(JSON.generate(raw))
-        doc.to_hash == normalized
+        JSON.parse(doc.to_json) == normalized
       end
     end
   end

data/lib/lutaml/openapi/document.rb

@@ -2,14 +2,14 @@
 
 module Lutaml
   module Openapi
-    # An OpenAPI document: the root object (3.1 shape).
+    # An OpenAPI document: the root object, stored verbatim.
     #
-    # Losslessness lives on the raw hash: `components` (and every other
-    # section) is kept verbatim, and 3.0 sources denormalize back on
-    # serialization. The typed schema view (#schemas) materializes
-    # lutaml-jsonschema models on demand — that view applies the
-    # jsonschema model's own normalizations, so round-trip fidelity is
-    # asserted on the hash, not the typed layer.
+    # Losslessness is structural: every parsed section is kept exactly
+    # as the source carried it (3.0 dialects included), so both wire
+    # serializations round-trip without an emit-time transform. The
+    # typed schema view (#schemas) is where dialects converge — it
+    # materializes lutaml-jsonschema models from the 3.1-normalized
+    # shape, applying the 3.0 frontend for 3.0 sources on demand.
     class Document < Lutaml::Model::Serializable
       attribute :openapi, :string
       attribute :source_dialect, :string
@@ -40,19 +40,20 @@ module Lutaml
       end
 
       # components.schemas as { name => Lutaml::Jsonschema::Schema } —
-      # the typed view for diff/exports/validation.
+      # the typed view for diff/exports/validation. Schema nodes are
+      # normalized into the 3.1 shape here: this is the only place the
+      # 3.0 frontend applies.
       def schemas
         ((components && components["schemas"]) || {}).to_h do |name, value|
-          [name, Lutaml::Jsonschema::Schema.from_json(JSON.generate(value))]
+          shape = source_dialect == "3.0" ? Oas30.normalize(value) : value
+          [name, Lutaml::Jsonschema::Schema.from_json(JSON.generate(shape))]
         end
       end
 
       def to_hash(options = {})
         hash = super
         hash.delete("source_dialect") # internal: tracks the frontend used
-        return hash unless source_dialect == "3.0"
-
-        Oas30.denormalize(hash)
+        hash
       end
     end
   end

data/lib/lutaml/openapi/oas30.rb

@@ -2,9 +2,10 @@
 
 module Lutaml
   module Openapi
-    # The OpenAPI 3.0 frontend: normalizes 3.0 documents into the 3.1
-    # shape before modeling, and denormalizes back on serialization —
-    # both directions as pure hash walks.
+    # The OpenAPI 3.0 frontend: normalizes 3.0 schema nodes into the
+    # 3.1 shape as a pure hash walk. Applied only where the typed layer
+    # consumes nodes — the document hash itself is stored verbatim, so
+    # no denormalization exists.
     module Oas30
       module_function
 
@@ -16,14 +17,6 @@ module Lutaml
         end
       end
 
-      def denormalize(hash)
-        walk(hash) do |node|
-          node = denormalize_nullable(node)
-          node = denormalize_exclusive(node, "exclusiveMinimum", "minimum")
-          denormalize_exclusive(node, "exclusiveMaximum", "maximum")
-        end
-      end
-
       def walk(node, &)
         case node
         when Hash
@@ -49,20 +42,6 @@ module Lutaml
         node
       end
 
-      def denormalize_nullable(node)
-        types = node["type"]
-        return node unless types.is_a?(Array) && types.include?("null")
-
-        rest = types - ["null"]
-        if rest.empty?
-          node.delete("type") # 3.0 had only `nullable: true`, no type
-        else
-          node["type"] = rest.size == 1 ? rest.first : rest
-        end
-        node["nullable"] = true
-        node
-      end
-
       # 3.0 boolean exclusivity rides beside the bound; 3.1 carries the
       # bound in the exclusive* keyword itself.
       def normalize_exclusive(node, exclusive, bound)
@@ -73,15 +52,6 @@ module Lutaml
         node[exclusive] = node.delete(bound) if flag == true && node.key?(bound)
         node
       end
-
-      def denormalize_exclusive(node, exclusive, bound)
-        value = node[exclusive]
-        return node unless value.is_a?(Numeric)
-
-        node = node.merge(bound => value)
-        node[exclusive] = true
-        node
-      end
     end
   end
 end

data/lib/lutaml/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Openapi
-    VERSION = "0.1.2"
+    VERSION = "0.1.3"
   end
 end

data/lib/lutaml/openapi.rb

@@ -8,10 +8,11 @@ require "json"
 module Lutaml
   # OpenAPI 3.0/3.1 as a lossless lutaml-model.
   #
-  # The 3.1 shape is the model (its Schema objects are JSON Schema
-  # 2020-12, carried by lutaml-jsonschema); 3.0 documents are
-  # normalized into it by the 3.0 frontend while `source_dialect` is
-  # kept, so serialization re-emits 3.0 semantics for 3.0 sources.
+  # The document is stored verbatim — what was parsed is what the wire
+  # re-emits, so losslessness is structural rather than an emit-time
+  # transform. The 3.1 shape is the typed view: `source_dialect` tracks
+  # the frontend, and 3.0 schema nodes are normalized into JSON Schema
+  # 2020-12 by the 3.0 frontend when the typed layer materializes them.
   # Anything unmodeled rides the extensions catch-all — documents
   # round-trip verbatim.
   module Openapi
@@ -26,7 +27,6 @@ module Lutaml
     def self.parse(string)
       data = parse_raw(string)
       dialect = data["openapi"].to_s.start_with?("3.0") ? "3.0" : "3.1"
-      data = Oas30.normalize(data) if dialect == "3.0"
 
       Document.from_json(JSON.generate(data)).tap do |doc|
         doc.source_dialect = dialect