lutaml-openapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7b193ad406f534945c41bfbd3bce71181ec841b9f4924f8c107a4ca2a2160ed
+  data.tar.gz: e909c86543746e00d56973d4fead8dbe02742318f904acd5213a56d9925e1c77
+SHA512:
+  metadata.gz: 5d1c384ca671c9dbfa95ef73fd9806e67808af4534e8b4cd697321ea9fdc7a8d0f783da5ae8beaebb60c1d33dc15da782ad614954f6cd8d80263fb2e857fd200
+  data.tar.gz: 3c5de6c1bcd9a4454ffe79d6a17914a5f82bb0e4a70d5cda51a5899ff4d9f47f825c8ee35b753ea9833c885834f138785997d24ff71447ea0a4ee82c0b0ae628

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+All notable changes to this project are documented in this file.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"lutaml-jsonschema" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["ronald.tse@ribose.com"](mailto:"ronald.tse@ribose.com").

data/LICENSE.md

@@ -0,0 +1,33 @@
+Licenses & Copyright
+====================
+
+This license file adheres to the formatting guidelines of
+[readable-licenses](https://github.com/nevir/readable-licenses).
+
+
+Ribose's BSD 2-Clause License
+-----------------------------
+
+Copyright (c) 2026, [Ribose Inc](https://www.ribose.com).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1.  Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/PLAN.md

@@ -0,0 +1,103 @@
+# PLAN.md — lutaml-openapi: OpenAPI as a model-based standard
+
+Closes [metanorma/metanorma-ogc#153](https://github.com/metanorma/metanorma-ogc/issues/153)
+("Model-based standard (OpenAPI)", open since 2020-06-15): make the OpenAPI
+definition the **primary publication** of the OGC API family, with the
+implementers' guide and most of the normative OGC/ISO publication **driven by
+the OpenAPI model** — the ISO-10303 play (expressir → lutaml-express →
+metanorma-plugin-lutaml) applied to OpenAPI.
+
+## Mission
+
+Parse OpenAPI **3.0 and 3.1** documents into a lossless lutaml-model object
+graph; render them as (a) sovereign single-file human documentation and
+(b) normative Metanorma sections through `metanorma-plugin-openapi`, with
+Markdown descriptions properly converted to AsciiDoc via **coradoc**.
+
+## Repos and org parity
+
+| Repo | Org | Role | Setup cloned from |
+|---|---|---|---|
+| `lutaml/lutaml-openapi` | lutaml | the model gem | lutaml-xsd / lutaml-jsonschema (generic-rake CI, cimas release train, rubocop baseline, BSD-2-Clause) |
+| `metanorma/metanorma-plugin-openapi` | metanorma | the Metanorma plugin | metanorma-plugin-lutaml (rake.yml + release.yml, BSD-2-Clause, Ribose authorship) |
+
+Team access mirrors siblings: lutaml → staff:admin, developers:push,
+ci:push, express:push, editors:push; metanorma → staff:admin,
+developers:push, ci:push, editors:push.
+
+## Architecture
+
+```
+OpenAPI 3.0/3.1 (YAML/JSON, CommonMark descriptions)
+        │ parse (3.0 normalized into the 3.1-shaped model; source dialect kept)
+        ▼
+Lutaml::Openapi::Document ── components.schemas ──► Lutaml::Jsonschema::Schema
+        │                                            (lossless: map_unmapped)
+        ├─► SPA (own Vue frontend, lutaml-xsd precedent)          [human guide]
+        └─► metanorma-plugin-openapi ── Coradoc.convert(md → adoc) [normative]
+              requirements-class rendering per the OGC API - Features
+              "requirements class OpenAPI 3.1" pattern (ModSpec-aware)
+```
+
+### Design decisions
+
+1. **3.1-shaped model, 3.0 frontend.** 3.1 is the superset and its Schema
+   objects are 2020-12 — lutaml-jsonschema's native dialect. The 3.0 parser
+   normalizes into the 3.1 shape (`nullable` → `type: [T, null]`,
+   boolean `exclusiveMinimum` → numeric, `binary`/`file` formats) while
+   `source_dialect` is kept on the document; serialization re-emits 3.0
+   semantics for 3.0 sources. Anything unmodeled rides `map_unmapped`
+   extensions — the document round-trips verbatim.
+2. **Descriptions are Markdown (CommonMark per OAS).** The model stores them
+   verbatim (losslessness). Conversion to AsciiDoc happens at render time via
+   `Coradoc.convert(desc, from: :markdown, to: :asciidoc)` — the coradoc tree
+   is the manipulation point (opoudjis's pipeline in metanorma-ogc#153). The
+   SPA keeps its own markdown-lite renderer.
+3. **Schema layer is delegated.** `components.schemas` materializes as
+   `Lutaml::Jsonschema::Schema` — schema-level features (diff, exports, meta-
+   schema validation) come free and stay MECE with lutaml-jsonschema.
+4. **The plugin targets ModSpec.** metanorma#125 shipped the model-based
+   standards machinery (modspec 0.2.3). The plugin renders
+   requirements-class sections that reference/extend OpenAPI artifacts —
+   the Features API pattern — not free-form prose.
+5. **Own SPA frontend** in lutaml-openapi (lutaml-xsd precedent), seeded
+   from lutaml-jsonschema's frontend patterns (i18n catalog, axe audit in
+   the default rake gate, browser/PDF gates, determinism guard).
+
+## Milestones
+
+- **M0 — repos live with sibling parity** (this milestone): both repos
+  created, teams set, CI + release workflows, lint baseline, first PR merged.
+  *Done-when:* both repos' CI green on main; team access matches siblings.
+- **M1 — 3.1 model + 3.0 frontend parser**: `Document`, `Path`, `Operation`,
+  `Components`, `Response`, `Parameter`, `RequestBody`, `SecurityScheme`,
+  `Server`; schemas as `Lutaml::Jsonschema::Schema`; lossless round-trip;
+  both OGC corpus documents (oas30 + oas31) parse, round-trip, and
+  meta-validate. *Done-when:* both corpus files round-trip with zero
+  modeled-keyword loss (golden specs); unknown keywords preserved.
+- **M2 — SPA**: OpenAPI human guide (paths/operations/components views,
+  search, builder for examples); i18n + AA audit + determinism + browser
+  gates as in lutaml-jsonschema. *Done-when:* the two corpus documents render
+  as single-file SPAs that boot in headless Chrome and pass axe AA.
+- **M3 — `metanorma-plugin-openapi`**: `lutaml_openapi` /
+  `openapi_requirements_class` blocks emitting normative AsciiDoc sections;
+  descriptions through coradoc; ModSpec requirement-class alignment.
+  *Done-when:* an AsciiDoc document embedding the Features API OpenAPI
+  renders through metanorma into valid HTML/PDF with normative sections.
+- **M4 — OGC acceptance**: a metanorma-ogc#153 close-out demonstration —
+  OGC API - Features Part 1 published as (a) our SPA and (b) a Metanorma
+  document with model-driven normative sections. *Done-when:* the demonstration
+  is linked on metanorma-ogc#153 and the ticket can close.
+
+## Non-goals (for now)
+
+- OpenAPI 2.0/Swagger; AsyncAPI.
+- Markdown *authoring* of OpenAPI (opoudjis's coradoc round-trip) — the 2026
+  note makes requirements authoring the focus; revisit later.
+- We do not host/serve anything: artifacts are sovereign files.
+
+## Standing laws (inherited)
+
+lutaml-model serialization only (no hand-rolled to_h); autoload over
+require_relative; PRs only, never commit to main; no AI attribution; exact
+release versions from the owner; real objects in specs, never doubles.

data/README.md

@@ -0,0 +1,9 @@
+# Lutaml::Openapi
+
+OpenAPI 3.0/3.1 as a lossless lutaml-model — the model layer for
+model-based OpenAPI standards (see PLAN.md for the program; closes
+metanorma/metanorma-ogc#153's model layer).
+
+## Status
+
+Scaffold. Milestones and acceptance criteria live in [PLAN.md](PLAN.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/lutaml/openapi/document.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Openapi
+    # An OpenAPI document: the root object (3.1 shape).
+    #
+    # 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.
+    class Document < Lutaml::Model::Serializable
+      attribute :openapi, :string
+      attribute :source_dialect, :string
+      attribute :info, :hash
+      attribute :servers, :hash, collection: true
+      attribute :paths, :hash
+      attribute :webhooks, :hash
+      attribute :security, :hash, collection: true
+      attribute :tags, :hash, collection: true
+      attribute :external_docs, :hash
+      attribute :components, :hash
+
+      # Keywords the model does not name (vendor extensions, dialect
+      # additions): collected verbatim, re-emitted on serialization.
+      attribute :extensions, :hash, default: -> { {} }
+
+      json do
+        map "openapi", to: :openapi
+        map "info", to: :info
+        map "servers", to: :servers
+        map "paths", to: :paths
+        map "webhooks", to: :webhooks
+        map "components", to: :components
+        map "security", to: :security
+        map "tags", to: :tags
+        map "externalDocs", to: :external_docs
+        map_unmapped to: :extensions
+      end
+
+      # components.schemas as { name => Lutaml::Jsonschema::Schema } —
+      # the typed view for diff/exports/validation.
+      def schemas
+        ((components && components["schemas"]) || {}).to_h do |name, value|
+          [name, Lutaml::Jsonschema::Schema.from_json(JSON.generate(value))]
+        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)
+      end
+    end
+  end
+end

data/lib/lutaml/openapi/oas30.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+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.
+    module Oas30
+      module_function
+
+      def normalize(hash)
+        walk(hash) do |node|
+          node = normalize_nullable(node)
+          normalize_exclusive(node, "exclusiveMinimum", "minimum") ||
+            normalize_exclusive(node, "exclusiveMaximum", "maximum") || node
+        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
+          node = yield node
+          node.transform_values { |v| walk(v, &) }
+        when Array
+          node.map { |v| walk(v, &) }
+        else
+          node
+        end
+      end
+
+      # 3.0 `nullable: true` → a null-member type union; `nullable:
+      # false` is dropped (3.1 default).
+      def normalize_nullable(node)
+        return node unless node.key?("nullable")
+
+        nullable = node.delete("nullable")
+        return node unless nullable == true
+
+        types = Array(node["type"]).compact
+        node["type"] = (types << "null").uniq unless types.include?("null")
+        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)
+        return node unless [true, false].include?(node[exclusive])
+
+        flag = node.delete(exclusive)
+        # the bound MOVES into exclusive*: minimum must not survive it
+        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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Openapi
+    VERSION = "0.1.0"
+  end
+end

data/lib/lutaml/openapi.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "lutaml/jsonschema"
+require "lutaml/model"
+require "yeptris/yaml"
+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.
+  # Anything unmodeled rides the extensions catch-all — documents
+  # round-trip verbatim.
+  module Openapi
+    autoload :VERSION, "lutaml/openapi/version"
+    autoload :Document, "lutaml/openapi/document"
+    autoload :Oas30, "lutaml/openapi/oas30"
+
+    # Parse an OpenAPI document (YAML or JSON, 3.0 or 3.1) into a
+    # lossless {Document}.
+    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
+      end
+    end
+
+    def self.parse_raw(string)
+      stripped = string.lstrip
+      if stripped.start_with?("{", "[")
+        require "yeptris/json"
+        Yeptris::JSON.load(string)
+      else
+        Yeptris::YAML.load(string)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: lutaml-openapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: lutaml-jsonschema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.25
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.25
+- !ruby/object:Gem::Dependency
+  name: lutaml-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.122
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.122
+- !ruby/object:Gem::Dependency
+  name: yeptris
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.34
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.34
+description: Parse OpenAPI 3.0/3.1 documents into lossless LutaML model objects; the
+  model layer for model-based OpenAPI standards
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop_todo.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.md
+- PLAN.md
+- README.md
+- Rakefile
+- lib/lutaml/openapi.rb
+- lib/lutaml/openapi/document.rb
+- lib/lutaml/openapi/oas30.rb
+- lib/lutaml/openapi/version.rb
+homepage: https://github.com/lutaml/lutaml-openapi
+licenses:
+- BSD-2-Clause
+metadata:
+  homepage_uri: https://github.com/lutaml/lutaml-openapi
+  source_code_uri: https://github.com/lutaml/lutaml-openapi
+  changelog_uri: https://github.com/lutaml/lutaml-openapi/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: OpenAPI 3.0/3.1 as a lossless lutaml-model
+test_files: []