lutaml-lml 0.2.0 → 0.3.0

data/lib/lutaml/lml/layout/elk_svg_markers.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Layout
+    # SVG arrow-marker vocabulary and the <defs> block for ElkSvgRenderer.
+    # Marker ids are keyed by association member_end_type.
+    module ElkSvgMarkers
+      EDGE_STROKE = '#666666'
+
+      ARROW_MARKERS = {
+        'association' => 'arrow',
+        'aggregation' => 'diamond',
+        'composition' => 'diamond_filled',
+        'generalization' => 'triangle',
+        'uses' => 'arrow',
+        'direct' => 'arrow'
+      }.freeze
+
+      MARKER_SHAPES = {
+        'arrow' => %(<path d="M 0 0 L 10 5 L 0 10 z" fill="#{EDGE_STROKE}"/>),
+        'triangle' => %(<path d="M 0 0 L 12 5 L 0 10 z" fill="white" stroke="#{EDGE_STROKE}"/>),
+        'diamond' => %(<path d="M 0 4 L 7 0 L 14 4 L 7 8 z" fill="white" stroke="#{EDGE_STROKE}"/>),
+        'diamond_filled' => %(<path d="M 0 4 L 7 0 L 14 4 L 7 8 z" fill="#{EDGE_STROKE}"/>)
+      }.freeze
+
+      def arrow_marker(edge)
+        edge_type = edge.properties&.fetch('member_end_type', nil)
+        ARROW_MARKERS.fetch(edge_type.to_s, 'arrow')
+      end
+
+      def defs
+        MARKER_SHAPES.filter_map { |id, path| marker_def(id, path) }.join("\n")
+      end
+
+      private
+
+      def marker_def(id, path)
+        w, h = id.start_with?('diamond') ? %w[14 8] : %w[10 10]
+        %(<marker id="#{id}" viewBox="0 0 #{w} #{h}" refX="9" refY="4" ) +
+          %(markerWidth="#{w}" markerHeight="#{h}" ) +
+          %(orient="auto-start-reverse">#{path}</marker>)
+      end
+    end
+  end
+end

data/lib/lutaml/lml/layout/elk_svg_renderer.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Layout
+    # Renders a laid-out Elkrb::Graph (nodes positioned by the layout) as
+    # standalone SVG: rounded-rect nodes with text-line labels and
+    # polyline edges with per-type arrow markers.
+    class ElkSvgRenderer
+      include ElkSvgMarkers
+
+      EDGE_STROKE = ElkSvgMarkers::EDGE_STROKE
+
+      HEADER = <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="%<width>s" height="%<height>s" viewBox="0 0 %<width>s %<height>s">
+      XML
+      NODE_FILL = '#f8f8f8'
+      NODE_STROKE = '#333333'
+
+      def render(graph)
+        @graph = graph
+        @out = +''
+        @out << format(HEADER, width: bounds_width, height: bounds_height)
+        @out << "<defs>\n#{defs}\n</defs>\n"
+        nodes
+        edges
+        @out << "</svg>\n"
+        @out
+      end
+
+      private
+
+      def nodes
+        @graph.children.each { |node| render_node(node) }
+      end
+
+      def render_node(node)
+        @out << %(<g transform="translate(#{node.x.to_i},#{node.y.to_i})">)
+        @out << node_rect(node)
+        node.labels.each_with_index { |label, i| @out << node_label(label, i) }
+        @out << '</g>'
+      end
+
+      def node_rect(node)
+        %(<rect width="#{node.width.to_i}" height="#{node.height.to_i}" rx="6" ) +
+          %(fill="#{NODE_FILL}" stroke="#{NODE_STROKE}"/>)
+      end
+
+      def node_label(label, index)
+        y = ((index + 0.7) * ElkGraphBuilder::LINE_HEIGHT).round(1)
+        weight = index.zero? ? ' font-weight="bold"' : ''
+        %(<text x="7" y="#{y}" font-family="Helvetica" font-size="12"#{weight}>#{escape(label.text)}</text>)
+      end
+
+      def edges
+        @graph.edges.each { |edge| render_edge(edge) }
+      end
+
+      def render_edge(edge)
+        points = edge_points(edge)
+        return if points.empty?
+
+        @out << edge_polyline(edge, points)
+        edge_label(edge, points)
+      end
+
+      def edge_polyline(edge, points)
+        pts = points.map { |p| "#{p.x.round(1)},#{p.y.round(1)}" }.join(' ')
+        %(<polyline fill="none" stroke="#{EDGE_STROKE}" marker-end="url(##{arrow_marker(edge)})" points="#{pts}"/>)
+      end
+
+      def edge_label(edge, points)
+        label = Array(edge.labels).first
+        return unless label&.text
+
+        @out << edge_label_text(label, edge_anchor(points))
+      end
+
+      def edge_anchor(points)
+        mid = points[points.size / 2]
+        { x: (mid.x + 4).round(1), y: (mid.y - 4).round(1) }
+      end
+
+      def edge_label_text(label, anchor)
+        %(<text x="#{anchor[:x]}" y="#{anchor[:y]}" font-family="Helvetica" ) +
+          %(font-size="10" fill="#{EDGE_STROKE}">#{escape(label.text)}</text>)
+      end
+
+      def edge_points(edge)
+        sections = Array(edge.sections)
+        return [] if sections.empty?
+
+        points = [sections.first.start_point]
+        sections.each do |section|
+          points.concat(Array(section.bend_points))
+          points << section.end_point
+        end
+        points.compact
+      end
+
+      def bounds_width
+        extent(:x, :width) + 20
+      end
+
+      def bounds_height
+        extent(:y, :height) + 20
+      end
+
+      def extent(pos, size)
+        values = @graph.children.map { |n| n.public_send(pos).to_f + n.public_send(size).to_f }
+        [values.max || 0, 0].max.round
+      end
+
+      def escape(text)
+        text.to_s.gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;')
+      end
+    end
+  end
+end

data/lib/lutaml/lml/layout/graph_viz_engine.rb

@@ -7,7 +7,7 @@ module Lutaml
   module Layout
     class GraphVizEngine < Engine
       def render(type)
-        Open3.popen3("dot -T#{type}") do |stdin, stdout, _stderr, _wait|
+        Open3.popen3("dot", "-T#{type}") do |stdin, stdout, _stderr, _wait|
           stdout.binmode
           stdin.puts(input)
           stdin.close

data/lib/lutaml/lml/layout.rb

@@ -4,5 +4,9 @@ module Lutaml
   module Layout
     autoload :Engine, "lutaml/lml/layout/engine"
     autoload :GraphVizEngine, "lutaml/lml/layout/graph_viz_engine"
+    autoload :ElkEngine, "lutaml/lml/layout/elk_engine"
+    autoload :ElkGraphBuilder, "lutaml/lml/layout/elk_graph_builder"
+    autoload :ElkSvgRenderer, "lutaml/lml/layout/elk_svg_renderer"
+    autoload :ElkSvgMarkers, "lutaml/lml/layout/elk_svg_markers"
   end
 end

data/lib/lutaml/lml/model_compiler/enums.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    class ModelCompiler
+      # Compiles LML enums into Serializable subclasses with member
+      # payloads, table-driven expansion, and value accessors.
+      module Enums
+        EnumValue = Struct.new(:name, :description, :payload)
+
+        private
+
+        def compile_enum(enum_def)
+          name = enum_def.name.to_s
+          expand_from_table(enum_def)
+          values = extract_enum_values(enum_def)
+
+          payload_fields = Array(enum_def.member_fields).map(&:name).map(&:to_s)
+          value_names = values.map { |v| v.name.to_s }
+          compiled_klass = Class.new(Lutaml::Model::Serializable) do
+            attribute :value, :string, values: value_names, default: values.first.name
+            attribute :description, :string
+            payload_fields.each do |field|
+              attribute field.to_sym, :string
+            end
+
+            define_method(:to_s) { value }
+          end
+
+          values.each do |value|
+            accessor = value.name.to_s.gsub(/[^a-zA-Z0-9_]/, '_')
+            compiled_klass.define_singleton_method(accessor) do
+              new({ value: value.name, description: value.description }.merge(value.payload || {}))
+            end
+          end
+          compiled_klass.define_singleton_method(:values) { values }
+
+          @enum_names << name
+          @enum_classes[name] = compiled_klass
+          register(name, compiled_klass)
+        end
+
+        # Builds a compiled Serializable subclass from a class or data-type
+        # definition: declares attributes and stashes forward-referenced
+        # attributes for post-registration resolution.
+
+        # RS 3001 §Attribute: `values { v1, v2 }` expands into an anonymous
+        # enum baked from the inline set; the attribute is typed with it.
+        def resolve_values_type(klass_def, attr)
+          return attr.type.to_s unless attr.value_set&.any?
+
+          enum_name = anonymous_enum_name(klass_def.name, attr.name)
+          members = attr.value_set.map { |v| ::Lutaml::Lml::TopElementAttribute.new(name: v.to_s) }
+          compile_enum(::Lutaml::Lml::Enum.new(name: enum_name, attributes: members))
+          enum_name
+        end
+
+        def anonymous_enum_name(class_name, attr_name)
+          base = class_name.to_s.split('::').last
+          attr_part = attr_name.to_s.split('_').map(&:capitalize).join
+          "#{base}#{attr_part}Values"
+        end
+
+        # L7a point 3: from_table members are baked at compile time — the
+        # artifact table's rows become the values, validated against the
+        # declared member_fields (unknown field = error; missing = nil).
+        # The member name comes from the row's "name" column.
+        def expand_from_table(enum_def)
+          return unless enum_def.from_table_name
+
+          rows = artifact_table_rows(enum_def)
+          known = Array(enum_def.member_fields).map { |f| f.name.to_s }
+          rows.each do |row|
+            row = row.transform_keys(&:to_s)
+            member_name = row.fetch('name')
+            unknown = row.keys - known - ['name']
+            if unknown.any?
+              raise ArgumentError,
+                    "enum #{enum_def.name}: table row #{member_name.inspect} has " \
+                    "undeclared fields #{unknown.inspect} (declared: #{known.inspect})"
+            end
+            payload = row.slice(*known).compact
+            enum_def.attributes << TopElementAttribute.new(
+              name: member_name,
+              properties: payload.map do |field, value|
+                TopElementAttribute.new(name: field, value: value)
+              end,
+            )
+          end
+        end
+
+        def artifact_table_rows(enum_def)
+          reference = enum_def.from_table_artifact || @default_artifact
+          path = artifact_path_for(reference.to_s)
+          unless path
+            raise ArgumentError,
+                  "enum #{enum_def.name}: from_table artifact #{reference.inspect} not found"
+          end
+
+          envelope = JSON.parse(File.read(path))
+          table = envelope['tables'].to_h[enum_def.from_table_name]
+          unless table
+            raise ArgumentError,
+                  "enum #{enum_def.name}: table #{enum_def.from_table_name.inspect} " \
+                  "not found in artifact #{reference.inspect}"
+          end
+
+          table['rows'].to_a
+        end
+
+        def extract_enum_values(enum_def)
+          member_fields = Array(enum_def.member_fields).map do |f|
+            [f.name.to_s, f.type.to_s]
+          end
+          enum_def.attributes.map do |attr|
+            description = member_description(attr)
+            payload = extract_member_payload(attr)
+            validate_member_payload(enum_def, attr, payload, member_fields)
+            EnumValue.new(attr.name.to_s, description, payload)
+          end
+        end
+
+        # The member description rides a nested attribute named `description`
+        # (bare-member form) or `definition` (RS 3001 `value` blocks); both
+        # spellings are accepted.
+
+        # The member description rides a nested attribute named `description`
+        # (bare-member form) or `definition` (RS 3001 `value` blocks); both
+        # spellings are accepted.
+        def member_description(attr)
+          nested = Array(attr.attributes).find do |n|
+            %w[description definition].include?(n.name.to_s)
+          end
+          text = nested&.type || nested&.definition || nested&.value
+          text.is_a?(Hash) && text.key?(:string) ? text[:string] : text
+        end
+
+        # L7a: per-member payload lines ride the keyword-attribute
+        # properties (`abbreviation = "WD"`)
+
+        # L7a: per-member payload lines ride the keyword-attribute
+        # properties (`abbreviation = "WD"`)
+        def extract_member_payload(attr)
+          Array(attr.properties).to_h { |p| [p.name.to_s, p.value&.to_s] }
+        end
+
+        def validate_member_payload(enum_def, attr, payload, member_fields)
+          known = member_fields.map(&:first)
+          unknown = payload.keys - known
+          return unless unknown.any?
+
+          raise ArgumentError,
+                "enum #{enum_def.name}: member #{attr.name} has undeclared " \
+                "payload fields #{unknown.inspect} (declared: #{known.inspect})"
+        end
+
+        def enum_class_for(type)
+          type.is_a?(Class) && @enum_classes.value?(type) and return type
+        end
+
+        def enum_value_name(raw)
+          raw.split('::').last
+        end
+
+        # L7b: derived fields declare existence + type; computation is
+        # bound by the binder from artifact derive specs. The attribute
+        # participates in mappings like any other (relaton consumes URNs
+        # from model JSON).
+      end
+    end
+  end
+end

data/lib/lutaml/lml/model_compiler/hydration.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    class ModelCompiler
+      # Builds typed instances from parsed instance documents
+      # against the compiled class set.
+      module Hydration
+        private
+
+        def hydrate_instance(instance)
+          inner = instance.instance
+          return hydrate_instance(inner) if inner && Array(instance.attributes).empty?
+
+          type_name = resolve_instance_type(instance)
+          klass = @compiled[type_name]
+          return hydrate_as_untyped(instance, type_name) unless klass
+
+          attrs = extract_instance_attributes(instance, klass)
+          klass.new(**attrs)
+        end
+
+        # An inline map's cargo is {key_value_map: [{key:, value:}, ...]} with
+        # literal-shaped keys/values ({string: ..}, {number: ..}, {boolean: ..});
+        # materialize it as a plain Hash (issue #17: maps hydrate as data).
+
+        # An inline map's cargo is {key_value_map: [{key:, value:}, ...]} with
+        # literal-shaped keys/values ({string: ..}, {number: ..}, {boolean: ..});
+        # materialize it as a plain Hash (issue #17: maps hydrate as data).
+        def hydrate_map_cargo(cargo)
+          cargo[:key_value_map].to_h do |pair|
+            [hydrate_scalar(pair[:key]).to_s, hydrate_scalar(pair[:value])]
+          end
+        end
+
+        def hydrate_scalar(literal)
+          literal = literal.value if literal.respond_to?(:value)
+          literal.is_a?(Hash) ? literal.values.first : literal
+        end
+
+        def resolve_instance_type(instance)
+          # L6: the explicit isa keyword is the type override; a `type`
+          # attribute is ordinary data (pubid's identifier-kind field)
+          return demodulize(instance.isa.to_s) if instance.isa
+
+          demodulize(instance.type.to_s)
+        end
+
+        def demodulize(name)
+          name.split('::').last.to_s
+        end
+
+        def hydrate_as_untyped(instance, type_name)
+          { _name: type_name, **extract_raw_attributes(instance) }
+        end
+
+        def extract_raw_attributes(instance)
+          instance.each_attribute.with_object({}) do |(name, value, nested), hash|
+            hash[name.to_sym] = resolve_instance_value(value, nested)
+          end
+        end
+
+        def extract_instance_attributes(instance, klass)
+          schema_keys = klass.attributes.keys.to_set
+          instance.each_attribute.with_object({}) do |(name, value, nested), hash|
+            key = name.to_sym
+            next unless schema_keys.include?(key)
+
+            hash[key] = resolve_instance_value(value, nested, klass.attributes[key])
+          end
+        end
+
+        def resolve_instance_value(value, nested, attr_def = nil)
+          value = value.value if value.respond_to?(:value)
+          return hydrate_map_cargo(value) if value.is_a?(Hash) && value.key?(:key_value_map)
+
+          if nested.any?
+            # A scalar attribute with a single nested instance hydrates to
+            # the object itself; the declaration is the truth (issue #17).
+            return hydrate_typed(nested.first, attr_def) if !attr_def&.collection && nested.one?
+
+            nested.map { |i| hydrate_typed(i, attr_def) }
+          # The Array guard must run before the enum branch: an array
+          # value under an enum-typed attribute stays a raw array.
+          # rubocop:disable Lint/DuplicateBranch
+          elsif value.is_a?(Array)
+            value
+          elsif (enum_class = attr_def && enum_class_for(attr_def.type))
+            value_name = enum_value_name(value.to_s)
+            description = enum_class.values
+                                    .find { |v| v.name == value_name }&.description
+            enum_class.new(value: value_name, description: description)
+          elsif !value.nil?
+            value
+            # rubocop:enable Lint/DuplicateBranch
+          end
+        end
+
+        # An untyped nested instance takes the enclosing attribute's type;
+        # hydrate_as_untyped would otherwise emit a raw hash polluted with
+        # a `_name` key, which also defeats union member key-coverage.
+
+        # An untyped nested instance takes the enclosing attribute's type;
+        # hydrate_as_untyped would otherwise emit a raw hash polluted with
+        # a `_name` key, which also defeats union member key-coverage.
+        def hydrate_typed(instance, attr_def)
+          return hydrate_instance(instance) if instance.isa || !instance.type.to_s.empty?
+
+          type = attr_def&.type
+          return hydrate_instance(instance) unless type.is_a?(Class)
+
+          if type.include?(Lutaml::Model::Serialize)
+            type.new(**extract_instance_attributes(instance, type))
+          elsif type == Lutaml::Model::Type::Union
+            extract_raw_attributes(instance)
+          else
+            hydrate_instance(instance)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/model_compiler/serialization_mappings.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    class ModelCompiler
+      # Applies declared LML serialization mappings
+      # (xml / key_value wire names, namespaces) onto compiled classes.
+      module SerializationMappings
+        private
+
+        # In-class `mapping <format> { … }` is the shortcut for a sibling
+        # mapping targeting the enclosing class; hoist them so emission is
+        # uniform.
+        def hoist_class_serialization_mappings(doc)
+          (Array(doc.classes) + Array(doc.data_types)).each do |klass_def|
+            Array(klass_def.serialization_mappings).each do |mapping|
+              mapping.target = klass_def.name.to_s
+              @serialization_mappings << mapping
+            end
+          end
+        end
+
+        # Emit the lutaml-model mapping blocks declared in the LML source:
+        #   mapping yaml { map "full-name", to: "name" }
+        # becomes klass.yml do |m| m.map "full-name", to: :name end
+        def apply_declared_mappings(compiled_klass, def_obj)
+          return unless def_obj.is_a?(UmlClass) || def_obj.is_a?(DataType)
+
+          def_obj.wire_mappings.to_a.group_by(&:format).each do |format, entries|
+            next unless format && Lutaml::Model::FormatRegistry.registered?(format.to_sym)
+
+            compiled_klass.public_send(format) do |mapping|
+              entries.each { |entry| mapping.map(entry.wire, to: entry.to.to_sym) }
+            end
+          end
+        end
+
+        # Apply a lutaml-model XML mapping to each compiled class so they
+        # support from_xml/to_xml. Runs after forward references are resolved
+        # so all attributes (immediate + deferred) get element mappings.
+        def apply_xml_mappings
+          @compiled.each do |name, klass|
+            next if @enum_names.include?(name)
+
+            custom = serialization_mapping_for(name, 'xml')
+            next apply_custom_xml_mapping(klass, custom) if custom
+
+            apply_xml_mapping(klass, name)
+          end
+        end
+
+        def apply_xml_mapping(klass, root_name)
+          attr_names = klass.attributes.keys
+          return if attr_names.empty?
+
+          klass.xml do |mapping|
+            mapping.element(root_name)
+            attr_names.each do |attr_name|
+              mapping.map_element(attr_name.to_s, to: attr_name)
+            end
+          end
+        end
+
+        # RS 3010 extension: key-value mapping blocks for the declared
+        # formats (yaml/json/toml share lutaml-model's key_value model).
+
+        # RS 3010 extension: key-value mapping blocks for the declared
+        # formats (yaml/json/toml share lutaml-model's key_value model).
+        def apply_key_value_mappings
+          @compiled.each do |name, klass|
+            next if @enum_names.include?(name)
+
+            custom = serialization_mapping_for(name, 'key_value')
+            apply_custom_key_value_mapping(klass, custom) if custom
+          end
+        end
+
+        def serialization_mapping_for(target, format)
+          @serialization_mappings.find do |m|
+            m.target.to_s == target && serialization_format(m.format) == format
+          end
+        end
+
+        def serialization_format(format)
+          %w[yaml json toml].include?(format.to_s) ? 'key_value' : format.to_s
+        end
+
+        def apply_custom_xml_mapping(klass, mapping)
+          check_namespace_ambiguity(mapping)
+          ns_class = namespace_class_for(mapping.namespace_ref) if mapping.namespace_ref
+          rule_ns = mapping.rules.select { |r| r.kind == 'namespace' }
+                                 .to_h { |r| [r.field, namespace_class_for(r.field)] }
+          klass.xml do |m|
+            m.element(mapping.element_name) if mapping.element_name
+            m.namespace(ns_class) if ns_class
+            m.mixed_content if mapping.mixed_content
+            mapping.rules.each do |rule|
+              case rule.kind
+              when 'element' then m.map_element(rule.wire, to: rule.field.to_sym)
+              when 'attribute' then m.map_attribute(rule.wire, to: rule.field.to_sym)
+              when 'content' then m.map_content(to: rule.field.to_sym)
+              when 'namespace' then m.namespace(rule_ns[rule.field])
+              end
+            end
+          end
+        end
+
+        def apply_custom_key_value_mapping(klass, mapping)
+          formats = mapping.format.to_s == 'key_value' ? %w[yaml json toml] : [mapping.format.to_s]
+          klass.instance_eval do
+            formats.each do |format|
+              public_send(format) do |m|
+                mapping.rules.each do |rule|
+                  case rule.kind
+                  when 'map' then m.map(rule.wire, to: rule.field.to_sym)
+                  when 'key' then m.map_key(to_instance: rule.field.to_sym)
+                  when 'value'
+                    if rule.mode == 'as_attribute'
+                      m.map_value(as_attribute: rule.field.to_sym)
+                    else
+                      m.map_value(to_instance: rule.field.to_sym)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        def check_namespace_ambiguity(mapping)
+          return unless mapping.format.to_s == 'xml'
+          return if mapping.namespace_ref || @declared_namespaces.length < 2
+
+          raise ArgumentError,
+                "mapping #{mapping.format} #{mapping.target}: ambiguous default " \
+                "namespace — #{@declared_namespaces.length} namespaces in scope " \
+                "(#{@declared_namespaces.map(&:name).join(', ')}); declare one with " \
+                "'namespace <name>'"
+        end
+
+        def namespace_class_for(ref)
+          return nil if ref.nil?
+
+          require 'lutaml/xml/namespace' unless defined?(Lutaml::Xml::Namespace)
+
+          ns_class = @namespace_classes[ref]
+          return ns_class if ns_class
+
+          declared = @declared_namespaces.find { |ns| ns.name.to_s == ref }
+          raise ArgumentError, "unknown namespace '#{ref}'" unless declared
+
+          ns_class = Class.new(Lutaml::Xml::Namespace)
+          uri = declared.uri
+          prefix = declared.prefix.to_s
+          ns_class.define_singleton_method(:uri) { uri }
+          ns_class.define_singleton_method(:prefix_default) { prefix }
+          @namespace_classes[ref] = ns_class
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/model_compiler/string_formats.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    class ModelCompiler
+      # Registers declared string_format handlers on
+      # compiled classes.
+      module StringFormats
+        private
+
+        # L5: register grammar-backed string formats. Class-level
+        # declarations win; a models-block default applies to classes
+        # without their own. Artifact resolution: the compiler's
+        # artifacts map (name => path), else the string as a path.
+        def register_string_formats(doc)
+          defaults = doc.packages.flat_map(&:default_string_formats)
+          doc.classes.each do |class_def|
+            declared = Array(class_def.string_formats)
+            declared.each { |fmt| register_string_format(class_def.name.to_s, fmt) }
+
+            declared_formats = declared.map(&:format)
+            defaults.reject { |fmt| declared_formats.include?(fmt.format) }
+                    .each { |fmt| register_string_format(class_def.name.to_s, fmt) }
+          end
+        end
+
+        def register_string_format(class_name, fmt)
+          artifact_path = artifact_path_for(fmt.artifact.to_s)
+          return unless artifact_path
+
+          compiled = @compiled[class_name]
+          return unless compiled
+
+          Parsanol::PARG::Lutaml.register(compiled,
+                                          format_name: fmt.format.to_sym,
+                                          artifact: artifact_path,
+                                          entry: fmt.root.to_s)
+        end
+      end
+    end
+  end
+end