metanorma-mko 1.0.0

data/lib/metanorma/mko/schema/document.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    module Schema
+      class Ids < Lutaml::Model::Serializable
+        attribute :canonical, :string
+        attribute :short, :string
+        # parsed identity (issue #50 follow-up 1): consumers filter and
+        # group on series/number/part — they must never decompose the
+        # canonical string themselves (a silent parse failure on the
+        # consumer side hid a whole corpus lane from retrieval)
+        attribute :series, :string
+        attribute :number, :string
+        attribute :part, :string
+        attribute :docid, :string, collection: true
+        attribute :urn, :string, collection: true
+
+        json do
+          map "canonical", to: :canonical
+          map "short", to: :short
+          map "series", to: :series
+          map "number", to: :number
+          map "part", to: :part
+          map "docid", to: :docid
+          map "urn", to: :urn
+        end
+      end
+
+      class TitleEntry < Lutaml::Model::Serializable
+        attribute :lang, :string
+        attribute :text, :string
+
+        json do
+          map "lang", to: :lang
+          map "text", to: :text
+        end
+      end
+
+      class DateEntry < Lutaml::Model::Serializable
+        attribute :type, :string
+        attribute :on, :string
+
+        json do
+          map "type", to: :type
+          map "on", to: :on
+        end
+      end
+
+      class StatusInfo < Lutaml::Model::Serializable
+        attribute :stage, :string
+        attribute :substage, :string
+        attribute :abbreviation, :string
+
+        json do
+          map "stage", to: :stage
+          map "substage", to: :substage
+          map "abbreviation", to: :abbreviation
+        end
+      end
+
+      class RelationEntry < Lutaml::Model::Serializable
+        attribute :type, :string
+        attribute :to, :string
+
+        json do
+          map "type", to: :type
+          map "to", to: :to
+        end
+      end
+
+      class StructureNode < Lutaml::Model::Serializable
+        attribute :id, :string
+        attribute :number, :string
+        attribute :title, :string
+        attribute :children, StructureNode, collection: true,
+                  default: -> { [] }
+
+        json do
+          map "id", to: :id
+          map "number", to: :number
+          map "title", to: :title
+          map "children", to: :children
+        end
+      end
+
+      # document.json — identity, status, and the numbered structure tree.
+      class Document < Lutaml::Model::Serializable
+        attribute :ids, Ids
+        attribute :flavor, :string
+        attribute :doctype, :string
+        attribute :titles, TitleEntry, collection: true
+        attribute :edition, :string
+        attribute :languages, :string, collection: true
+        attribute :status, StatusInfo
+        # derived from succession edges (Relaton relations verbatim) —
+        # authoritative over the hand-entered status field when present
+        attribute :derived_status, :string
+        attribute :dates, DateEntry, collection: true
+        attribute :relations, RelationEntry, collection: true
+        attribute :structure, StructureNode, collection: true
+
+        json do
+          map "ids", to: :ids
+          map "flavor", to: :flavor
+          map "doctype", to: :doctype
+          map "titles", to: :titles
+          map "edition", to: :edition
+          map "languages", to: :languages
+          map "status", to: :status
+          map "derived_status", to: :derived_status, render_nil: false
+          map "dates", to: :dates
+          map "relations", to: :relations
+          map "structure", to: :structure
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mko/schema/edge.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    module Schema
+      # One graph edge between knowledge objects (or an external key).
+      # Kinds: part_of, cites, defines, tested_by, class_of, amends,
+      # variant_of, supersedes.
+      class Edge < Lutaml::Model::Serializable
+        attribute :from, :string
+        attribute :to, :string
+        attribute :kind, :string
+
+        json do
+          map "from", to: :from
+          map "to", to: :to
+          map "kind", to: :kind
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mko/schema/identifiers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    module Schema
+      # identifiers.json — the document's identifiers; `parsed` carries
+      # the pubid monogem's native JSON when a flavor covers it.
+      class IdentifierInfo < Lutaml::Model::Serializable
+        attribute :original, :string
+        attribute :type, :string
+        attribute :primary, :boolean
+        attribute :parsed, :hash
+
+        json do
+          map "original", to: :original
+          map "type", to: :type
+          map "primary", to: :primary
+          map "parsed", to: :parsed
+        end
+      end
+
+      class Identifiers < Lutaml::Model::Serializable
+        attribute :identifiers, IdentifierInfo, collection: true
+
+        json do
+          map "identifiers", to: :identifiers
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mko/schema/json_schema.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    module Schema
+      # JSON Schema (draft 2020-12) generation for the MKO wire
+      # contract. The lutaml schema classes are the single source of
+      # truth: types come from the attribute declarations, wire names
+      # from the classes' json mappings (e.g. :klass renders as
+      # "class"). Consumers validate against these schemas — never
+      # against hand-written copies that drift.
+      module JsonSchema
+        PRIMITIVES = {
+          "Lutaml::Model::Type::String" => { "type" => "string" },
+          "Lutaml::Model::Type::Integer" => { "type" => "integer" },
+          "Lutaml::Model::Type::Boolean" => { "type" => "boolean" },
+          "Lutaml::Model::Type::Hash" => { "type" => "object" },
+        }.freeze
+
+        class << self
+          def schema_for(klass, seen = {})
+            return { "$ref" => seen[klass] } if seen.key?(klass)
+
+            seen[klass] = "#"
+            properties = klass.attributes.each_with_object({}) do |(name, attr), h|
+              h[wire_name(klass, name)] = property_for(attr, seen)
+            end
+            {
+              "$schema" => "https://json-schema.org/draft/2020-12/schema",
+              "title" => klass.name.to_s.split("::").last,
+              "type" => "object",
+              "properties" => properties,
+            }
+          end
+
+          # The published contract: one schema per wire component and
+          # per typed payload, plus the consumer excerpt.
+          def all
+            Unit # trigger payload-class autoloads
+            schemas = {
+              "unit" => schema_for(Unit),
+              "edge" => schema_for(Edge),
+              "manifest" => schema_for(Manifest),
+              "document" => schema_for(Document),
+              "identifiers" => schema_for(Identifiers),
+              "collection" => schema_for(Schema::Collection),
+              "payload-table" => schema_for(TablePayload),
+              "payload-formula" => schema_for(FormulaPayload),
+              "payload-figure" => schema_for(FigurePayload),
+              "payload-term" => schema_for(TermPayload),
+              "payload-requirement" => schema_for(RequirementPayload),
+              "payload-reference" => schema_for(ReferencePayload),
+              "payload-clause" => schema_for(SectionPayload),
+              "payload-annex" => schema_for(SectionPayload),
+            }
+            schemas["excerpt"] = excerpt_schema(schemas)
+            schemas
+          end
+
+          # Consumer clause: text with [[u:…]] references plus resolved
+          # producer payload blocks (MN 116 §consumer-refs).
+          def excerpt_schema(payload_schemas)
+            block = {
+              "type" => "object",
+              "properties" => {
+                "unit_id" => { "type" => "string", "pattern" => "\\Au:" },
+                "type" => { "type" => "string" },
+                "docidentifier" => { "type" => "string" },
+                "edition" => { "type" => "string" },
+                "payload" => {
+                  "oneOf" => payload_schemas
+                    .select { |name, _| name.start_with?("payload-") }
+                    .map { |_, s| s }.uniq,
+                },
+              },
+              "required" => %w[unit_id type payload],
+            }
+            {
+              "$schema" => "https://json-schema.org/draft/2020-12/schema",
+              "title" => "Excerpt",
+              "type" => "object",
+              "properties" => {
+                "text" => { "type" => "string" },
+                "blocks" => { "type" => "array", "items" => block },
+              },
+              "required" => %w[text blocks],
+            }
+          end
+
+          private
+
+          def property_for(attr, seen)
+            type = primitive(attr) || schema_for(attr.type, seen)
+            attr.collection? ? { "type" => "array", "items" => type } : type
+          end
+
+          def primitive(attr)
+            PRIMITIVES[attr.type.name.to_s]
+          end
+
+          # The json mappings are the wire contract; the attribute name
+          # is only the Ruby-side handle.
+          def wire_name(klass, attr_name)
+            wire_names(klass)[attr_name] || attr_name.to_s
+          end
+
+          def wire_names(klass)
+            @wire_names ||= {}
+            @wire_names[klass] ||= begin
+              mapping = klass.mappings_for(:json)
+              mapping.mappings_hash.values.each_with_object({}) do |rule, h|
+                h[rule.to] = rule.name.to_s
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mko/schema/manifest.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    module Schema
+      class ManifestComponent < Lutaml::Model::Serializable
+        attribute :name, :string
+        attribute :file, :string
+        attribute :media_type, :string
+        attribute :count, :integer
+        attribute :hash, :string
+
+        json do
+          map "name", to: :name
+          map "file", to: :file
+          map "media_type", to: :media_type
+          map "count", to: :count
+          map "hash", to: :hash
+        end
+      end
+
+      class Generated < Lutaml::Model::Serializable
+        attribute :tool, :string
+        attribute :schema_version, :string
+        attribute :flavor, :string
+        attribute :timestamp, :string
+
+        json do
+          map "tool", to: :tool
+          map "schema_version", to: :schema_version
+          map "flavor", to: :flavor
+          map "timestamp", to: :timestamp
+        end
+      end
+
+      class Manifest < Lutaml::Model::Serializable
+        attribute :schema, :string
+        attribute :schema_version, :string
+        attribute :generated, Generated
+        attribute :source_file, :string
+        attribute :source_hash, :string
+        attribute :components, ManifestComponent, collection: true
+        attribute :license, :string
+        attribute :copyright, :string
+
+        json do
+          map "schema", to: :schema
+          map "schema_version", to: :schema_version
+          map "generated", to: :generated
+          map "source", to: :source_file
+          map "source-hash", to: :source_hash
+          map "components", to: :components
+          map "license", to: :license
+          map "copyright", to: :copyright
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mko/schema/unit.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    module Schema
+      class TableColumn < Lutaml::Model::Serializable
+        attribute :label, :string
+        # typed column: unit references the units register (#55 GAP-2)
+        attribute :type, :string
+        attribute :unit, :string
+        attribute :units, :string
+
+        json do
+          map "label", to: :label
+          map "type", to: :type, render_nil: false
+          map "unit", to: :unit, render_nil: false
+          map "units", to: :units, render_nil: false
+        end
+      end
+
+      class TablePayload < Lutaml::Model::Serializable
+        attribute :caption, :string
+        attribute :columns, TableColumn, collection: true
+        attribute :rows, :string, collection: true, default: -> { [] }
+        # The block's native JSON object — the Mirror node tree
+        # (lossless; the serialization the JS renderer consumes).
+        # Provenance/fidelity, not an embedding form: the retrieval
+        # contract is the typed text fields.
+        attribute :mirror, :hash
+
+        json do
+          map "caption", to: :caption
+          map "columns", to: :columns
+          map "rows", to: :rows
+          map "mirror", to: :mirror
+        end
+
+        def embed_text
+          cols = columns.map { |c| c.label + (c.unit ? " [#{c.unit}]" : "") }
+            .join(", ")
+          "Table: #{caption}; columns: #{cols}; " +
+            rows.map { |r| "row: #{r}" }.join(" | ")
+        end
+      end
+
+      class FormulaPayload < Lutaml::Model::Serializable
+        attribute :asciimath, :string
+        attribute :mathml, :string
+        # units register references (units.jsonl entry ids)
+        attribute :units, :string, collection: true, default: -> { [] }
+        # reserved: evaluation forms (typed params + expression in a
+        # declared language); absent unless authored (#55 GAP-3)
+        attribute :semantics, :hash
+        attribute :description, :string
+
+        # Derived encodings — never canonical; each names its converter
+        # (#55: re-encoding at the producer is a provenance break)
+        class DerivedForm < Lutaml::Model::Serializable
+          attribute :form, :string
+          attribute :converter, :string
+
+          json do
+            map "form", to: :form
+            map "converter", to: :converter
+          end
+        end
+        attribute :latex, DerivedForm
+        attribute :omml, DerivedForm
+
+        json do
+          map "asciimath", to: :asciimath
+          map "mathml", to: :mathml
+          map "units", to: :units, render_empty: false
+          map "semantics", to: :semantics, render_nil: false
+          map "latex", to: :latex, render_nil: false
+          map "omml", to: :omml, render_nil: false
+          map "description", to: :description
+        end
+      end
+
+      class FigurePayload < Lutaml::Model::Serializable
+        attribute :alt, :string
+        attribute :uri, :string
+        # hash-addressed bundle asset ("assets/<sha256>"), when bytes
+        # were available at export (data URIs or assets_from)
+        attribute :asset, :string
+        attribute :caption, :string
+        # Native JSON object: the Mirror node tree (see TablePayload).
+        attribute :mirror, :hash
+
+        json do
+          map "alt", to: :alt
+          map "asset", to: :asset
+          map "uri", to: :uri
+          map "caption", to: :caption
+          map "mirror", to: :mirror
+        end
+      end
+
+      class TermSourceEntry < Lutaml::Model::Serializable
+        attribute :citeas, :string
+
+        json do
+          map "citeas", to: :citeas
+        end
+      end
+
+      class TermPayload < Lutaml::Model::Serializable
+        attribute :concept, :string
+        attribute :designations, :string, collection: true, default: -> { [] }
+        attribute :admitted, :string, collection: true, default: -> { [] }
+        attribute :deprecated, :string, collection: true, default: -> { [] }
+        attribute :definition, :string
+        attribute :sources, TermSourceEntry, collection: true, default: -> { [] }
+
+        json do
+          map "concept", to: :concept
+          map "designations", to: :designations
+          map "admitted", to: :admitted, render_empty: false
+          map "deprecated", to: :deprecated, render_empty: false
+          map "definition", to: :definition
+          map "sources", to: :sources
+        end
+      end
+
+      class RequirementPayload < Lutaml::Model::Serializable
+        attribute :identifier, :string
+        attribute :klass, :string
+        attribute :obligation, :string
+        attribute :subject, :string
+        attribute :statement, :string
+        attribute :inherits, :string, collection: true, default: -> { [] }
+
+        json do
+          map "identifier", to: :identifier
+          map "class", to: :klass
+          map "obligation", to: :obligation
+          map "subject", to: :subject
+          map "statement", to: :statement
+          map "inherits", to: :inherits
+        end
+      end
+
+      # Coverage of a section unit (#56): the deterministic summary and
+      # the ordered membership. Children are unit ids in document order;
+      # the same relation the part_of edges carry bottom-up, given here
+      # top-down so tree navigation never re-derives structure from
+      # anchor strings.
+      class SectionPayload < Lutaml::Model::Serializable
+        # deterministic composition (title + covered sub-clauses) —
+        # never model-inferred; consumers may override with their own
+        # LLM summaries, but the default requires none
+        attribute :summary, :string
+        attribute :children, :string, collection: true, default: -> { [] }
+
+        json do
+          map "summary", to: :summary
+          map "children", to: :children
+        end
+      end
+
+      class ReferencePayload < Lutaml::Model::Serializable
+        attribute :key, :string
+        attribute :cited, :string
+
+        json do
+          map "key", to: :key
+          map "cited", to: :cited
+        end
+      end
+
+      # One knowledge object. payload is one of the typed payloads above,
+      # chosen by type. text is the human-readable display text.
+      class Unit < Lutaml::Model::Serializable
+        attribute :id, :string
+        attribute :type, :string
+        attribute :anchor, :string
+        attribute :number, :string
+        # document order as an integer (#56): reading order is a sort,
+        # never a parse of dotted anchor strings. Position, not content —
+        # excluded from the content hash by contract.
+        attribute :ordinal, :integer
+        # the anchor a READER cites (issue #50 follow-up 2): the parent
+        # clause number for embedded objects (tables/formulas/figures),
+        # the unit's own number for top-level sections. Consumers cite
+        # identically without walking the parent chain.
+        attribute :cite_as, :string
+        attribute :title, :string
+        attribute :parent, :string
+        attribute :breadcrumb, :string, collection: true, default: -> { [] }
+        attribute :obligation, :string
+        attribute :lang, :string
+        # authoring-time situating note (#53 item 7): AI-assisted,
+        # editor-approved, versioned with the document. Wire-ready —
+        # emitted the day the authoring system ships it.
+        attribute :ai_note, :string
+        attribute :text, :string
+        attribute :payload, :hash
+        attribute :hash, :string
+
+        json do
+          map "id", to: :id
+          map "type", to: :type
+          map "anchor", to: :anchor
+          map "number", to: :number
+          map "ordinal", to: :ordinal, render_nil: false
+          map "cite_as", to: :cite_as
+          map "title", to: :title
+          map "parent", to: :parent
+          map "breadcrumb", to: :breadcrumb
+          map "obligation", to: :obligation
+          map "lang", to: :lang
+          map "ai_note", to: :ai_note, render_nil: false
+          map "text", to: :text
+          map "payload", to: :payload
+          map "hash", to: :hash
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mko/schema.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mko
+    # The MKO wire schema. Every class is a lutaml-model Serializable with
+    # JSON mappings — one schema, framework-generated serializations only.
+    module Schema
+      autoload :Manifest, "metanorma/mko/schema/manifest"
+      autoload :Document, "metanorma/mko/schema/document"
+      autoload :StructureNode, "metanorma/mko/schema/document"
+      autoload :Unit, "metanorma/mko/schema/unit"
+      autoload :Edge, "metanorma/mko/schema/edge"
+      autoload :Identifiers, "metanorma/mko/schema/identifiers"
+      autoload :JsonSchema, "metanorma/mko/schema/json_schema"
+      autoload :Collection, "metanorma/mko/schema/collection"
+      autoload :CollectionMember, "metanorma/mko/schema/collection"
+      autoload :IdentifierInfo, "metanorma/mko/schema/identifiers"
+    end
+  end
+end