pubid 2.0.6 → 2.0.7

data/lib/pubid/pubid_urn/schema.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Pubid
+  module PubidUrn
+    # One prefixed atom: an optional value, found by its prefix and not by
+    # its position ("part-1", "co-IEC,IEEE", "ids-(iso:is:9001)").
+    #
+    # +path+ is a dotted key path into the node's +to_hash+; "*" walks the
+    # elements of an Array ("languages.*.code"). +kind+ is one of
+    # :string, :list (of Strings), :bool, :bools (a list of booleans), :int,
+    # :id (a nested identifier hash) or :ids (an Array of them). A path with
+    # "*" is always a list: :list, or :bools when its elements are booleans.
+    Atom = Struct.new(:path, :prefix, :kind) do
+      def parts
+        @parts ||= path.split(".")
+      end
+
+      def list?
+        LIST_KINDS.key?(kind)
+      end
+
+      # @return [Symbol] the kind of one value (of one element of a list)
+      def element
+        LIST_KINDS.fetch(kind, kind)
+      end
+    end
+
+    # A list kind => the kind of its elements.
+    LIST_KINDS = { list: :string, bools: :bool }.freeze
+
+    # A spelling-only value (+original_code+, +original_text+ …). Facets are
+    # written in the trailing "f" group, so a consumer can cut them off a slug.
+    # +kind+ is :string, :list, :bool or :bools, as for an Atom; a spelling
+    # flag ("V.25 ter" against "V.25ter") is a :bool facet.
+    Facet = Struct.new(:path, :name, :kind) do
+      def parts
+        @parts ||= path.split(".")
+      end
+
+      def list?
+        LIST_KINDS.key?(kind)
+      end
+
+      def element
+        LIST_KINDS.fetch(kind, kind)
+      end
+    end
+
+    # The URN shape of one concrete identifier type.
+    class TypeSchema
+      attr_reader :flavor, :type, :token, :core, :atoms, :facets
+
+      def initialize(flavor:, type:, token:, core:, atoms:, facets:)
+        @flavor = flavor
+        @type = type
+        @token = token
+        @core = core.map { |path| path.split(".") }.freeze
+        @atoms = atoms.freeze
+        @facets = facets.freeze
+        @atom_index = atoms.each_with_index.to_h { |atom, i| [atom.prefix, i] }
+        @facet_names = facets.to_h { |facet| [facet.name, facet] }
+      end
+
+      # @return [Integer, nil] the canonical position of the atom whose
+      #   prefix starts +token+, or nil when +token+ is no atom of this type
+      def atom_position(token)
+        prefix = token[/\A([a-z0-9]+)-/, 1]
+        prefix && @atom_index[prefix]
+      end
+
+      def facet(name)
+        @facet_names[name]
+      end
+    end
+
+    # The pubid-scheme schema of one flavor: the canonical atom order, the
+    # facets, and one TypeSchema for each concrete type.
+    #
+    # Atoms and facets declared at flavor level apply to every type, in the
+    # order of declaration; a type adds its own after them. A type token, an
+    # atom prefix and a facet name are a lower-case letter followed by
+    # lower-case letters and digits, so none can contain the "-" that ends a
+    # prefix or the "." that qualifies a token of another flavor, and each
+    # has the shape PubidUrn::STRUCTURE reads as structure.
+    class FlavorSchema
+      NAME = /\A[a-z][a-z0-9]*\z/
+      KINDS = %i[string list bool bools int id ids].freeze
+      FACET_KINDS = %i[string list bool bools].freeze
+      # "f" opens the facet group; "type" is the type-metadata URN
+      # (Pubid::IdentifierMetadata, "urn:pubid:<flavor>:type:<key>").
+      RESERVED_TOKENS = %w[f type].freeze
+
+      attr_reader :flavor, :types
+
+      def initialize(flavor)
+        @flavor = flavor
+        @atoms = []
+        @facets = []
+        @types = {}
+        @tokens = {}
+      end
+
+      def atom(path, prefix, kind: nil)
+        @atoms << build_atom(path, prefix, kind)
+      end
+
+      def facet(path, name, kind: nil)
+        @facets << build_facet(path, name, kind)
+      end
+
+      # @param type [String] the +_type+ the class serializes
+      # @param token [String] the short type token of the URN
+      # @param core [Array<String>] the positional core paths
+      # @param atoms [Array<Array>] extra atoms: [path, prefix, kind]
+      # @param facets [Array<Array>] extra facets: [path, name, kind]
+      def type(type, token, core: %w[number], atoms: [], facets: [])
+        check_name!(token, "type token")
+        if RESERVED_TOKENS.include?(token) || @tokens.key?(token)
+          raise ArgumentError, 
+                "type token #{token.inspect} is reserved or taken"
+        end
+
+        all_atoms = @atoms + atoms.map { |spec| build_atom(*spec) }
+        check_unique!(all_atoms.map(&:prefix), "atom prefix", type)
+        all_facets = @facets + facets.map { |spec| build_facet(*spec) }
+        check_unique!(all_facets.map(&:name), "facet name", type)
+
+        schema = TypeSchema.new(flavor: flavor, type: type, token: token,
+                                core: core, atoms: all_atoms,
+                                facets: all_facets)
+        @types[type] = schema
+        @tokens[token] = schema
+      end
+
+      def for_token(token)
+        @tokens[token]
+      end
+
+      def for_type(type)
+        @types[type]
+      end
+
+      private
+
+      def build_atom(path, prefix, kind = nil)
+        check_name!(prefix, "atom prefix")
+        Atom.new(path, prefix, check_kind!(path, kind, KINDS, "atom"))
+      end
+
+      def build_facet(path, name, kind = nil)
+        check_name!(name, "facet name")
+        Facet.new(path, name, check_kind!(path, kind, FACET_KINDS, "facet"))
+      end
+
+      # A path with "*" reads a list, so its kind must be a list kind.
+      def check_kind!(path, kind, kinds, what)
+        listed = path.split(".").include?("*")
+        kind ||= listed ? :list : :string
+        unless kinds.include?(kind)
+          raise ArgumentError, "unknown #{what} kind #{kind.inspect}"
+        end
+        if listed && !LIST_KINDS.key?(kind)
+          raise ArgumentError, "#{what} #{path.inspect} reads a list, " \
+                               "so its kind must be one of #{LIST_KINDS.keys}"
+        end
+
+        kind
+      end
+
+      def check_name!(name, what)
+        return if NAME.match?(name)
+
+        raise ArgumentError, "#{what} #{name.inspect} must match #{NAME.source}"
+      end
+
+      def check_unique!(names, what, type)
+        dup = names.tally.find { |_, count| count > 1 }
+        return unless dup
+
+        raise ArgumentError, "#{what} #{dup.first.inspect} repeats in #{type}"
+      end
+    end
+  end
+end

data/lib/pubid/pubid_urn.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Pubid
+  # The pubid-scheme URN (issue #656): pubid's own URN namespace, which
+  # carries the full typed model and always round-trips —
+  # +Pubid.parse_urn(id.to_pubid_urn).to_hash == id.to_hash+.
+  #
+  # It is a different thing from the official URN (+#to_urn+, e.g.
+  # "urn:iso:std:…"), which follows the registered grammar of the
+  # organization and may be lossy. relaton uses the pubid-scheme URN as its
+  # HTTP path slug (relaton/relaton#441), so the form is also path-safe:
+  # no "/", "%", "?", "#" and no empty segment.
+  #
+  #   urn:pubid:iso:is:9001:year-2015:amd:1:year-2016
+  #
+  # The shape of each identifier type is declared in its flavor's
+  # +PubidUrnSchema+ (e.g. +lib/pubid/iso/pubid_urn_schema.rb+), through
+  # {define}. A flavor with no schema cannot emit one yet. The design of
+  # every flavor is in +docs/URN-SCHEMES.adoc+.
+  module PubidUrn
+    autoload :Escape, "pubid/pubid_urn/escape"
+    autoload :Atom, "pubid/pubid_urn/schema"
+    autoload :Facet, "pubid/pubid_urn/schema"
+    autoload :TypeSchema, "pubid/pubid_urn/schema"
+    autoload :FlavorSchema, "pubid/pubid_urn/schema"
+    autoload :Paths, "pubid/pubid_urn/paths"
+    autoload :Encoder, "pubid/pubid_urn/encoder"
+    autoload :Decoder, "pubid/pubid_urn/decoder"
+
+    PREFIX = "urn:pubid:"
+    # An absent core value in the middle of the core, or an absent element
+    # of a list. Distinct from an escape, which always has two hex digits.
+    NULL = "~"
+
+    # A raw segment that reads as structure and not as a core value: a type
+    # token or the facet marker ("amd", "f"), an atom ("year-2015"), or a
+    # token of another flavor ("iec.is", "3gpp.ts").
+    #
+    # The rule depends on the SHAPE of the segment only, never on which
+    # schemas exist. So a published URN keeps its meaning when a flavor, a
+    # type token or an atom is added later. Type tokens, atom prefixes and
+    # facet names therefore start with a lower-case letter
+    # (FlavorSchema::NAME). Digit-led numbers ("9001", "802.11", "800-53")
+    # and upper-case ones ("G.711") never match; a core value that does
+    # match gets its first character escaped ("iec.is" -> "~69ec.is").
+    STRUCTURE = /
+      \A(?:
+        [a-z][a-z0-9]*(?:-|\z)                     # token, "f", atom
+      | [a-z0-9]*[a-z][a-z0-9]*\.[a-z][a-z0-9]*\z  # token of another flavor
+      )
+    /x
+
+    # The longest URN that parse accepts, and that generate emits. An
+    # escape is up to 3 characters for each UTF-8 byte (up to 9 for a CJK
+    # character), so the 1000-character limit of a printed identifier is too
+    # tight here. The parser is linear-time (anchored, non-backtracking
+    # patterns), so this bound is a guard against oversized input, not a
+    # ReDoS barrier.
+    MAX_LENGTH = 16 * Pubid::MAX_INPUT_LENGTH
+
+    @schemas = {}
+
+    class << self
+      # Declare the schema of a flavor. +flavor+ is the flavor segment of
+      # its +_type+ ("iso", "cencenelec", "3gpp").
+      #
+      # @yield the FlavorSchema, evaluated with instance_eval
+      # @return [FlavorSchema]
+      def define(flavor, &)
+        schema = FlavorSchema.new(flavor)
+        schema.instance_eval(&)
+        @schemas[flavor] = schema
+      end
+
+      # @param identifier [Pubid::Identifier]
+      # @return [String]
+      # @raise [Pubid::Errors::InvalidInputError] when its flavor has no
+      #   schema yet, the schema does not place one of its values, or the URN
+      #   would be longer than MAX_LENGTH
+      def generate(identifier)
+        urn = "#{PREFIX}#{Encoder.new(identifier.to_hash).body}"
+        if urn.length > MAX_LENGTH
+          raise Errors::InvalidInputError,
+                "pubid URN exceeds #{MAX_LENGTH} characters"
+        end
+
+        urn
+      end
+
+      # @param string [String] a pubid-scheme URN
+      # @return [Pubid::Identifier]
+      # @raise [Pubid::Errors::InvalidInputError] when +string+ is not a
+      #   String or is longer than MAX_LENGTH
+      # @raise [Pubid::Errors::UrnParseError] for a malformed, unknown or
+      #   non-canonical URN
+      def parse(string)
+        check_input!(string)
+        identifier = build(string[PREFIX.length..])
+        check_canonical!(identifier, string)
+        identifier
+      end
+
+      # True for "urn:pubid:…" (the NID is case-insensitive, RFC 8141).
+      # Compares bytes, so it is safe on a string with invalid encoding.
+      def pubid_urn?(string)
+        string.is_a?(String) && string.b[0, PREFIX.length].downcase == PREFIX
+      end
+
+      # @return [FlavorSchema, nil]
+      def flavor_schema(flavor)
+        return @schemas[flavor] if @schemas.key?(flavor)
+
+        mod = TypeResolver.flavor_module(flavor)
+        if mod&.const_defined?(:PubidUrnSchema, false)
+          mod.const_get(:PubidUrnSchema)
+        end
+        @schemas[flavor]
+      end
+
+      # @return [TypeSchema]
+      def type_schema!(type, error:)
+        flavor = flavor_segment(type)
+        schema = flavor && flavor_schema(flavor)&.for_type(type)
+        return schema if schema
+
+        raise error, "no pubid URN schema for #{type.inspect}"
+      end
+
+      # "iso" in "pubid:iso:technical-report".
+      def flavor_segment(type)
+        return nil unless type.is_a?(String)
+
+        type.split(":")[1]
+      end
+
+      # Does +token+ (a raw, still escaped segment) read as structure? See
+      # STRUCTURE.
+      def structural?(token)
+        STRUCTURE.match?(token)
+      end
+
+      # A type token is "<token>" of the URN's own flavor, or "<flavor>.<token>"
+      # for a node of another flavor.
+      #
+      # @return [Array(String, String)] the owning flavor and the token
+      def split_token(token, flavor)
+        token.include?(".") ? token.split(".", 2) : [flavor, token]
+      end
+
+      # Split +string+ at +separator+ outside brackets.
+      #
+      # @param allow_empty [Boolean] true for the items of a list, where an
+      #   empty item is an empty String; a ":" segment is never empty
+      def split_top(string, separator, allow_empty: false)
+        parts = []
+        depth = 0
+        current = +""
+        string.each_char do |char|
+          depth += 1 if char == "("
+          depth -= 1 if char == ")"
+          check_depth!(string) if depth.negative?
+
+          if char == separator && depth.zero?
+            parts << current
+            current = +""
+          else
+            current << char
+          end
+        end
+        check_depth!(string) unless depth.zero?
+
+        parts << current
+        if !allow_empty && parts.any?(&:empty?)
+          raise Errors::UrnParseError, "empty segment in #{string.inspect}"
+        end
+
+        parts
+      end
+
+      private
+
+      def check_input!(string)
+        unless string.is_a?(String)
+          raise Errors::InvalidInputError, Pubid::INPUT_NOT_A_STRING_MESSAGE
+        end
+        if string.length > MAX_LENGTH
+          raise Errors::InvalidInputError,
+                "input exceeds #{MAX_LENGTH} characters"
+        end
+        unless string.valid_encoding? && pubid_urn?(string)
+          raise Errors::UrnParseError,
+                "not a pubid-scheme URN: #{string.inspect}"
+        end
+      end
+
+      # The URN is untrusted input: a value that decodes but cannot be cast
+      # into its attribute (a bad boolean, a String where a component goes)
+      # is a bad URN, so every failure here is reported as UrnParseError,
+      # with the original error as its cause.
+      def build(body)
+        Pubid.from_hash(Decoder.new(body).to_identifier_hash)
+      rescue Errors::UrnParseError
+        raise
+      rescue StandardError => e
+        raise Errors::UrnParseError,
+              "pubid URN #{body.inspect} does not build: #{e.message}"
+      end
+
+      def check_depth!(string)
+        raise Errors::UrnParseError, "unbalanced bracket in #{string.inspect}"
+      end
+
+      def check_canonical!(identifier, string)
+        canonical = identifier.to_pubid_urn
+        return if canonical[PREFIX.length..] == string[PREFIX.length..]
+
+        raise Errors::UrnParseError,
+              "#{string.inspect} is not canonical; " \
+              "the canonical form is #{canonical.inspect}"
+      rescue Errors::InvalidInputError => e
+        raise Errors::UrnParseError,
+              "#{string.inspect} does not re-encode: #{e.message}"
+      end
+    end
+  end
+end

data/lib/pubid/type_resolver.rb

@@ -29,6 +29,18 @@ module Pubid
         shared_class(type) || flavor_class(type)
       end
 
+      # The flavor module that the flavor segment of a +_type+ names
+      # ("iso", "cencenelec", "3gpp").
+      #
+      # @param segment [String]
+      # @return [Module, nil]
+      def flavor_module(segment)
+        return nil unless segment.is_a?(String)
+
+        ::Pubid.eager_load_flavors!
+        ::Pubid::Registry.get(segment) || flavor_by_module_segment(segment)
+      end
+
       private
 
       def shared_class(type)

data/lib/pubid/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pubid
-  VERSION = "2.0.6"
+  VERSION = "2.0.7"
 end

data/lib/pubid.rb

@@ -160,6 +160,7 @@ module Pubid
   autoload :Version, "pubid/version"
   autoload :Core, "pubid/core"
   autoload :TypeResolver, "pubid/type_resolver"
+  autoload :PubidUrn, "pubid/pubid_urn"
 
 
   # Require all flavor modules
@@ -281,8 +282,13 @@ module Pubid
   #
   # @param string [String] the URN
   # @return [Identifier] the parsed identifier
+  #
+  # A pubid-scheme URN ("urn:pubid:…", see {PubidUrn}) is decoded by the
+  # shared codec; every other namespace goes to its flavor's UrnParser.
   def self.parse_urn(string)
     eager_load_flavors!
+    return PubidUrn.parse(string) if PubidUrn.pubid_urn?(string)
+
     flavor = detect_flavor_from_urn(string)
     flavor_module = Registry.get(flavor)
     unless flavor_module
@@ -294,6 +300,18 @@ module Pubid
     urn_parser.parse(string)
   end
 
+  # Parse a pubid-scheme URN, and only that: an official URN such as
+  # "urn:iso:std:…" raises. For a consumer that takes a slug and must not
+  # accept a lossy official URN by mistake (relaton/relaton#441).
+  #
+  # @param string [String] a "urn:pubid:…" URN
+  # @return [Identifier]
+  # @raise [Pubid::Errors::UrnParseError]
+  def self.parse_pubid_urn(string)
+    eager_load_flavors!
+    PubidUrn.parse(string)
+  end
+
   # Build an identifier from its serialized hash, without naming its flavor —
   # the hash counterpart of {parse}.
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pubid
 version: !ruby/object:Gem::Version
-  version: 2.0.6
+  version: 2.0.7
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-11-03 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -168,6 +168,7 @@ files:
 - lib/pubid/ansi/identifiers/american_national_standard.rb
 - lib/pubid/ansi/identifiers/standard.rb
 - lib/pubid/ansi/parser.rb
+- lib/pubid/ansi/pubid_urn_schema.rb
 - lib/pubid/ansi/renderer.rb
 - lib/pubid/ansi/single_identifier.rb
 - lib/pubid/ansi/urn_generator.rb
@@ -244,6 +245,7 @@ files:
 - lib/pubid/astm/identifiers/technical_report.rb
 - lib/pubid/astm/identifiers/work_in_progress.rb
 - lib/pubid/astm/parser.rb
+- lib/pubid/astm/pubid_urn_schema.rb
 - lib/pubid/astm/renderer.rb
 - lib/pubid/astm/single_identifier.rb
 - lib/pubid/astm/urn_generator.rb
@@ -602,6 +604,7 @@ files:
 - lib/pubid/iec/identifiers/white_paper.rb
 - lib/pubid/iec/identifiers/working_document.rb
 - lib/pubid/iec/parser.rb
+- lib/pubid/iec/pubid_urn_schema.rb
 - lib/pubid/iec/renderer.rb
 - lib/pubid/iec/rendering_style.rb
 - lib/pubid/iec/single_identifier.rb
@@ -657,6 +660,7 @@ files:
 - lib/pubid/ieee/parser.rb
 - lib/pubid/ieee/pre_parser.rb
 - lib/pubid/ieee/project_renderer.rb
+- lib/pubid/ieee/pubid_urn_schema.rb
 - lib/pubid/ieee/renderer.rb
 - lib/pubid/ieee/typed_stages.rb
 - lib/pubid/ieee/urn_generator.rb
@@ -731,6 +735,7 @@ files:
 - lib/pubid/iso/identifiers/technology_trends_assessments.rb
 - lib/pubid/iso/normalizer.rb
 - lib/pubid/iso/parser.rb
+- lib/pubid/iso/pubid_urn_schema.rb
 - lib/pubid/iso/rendering_style.rb
 - lib/pubid/iso/single_identifier.rb
 - lib/pubid/iso/supplement_identifier.rb
@@ -769,6 +774,7 @@ files:
 - lib/pubid/itu/identifiers/supplement.rb
 - lib/pubid/itu/model.rb
 - lib/pubid/itu/parser.rb
+- lib/pubid/itu/pubid_urn_schema.rb
 - lib/pubid/itu/urn_generator.rb
 - lib/pubid/itu/urn_parser.rb
 - lib/pubid/jcgm.rb
@@ -853,6 +859,7 @@ files:
 - lib/pubid/nist/parser.rb
 - lib/pubid/nist/parser_output_normalizer.rb
 - lib/pubid/nist/preprocessor.rb
+- lib/pubid/nist/pubid_urn_schema.rb
 - lib/pubid/nist/renderer.rb
 - lib/pubid/nist/router.rb
 - lib/pubid/nist/series.rb
@@ -944,6 +951,12 @@ files:
 - lib/pubid/plateau/urn_generator.rb
 - lib/pubid/plateau/urn_parser.rb
 - lib/pubid/prefixes_support.rb
+- lib/pubid/pubid_urn.rb
+- lib/pubid/pubid_urn/decoder.rb
+- lib/pubid/pubid_urn/encoder.rb
+- lib/pubid/pubid_urn/escape.rb
+- lib/pubid/pubid_urn/paths.rb
+- lib/pubid/pubid_urn/schema.rb
 - lib/pubid/renderers.rb
 - lib/pubid/renderers/annotator.rb
 - lib/pubid/renderers/base.rb