lutaml-asyncapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b75c05f01f5016b7deba173f61e368b03928246dffb6f33fd5a7a097fbd4f960
+  data.tar.gz: eafbc41e37f96e3f5298782b3fe9a9c63a031bd7b0bea907f9cea25da67a5d30
+SHA512:
+  metadata.gz: 883f8c505425be9ad9425614ccc796c4afd64a59b8f93fe2aebba5ed15725ea4567feb9458f59d95ba94ec12ee544dff82a47dd23076f90e3e0b3d139ef13819
+  data.tar.gz: f95b27f78433d007a170fdfef17f77f05e34dbdc7719cf2bfd76272e5d26ea17acbe85db67a2b21132788b10f35640cb7a6756e822b4f32cddf14bc10c827154

data/.rubocop_todo.yml

@@ -0,0 +1 @@
+# Auto-generated by Cimas; offenses baselined at scaffold time.

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,86 @@
+# PLAN.md — lutaml-asyncapi: AsyncAPI as a model-based standard
+
+The event-driven counterpart of the OpenAPI program
+([metanorma/metanorma-ogc#153](https://github.com/metanorma/metanorma-ogc/issues/153),
+`lutaml/lutaml-openapi`): make the AsyncAPI definition the **primary
+publication** of event-driven / pub-sub API standards, with normative
+documentation driven by the AsyncAPI model.
+
+## Mission
+
+Parse **AsyncAPI 2.6, 3.0 and 3.1** documents into a lossless lutaml-model
+object graph (raw-hash fidelity first, typed views on demand), and feed them
+to documentation renderers the way `lutaml-openapi` feeds
+`metanorma-plugin-openapi`.
+
+## Audit basis (2026-10-25)
+
+Full spec read: `asyncapi/spec` `spec/asyncapi.md` (v3.1.0, 39 objects),
+meta-schemas `asyncapi/spec-json-schemas` (definitions 1.0.0–3.1.0).
+Corpus: 17 documents in `spec/fixtures` — 15 official 3.1.0 examples,
+`asyncapi-connectedsystems-2.yaml` (2.6.0, 9 embedded publish/subscribe
+operations), `edr-pubsub-asyncapi.yaml` (3.0.0). **All parse; 15/17 round-trip
+losslessly** — `gitter-streaming` and `slack-rtm` are blocked upstream by
+[lutaml/lutaml-model#1013](https://github.com/lutaml/lutaml-model/issues/1013)
+(nested `:hash` attributes silently rename key `text` → `type` and drop
+sibling `description`); they are vendored but excluded from goldens until
+that ships.
+
+Corpus facts shaping the model: no `schemaFormat` (Multi Format Schema)
+usage in the wild corpus; bindings sparse (kafka/mqtt/websocket); components
+sections seen in the wild: schemas, messages, parameters, securitySchemes,
+correlationIds, messageTraits, operationTraits (the model must still cover
+the full Components Object inventory: servers, channels, operations, replies,
+replyAddresses, externalDocs, tags, serverBindings, channelBindings,
+operationBindings, messageBindings, serverVariables).
+
+## Repos and org parity
+
+| Repo | Org | Role | Setup cloned from |
+|---|---|---|---|
+| `lutaml/lutaml-asyncapi` | lutaml | the model gem (this repo) | lutaml-openapi (generic-rake CI, cimas release train, rubocop baseline, BSD-2-Clause) |
+| `metanorma/metanorma-plugin-asyncapi` | metanorma | the Metanorma plugin (M3) | metanorma-plugin-openapi (preprocessor splice, real sections) |
+
+Team access mirrors siblings: staff:admin, developers:push, ci:push,
+express:push, editors:push.
+
+## Architecture
+
+```
+AsyncAPI 2.6 / 3.0 / 3.1 (YAML/JSON)
+        │ parse (2.x/3.0 normalized into the 3.x-shaped model; source version kept)
+        ▼
+Lutaml::Asyncapi::Document            (lossless: mapped roots + map_unmapped)
+        │                              round-trip goes through to_json —
+        │                              Serializable#to_hash emits attribute names
+        ├─► typed views (channels, operations, messages) on demand
+        └─► metanorma-plugin-asyncapi (M3): preprocessor splice — block
+            processors can never yield sections (Parser.parse_blocks limit)
+```
+
+## Milestones
+
+- **M0 — model seed (this repo)**: `Lutaml::Asyncapi.parse` (Yeptris
+  YAML/JSON by sniffing, version detect), `Document` (3.x shape,
+  `map_unmapped` extensions), lossless round-trip goldens from the corpus.
+  Done-when: 15/17 goldens green, rubocop clean, CI green.
+- **M1 — full typed model**: typed views for channels/operations/messages/
+  components incl. Multi Format Schema, bindings, security schemes; 2.6
+  frontend (embedded publish/subscribe → operation view, like Oas30).
+  Done-when: every spec object has a typed accessor and a spec.
+- **M2 — validation**: offline meta-schema checks against the vendored
+  asyncapi/spec-json-schemas (lutaml-jsonschema precedent, JSON Pointer
+  error paths).
+- **M3 — metanorma-plugin-asyncapi**: renderer + preprocessor; OGC
+  connected-systems part 2 and EDR pubsub as the acceptance corpus.
+- **M4 — SPA frontend**: single-file human documentation (lutaml-xsd /
+  lutaml-jsonschema precedent).
+
+## Standing laws
+
+- Losslessness lives on the raw hash; typed views are on-demand.
+- No hand-rolled serialization — lutaml-model mappings only
+  (`map`/`map_unmapped`/attribute serializers).
+- No doubles in specs — real documents from the corpus.
+- Round-trip assertions go through `to_json` (see the `to_hash` gotcha).
+- Versions are the owner's decision; releases only on explicit instruction.

data/README.md

@@ -0,0 +1 @@
+# lutaml-asyncapi

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/asyncapi/document.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Asyncapi
+    # The root AsyncAPI document object, in the 3.x shape.
+    #
+    # Losslessness lives on the raw mapping: every section is kept verbatim
+    # and unmodeled keywords re-emit on serialization (map_unmapped).
+    # Round-trip assertions go through to_json — Serializable#to_hash emits
+    # attribute names, not mapped wire names.
+    class Document < Lutaml::Model::Serializable
+      attribute :asyncapi, :string
+      attribute :id, :string
+      attribute :info, :hash
+      attribute :servers, :hash
+      attribute :default_content_type, :string
+      attribute :channels, :hash
+      attribute :operations, :hash
+      attribute :components, :hash
+      attribute :tags, :hash, collection: true
+      attribute :external_docs, :hash
+      attribute :extensions, :hash, default: -> { {} }
+
+      json do
+        map "asyncapi", to: :asyncapi
+        map "id", to: :id
+        map "info", to: :info
+        map "servers", to: :servers
+        map "defaultContentType", to: :default_content_type
+        map "channels", to: :channels
+        map "operations", to: :operations
+        map "components", to: :components
+        map "tags", to: :tags
+        map "externalDocs", to: :external_docs
+        map_unmapped to: :extensions
+      end
+
+      # The 2.x dialects embed publish/subscribe in channels and carry
+      # root tags/externalDocs; the 3.x model holds them verbatim until
+      # the 2.x frontend (PLAN.md M1) normalizes the operation view.
+      def dialect
+        version = asyncapi.to_s
+        case version
+        when /\A2\./ then "2.x"
+        when /\A3\./ then "3.x"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/asyncapi/version.rb

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

data/lib/lutaml/asyncapi.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "json"
+require "yeptris/yaml"
+require "lutaml/model"
+
+module Lutaml
+  # AsyncAPI 2.6/3.0/3.1 as a lossless lutaml-model.
+  module Asyncapi
+    autoload :Document, "lutaml/asyncapi/document"
+
+    # Parses an AsyncAPI document (YAML or JSON) into a Document.
+    def self.parse(string)
+      data = parse_raw(string)
+      Document.from_json(JSON.generate(data))
+    end
+
+    def self.parse_raw(string)
+      case string
+      when /\A\s*{/
+        JSON.parse(string)
+      else
+        Yeptris::YAML.load(string)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: lutaml-asyncapi
+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-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: nokogiri
+  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: 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 AsyncAPI 2.6/3.0/3.1 documents into lossless LutaML model objects;
+  the model layer for model-based AsyncAPI 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/asyncapi.rb
+- lib/lutaml/asyncapi/document.rb
+- lib/lutaml/asyncapi/version.rb
+homepage: https://github.com/lutaml/lutaml-asyncapi
+licenses:
+- BSD-2-Clause
+metadata:
+  homepage_uri: https://github.com/lutaml/lutaml-asyncapi
+  source_code_uri: https://github.com/lutaml/lutaml-asyncapi
+  changelog_uri: https://github.com/lutaml/lutaml-asyncapi/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: AsyncAPI 2.6/3.0/3.1 as a lossless lutaml-model
+test_files: []