newsmlg2 0.1.1

data/lib/newsmlg2/configuration.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Newsmlg2
+  # Registry of the NewsML-G2 root models in a lutaml-model global context,
+  # keyed by element id. This is the single source of truth for
+  # element-name → class resolution (root dispatch, itemSet items) —
+  # following the plurimath/mml pattern, library code never compares
+  # element-name strings itself.
+  module Configuration
+    CONTEXT_ID = :newsmlg2
+
+    class << self
+      def context
+        Lutaml::Model::GlobalContext.context(CONTEXT_ID)
+      end
+
+      # Rebuilds the built-in context from the registered models.
+      def populate_context!
+        Lutaml::Model::GlobalContext.unregister_context(CONTEXT_ID) if context
+        type_context = Lutaml::Model::GlobalContext.create_context(
+          id: CONTEXT_ID,
+          registry: Lutaml::Model::TypeRegistry.new,
+          fallback_to: [:default]
+        )
+        register_models_in(type_context)
+        Lutaml::Model::GlobalContext.clear_caches
+        type_context
+      end
+
+      # Registers a model under its element id (see the registration block
+      # at the bottom of lib/newsmlg2.rb).
+      def register_model(klass, id:)
+        normalized_id = id.to_sym
+        registered_models[normalized_id] = klass
+        (context || populate_context!).registry.register(normalized_id, klass)
+        klass
+      end
+
+      # Resolves an element name to its registered model class, or nil for
+      # unregistered names (non-element nodes, foreign roots).
+      def resolve(element_name)
+        name = element_name.to_sym
+        return nil unless Lutaml::Model::GlobalContext.resolvable?(name, CONTEXT_ID)
+
+        Lutaml::Model::GlobalContext.resolve_type(name, CONTEXT_ID)
+      end
+
+      private
+
+      def register_models_in(type_context)
+        registered_models.each do |model_id, klass|
+          type_context.registry.register(model_id, klass)
+        end
+      end
+
+      def registered_models
+        @registered_models ||= {}
+      end
+    end
+  end
+end

data/lib/newsmlg2/document.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Newsmlg2
+  # The NewsML-G2 document entry point: parses XML into a typed item (or
+  # newsMessage), exposes it, and serializes back to XML. Each document owns
+  # its CatalogStore, built from inline catalogs and catalogRefs.
+  #
+  #   doc = Newsmlg2.parse(xml)      # or Newsmlg2.parse_file(path)
+  #   doc.item                       # => Newsmlg2::NewsItem
+  #   doc.item.content_meta.headlines.first
+  #   doc.catalog_store.get_scheme_for_alias("ninat")
+  #   doc.to_xml                     # => declaration + item XML
+  #
+  # Root dispatch and itemSet resolution go through the Configuration
+  # registry; all model parsing is lutaml-model's from_xml. The gem never
+  # references a specific XML parser — the adapter is the consumer's
+  # choice via Lutaml::Model::Config.
+  class Document
+    class << self
+      # Parses NewsML-G2 XML into a Document.
+      def parse(xml)
+        with_resolved_adapter do
+          root_name, klass = root_class(xml)
+          unless klass
+            raise UnknownRootElement,
+                  "'#{root_name}' is not a NewsML-G2 item or newsMessage root element"
+          end
+
+          new(klass.from_xml(xml))
+        end
+      end
+
+      # Parses a NewsML-G2 XML file into a Document.
+      def parse_file(path)
+        parse(File.read(path))
+      end
+
+      private
+
+      # Runs the block with the consumer's configured XML adapter; if none
+      # resolves (fresh install, unconfigured default), falls back to the
+      # REXML adapter, which ships with Ruby — the gem never depends on a
+      # specific parser.
+      def with_resolved_adapter(&)
+        Lutaml::Model::Config.adapter_for(:xml)
+        yield
+      rescue Lutaml::Model::UnknownAdapterTypeError, LoadError
+        Lutaml::Model::Config.with_adapter(xml: :rexml, &)
+      end
+
+      # NewsML-G2 has eight possible root elements and lutaml-model has no
+      # multi-root dispatch, so the document's root element name is read
+      # once through the configured adapter and resolved to its registered
+      # model class. No element-name strings live in this file — the
+      # registry (lib/newsmlg2.rb registration block) is the single source
+      # of truth.
+      def root_class(xml)
+        root = Lutaml::Model::Config.adapter_for(:xml).parse(xml).root
+        name = root.name.sub(/\A[\w.-]+:/, '')
+        [name, Configuration.resolve(name)]
+      rescue StandardError
+        ['', nil]
+      end
+    end
+
+    attr_reader :item
+
+    # @param item [Newsmlg2::AnyItem, Newsmlg2::NewsMessage]
+    def initialize(item = nil)
+      @item = item
+      @catalog_store = CatalogStore.new
+      load_catalogs
+    end
+
+    # Replaces the document's item and rebuilds its catalog store.
+    def item=(new_item)
+      unless new_item.is_a?(AnyItem) || new_item.is_a?(NewsMessage)
+        raise ArgumentError,
+              "expected a Newsmlg2 item or NewsMessage, got #{new_item.class}"
+      end
+
+      @item = new_item
+      @catalog_store = CatalogStore.new
+      load_catalogs
+    end
+
+    # The catalogs known to this document (inline catalogs plus catalogRefs
+    # resolvable through the bundled IPTC catalog cache).
+    def catalog_store
+      @catalog_store ||= CatalogStore.new.tap { |store| load_catalogs_into(store) }
+    end
+
+    # Serializes the document: XML declaration plus the item, validating that
+    # a guid is present (items only).
+    def to_xml(**options)
+      item.validate! if item.is_a?(AnyItem)
+      item.to_xml({ declaration: true }.merge(options))
+    end
+    alias to_xml_string to_xml
+
+    private
+
+    def load_catalogs
+      load_catalogs_into(catalog_store)
+    end
+
+    def load_catalogs_into(store)
+      return unless item
+
+      case item
+      when AnyItem then load_catalog_holders(store, item)
+      when NewsMessage then load_catalog_holders(store, item.header)
+      end
+    end
+
+    def load_catalog_holders(store, holder)
+      return unless holder
+
+      holder.catalogs.to_a.each { |catalog| store.add_catalog(catalog) }
+      holder.catalog_refs.to_a.each { |ref| store.add_catalog_ref(ref.href) }
+    end
+  end
+end

data/lib/newsmlg2/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Newsmlg2
+  class Error < StandardError; end
+
+  # No catalog known to the document declares this scheme alias.
+  class AliasNotFoundInCatalogs < Error; end
+
+  # No catalog known to the document declares this scheme URI.
+  class UriNotFoundInCatalogs < Error; end
+  URINotFoundInCatalogs = UriNotFoundInCatalogs
+
+  # The parsed root element is not a NewsML-G2 item or newsMessage.
+  class UnknownRootElement < Error; end
+
+  # An item without a guid cannot be serialized.
+  class MissingGuidError < Error; end
+end

data/lib/newsmlg2/i18n.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Newsmlg2
+  # Helpers for multi-language content collections (elements carrying
+  # xml:lang, such as ConceptNameType values).
+  module I18n
+    module_function
+
+    # The languages used by a collection of localized elements.
+    def languages(collection)
+      collection.filter_map(&:xml_lang).uniq
+    end
+
+    # The first element of the collection matching the given language tag
+    # (exact match), or nil.
+    def for_language(collection, lang)
+      collection.find { |item| item.xml_lang == lang }
+    end
+  end
+end

data/lib/newsmlg2/items/any_item.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Newsmlg2
+  # An action which is executed at this hop in the hop history.
+  class Action < Newsmlg2::Types::QualRelPropType
+    xml_attributes :target, :targeturi, :timestamp
+
+    xml do
+      element 'action'
+    end
+  end
+
+  # A single hop of the Hop History.
+  class Hop < Newsmlg2::NarModel
+    include Newsmlg2::Base::CommonPowerAttributes
+
+    xml_attributes :seq, :timestamp
+
+    xml_element :parties, xml: 'party',
+                          type: Newsmlg2::Types::Party, collection: true
+    xml_element :actions, xml: 'action',
+                          type: Newsmlg2::Action, collection: true
+
+    xml do
+      element 'hop'
+    end
+  end
+
+  # A history of the creation and modifications of the content object of
+  # this item, expressed as a sequence of hops.
+  class HopHistory < Newsmlg2::NarModel
+    xml_element :hops, xml: 'hop', type: Newsmlg2::Hop, collection: true
+
+    xml do
+      element 'hopHistory'
+    end
+  end
+
+  # Time stamp representing an optionally truncated date and time.
+  class Timestamp < Newsmlg2::Types::TruncatedDateTimePropType
+    xml do
+      element 'timestamp'
+    end
+  end
+
+  # A step in the pubHistory.
+  class Published < Newsmlg2::NarModel
+    include Newsmlg2::Base::CommonPowerAttributes
+
+    xml_attributes :qcode, :uri, :literal
+
+    xml_element :timestamp, xml: 'timestamp',
+                            type: Newsmlg2::Timestamp
+    xml_element :names, xml: 'name',
+                        type: Newsmlg2::Types::ConceptNameType, collection: true
+    xml_element :related, xml: 'related',
+                          type: Newsmlg2::Types::Related, collection: true
+    xml_element :published_ext_properties, xml: 'publishedExtProperty',
+                                           type: Newsmlg2::Types::Flex2ExtPropType, collection: true
+
+    xml do
+      element 'published'
+    end
+  end
+
+  # One to many datasets about publishing this item.
+  class PubHistory < Newsmlg2::NarModel
+    xml_element :published, xml: 'published',
+                            type: Newsmlg2::Published, collection: true
+
+    xml do
+      element 'pubHistory'
+    end
+  end
+
+  # An assertion about a concept. XSD AssertType carries xs:any ##any
+  # content — NAR-namespace properties (name, geoAreaDetails, …) or
+  # provider extensions — preserved verbatim in #content.
+  class Assert < Newsmlg2::NarModel
+    include Newsmlg2::Base::CommonPowerAttributes
+    include Newsmlg2::Base::I18NAttributes
+
+    xml_attributes :qcode, :uri, :literal
+
+    attribute :content, :string
+
+    xml do
+      element 'assert'
+      map_all to: :content
+    end
+  end
+
+  # Inline reference: the concept represented by the content identified by
+  # the local identifier(s).
+  class InlineRef < Newsmlg2::Types::Flex1PropType
+    include Newsmlg2::Base::QuantifyAttributes
+
+    xml_attributes :idrefs
+
+    xml do
+      element 'inlineRef'
+    end
+  end
+
+  # Refers to the ids of elements whose values have been derived from the
+  # concept represented by this property.
+  class DerivedFrom < Newsmlg2::Types::Flex1PropType
+    xml_attributes :idrefs
+
+    xml do
+      element 'derivedFrom'
+    end
+  end
+
+  # Represents the non-Concept value that was used for deriving the value of
+  # one or more properties in this NewsML-G2 item.
+  class DerivedFromValue < Newsmlg2::NarModel
+    include Newsmlg2::Base::CommonPowerAttributes
+
+    xml_attributes :sourceidref, :idrefs
+
+    xml do
+      element 'derivedFromValue'
+    end
+  end
+
+  # A set of properties directly associated with the Item.
+  class ItemMeta < Newsmlg2::NarModel
+    include Newsmlg2::Base::CommonPowerAttributes
+    include Newsmlg2::Base::I18NAttributes
+    include Newsmlg2::Base::ItemManagementGroup
+
+    xml_element :links, xml: 'link',
+                        type: Newsmlg2::Types::Link, collection: true
+    xml_element :item_meta_ext_properties, xml: 'itemMetaExtProperty',
+                                           type: Newsmlg2::Types::Flex2ExtPropType, collection: true
+
+    xml do
+      element 'itemMeta'
+    end
+  end
+
+  # Abstract base of all G2 items. Item subclasses declare their own element
+  # name ("newsItem", "packageItem", …) and content model.
+  class AnyItem < Newsmlg2::NarModel
+    include Newsmlg2::Base::I18NAttributes
+
+    attribute :standard, :string, default: -> { 'NewsML-G2' }
+    attribute :standardversion, :string, default: -> { Newsmlg2::SPEC_VERSION }
+    attribute :conformance, :string, default: -> { 'power' }
+    attribute :guid, :string
+    attribute :version, :string, default: -> { '1' }
+
+    xml do
+      map_attribute 'standard', to: :standard, render_default: true
+      map_attribute 'standardversion', to: :standardversion, render_default: true
+      map_attribute 'conformance', to: :conformance, render_default: true
+      map_attribute 'guid', to: :guid
+      map_attribute 'version', to: :version, render_default: true
+    end
+
+    xml_element :catalog_refs, xml: 'catalogRef',
+                               type: Newsmlg2::CatalogRef, collection: true
+    xml_element :catalogs, xml: 'catalog',
+                           type: Newsmlg2::Catalog, collection: true
+    xml_element :hop_history, xml: 'hopHistory', type: Newsmlg2::HopHistory
+    xml_element :pub_history, xml: 'pubHistory', type: Newsmlg2::PubHistory
+    xml_element :rights_infos, xml: 'rightsInfo',
+                               type: Newsmlg2::Types::RightsInfo, collection: true
+    xml_element :item_meta, xml: 'itemMeta', type: Newsmlg2::ItemMeta
+
+    # Raises unless the item carries the attributes any NewsML-G2 item
+    # requires before serialization.
+    def validate!
+      raise MissingGuidError, "#{self.class.name.split('::').last} needs a guid" if guid.to_s.empty?
+
+      self
+    end
+  end
+end

data/lib/newsmlg2/items/catalog_item.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Newsmlg2
+  # The container of a single catalog.
+  class CatalogContainer < Newsmlg2::NarModel
+    xml_element :catalog, xml: 'catalog', type: Newsmlg2::Catalog
+
+    xml do
+      element 'catalogContainer'
+    end
+  end
+
+  # An Item containing a single managed NewsML-G2 catalog.
+  class CatalogItem < AnyItem
+    xml_element :content_meta, xml: 'contentMeta',
+                               type: Newsmlg2::ContentMetaCat
+    xml_element :catalog_container, xml: 'catalogContainer',
+                                    type: Newsmlg2::CatalogContainer
+
+    xml do
+      element 'catalogItem'
+    end
+  end
+end

data/lib/newsmlg2/items/concept_item.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Newsmlg2
+  # An Item containing information about a concept.
+  class ConceptItem < AnyItem
+    xml_element :content_meta, xml: 'contentMeta',
+                               type: Newsmlg2::ContentMetaAcD
+    xml_element :asserts, xml: 'assert',
+                          type: Newsmlg2::Assert, collection: true
+    xml_element :inline_refs, xml: 'inlineRef',
+                              type: Newsmlg2::InlineRef, collection: true
+    xml_element :derived_from, xml: 'derivedFrom',
+                               type: Newsmlg2::DerivedFrom, collection: true
+    xml_element :derived_from_values, xml: 'derivedFromValue',
+                                      type: Newsmlg2::DerivedFromValue, collection: true
+    xml_element :concept, xml: 'concept',
+                          type: Newsmlg2::Types::Concept
+
+    xml do
+      element 'conceptItem'
+    end
+  end
+end

data/lib/newsmlg2/items/content_meta.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Newsmlg2
+  # The full content metadata type (administrative + full descriptive
+  # properties) used by news and package items; element name "contentMeta"
+  # is declared by the owning item.
+  class ContentMeta < Newsmlg2::NarModel
+    include Newsmlg2::Base::CommonPowerAttributes
+    include Newsmlg2::Base::I18NAttributes
+
+    # python-newsmlg2 fixtures carry an in-namespace <name> inside
+    # contentMeta (an xs:any-style provider extension in those files);
+    # modelled so the value round-trips instead of being hoisted.
+    xml_element :names, xml: 'name',
+                        type: Newsmlg2::Types::ConceptNameType, collection: true
+    xml_element :icons, xml: 'icon',
+                        type: Newsmlg2::Types::Icon, collection: true
+    include Newsmlg2::Base::AdministrativeMetadataGroup
+    include Newsmlg2::Base::DescriptiveMetadataGroup
+
+    xml_element :content_meta_ext_properties, xml: 'contentMetaExtProperty',
+                                              type: Newsmlg2::Types::Flex2ExtPropType, collection: true
+
+    xml do
+      element 'contentMeta'
+    end
+  end
+
+  # Content metadata with the core descriptive set, used by concept,
+  # knowledge and planning items.
+  class ContentMetaAcD < Newsmlg2::NarModel
+    include Newsmlg2::Base::CommonPowerAttributes
+    include Newsmlg2::Base::I18NAttributes
+
+    # python-newsmlg2 fixtures carry an in-namespace <name> inside
+    # contentMeta (an xs:any-style provider extension in those files);
+    # modelled so the value round-trips instead of being hoisted.
+    xml_element :names, xml: 'name',
+                        type: Newsmlg2::Types::ConceptNameType, collection: true
+    xml_element :icons, xml: 'icon',
+                        type: Newsmlg2::Types::Icon, collection: true
+    include Newsmlg2::Base::AdministrativeMetadataGroup
+    include Newsmlg2::Base::DescriptiveMetadataCoreGroup
+
+    xml_element :content_meta_ext_properties, xml: 'contentMetaExtProperty',
+                                              type: Newsmlg2::Types::Flex2ExtPropType, collection: true
+
+    xml do
+      element 'contentMeta'
+    end
+  end
+
+  # The restricted content metadata of a catalog item.
+  class ContentMetaCat < Newsmlg2::NarModel
+    include Newsmlg2::Base::CommonPowerAttributes
+    include Newsmlg2::Base::I18NAttributes
+
+    xml_element :content_created, xml: 'contentCreated',
+                                  type: Newsmlg2::Types::TruncatedDateTimePropType
+    xml_element :content_modified, xml: 'contentModified',
+                                   type: Newsmlg2::Types::TruncatedDateTimePropType
+    xml_element :creators, xml: 'creator',
+                           type: Newsmlg2::Types::FlexAuthorPropType, collection: true
+    xml_element :contributors, xml: 'contributor',
+                               type: Newsmlg2::Types::FlexAuthorPropType, collection: true
+    xml_element :alt_ids, xml: 'altId',
+                          type: Newsmlg2::Types::AltId, collection: true
+
+    xml do
+      element 'contentMeta'
+    end
+  end
+end

data/lib/newsmlg2/items/item_ref.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Newsmlg2
+  # A reference to a target item or Web resource. Official IPTC examples
+  # carry media characteristics (width, height, …) on itemRef.
+  class ItemRef < Newsmlg2::Types::Link1Type
+    include Newsmlg2::Base::NewsContentCharacteristics
+
+    xml do
+      element 'itemRef'
+    end
+  end
+end

data/lib/newsmlg2/items/knowledge_item.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Newsmlg2
+  # An unordered set of concepts.
+  class ConceptSet < Newsmlg2::NarModel
+    include Newsmlg2::Base::CommonPowerAttributes
+
+    xml_element :concepts, xml: 'concept',
+                           type: Newsmlg2::Types::Concept, collection: true
+
+    xml do
+      element 'conceptSet'
+    end
+  end
+
+  # Metadata about a scheme conveyed by a Knowledge Item.
+  class SchemeMeta < Newsmlg2::NarModel
+    include Newsmlg2::Base::CommonPowerAttributes
+    include Newsmlg2::Base::AuthorityAttributes
+
+    xml_element :same_as_schemes, xml: 'sameAsScheme',
+                                  type: Newsmlg2::SameAsScheme, collection: true
+    xml_element :names, xml: 'name',
+                        type: Newsmlg2::Types::ConceptNameType, collection: true
+    xml_element :definitions, xml: 'definition',
+                              type: Newsmlg2::Types::Definition, collection: true
+    xml_element :notes, xml: 'note',
+                        type: Newsmlg2::Types::Note, collection: true
+    xml_element :related, xml: 'related',
+                          type: Newsmlg2::Types::Related, collection: true
+    xml_element :scheme_meta_ext_properties, xml: 'schemeMetaExtProperty',
+                                             type: Newsmlg2::Types::Flex2ExtPropType, collection: true
+
+    xml_attributes(
+      :uri, :preferredalias, :concepttype,
+      :schemecreated, :schememodified, :schemeretired
+    )
+
+    xml do
+      element 'schemeMeta'
+    end
+  end
+
+  # An Item used for collating a set of concept definitions to form the
+  # physical representation of a controlled vocabulary.
+  class KnowledgeItem < AnyItem
+    xml_element :content_meta, xml: 'contentMeta',
+                               type: Newsmlg2::ContentMetaAcD
+    xml_element :part_metas, xml: 'partMeta',
+                             type: Newsmlg2::PartMeta, collection: true
+    xml_element :asserts, xml: 'assert',
+                          type: Newsmlg2::Assert, collection: true
+    xml_element :inline_refs, xml: 'inlineRef',
+                              type: Newsmlg2::InlineRef, collection: true
+    xml_element :derived_from, xml: 'derivedFrom',
+                               type: Newsmlg2::DerivedFrom, collection: true
+    xml_element :derived_from_values, xml: 'derivedFromValue',
+                                      type: Newsmlg2::DerivedFromValue, collection: true
+    xml_element :concept_set, xml: 'conceptSet',
+                              type: Newsmlg2::ConceptSet
+    xml_element :scheme_meta, xml: 'schemeMeta',
+                              type: Newsmlg2::SchemeMeta
+
+    xml do
+      element 'knowledgeItem'
+    end
+  end
+end