metaschema 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d85cb4ff725e346ee1fbfc3ecb0090b1bc91fbde31d5d2fa1a24e0464f14c2db
4
- data.tar.gz: 5c14593b1fedde86d471330cb450c1907c6b365d550d59f14239d2d6848b1c98
3
+ metadata.gz: 68f887faf742585adce6ea1fbad13f325b9d5ab09d0949a9e3f44882e7436204
4
+ data.tar.gz: c7313871d57eaa5937c701a9c9576fb17142133c18cc431631dc999fa0b7ef83
5
5
  SHA512:
6
- metadata.gz: d651ce6fb12927439e2442bc94801ffd478576592d409c42dc2ad26b82f1455d07e21cb924d3aee3bab2ede04a46733d63b25c87fd4dcf21d3a74041cea51200
7
- data.tar.gz: c650d187391fac955d639a126a873af53cbbef284e1eb26492d7dc80235e05b539c5bd758696e96e08ed458c2076f52e78be4840385e38d0dfba9b67970ec8c6
6
+ metadata.gz: 9bc2dc07a2b91db5a98182563981bd4e7569b50ef1fe6f82f4700bccdda43b4030b730f9c093a27a989320f8365ecbc8f9fada30176c83d3956d112b744adc9a
7
+ data.tar.gz: 174bbc462d505ad18e320a4f13d61bdae7f57a2314f524f09f62969c06d901bc9d63b30339acf534dd434d8a04ccc883a700f88d6822fe14b99596b9f85bd762
data/README.adoc CHANGED
@@ -139,6 +139,27 @@ The `TypeMapper` maps Metaschema data types to Ruby/Lutaml::Model types:
139
139
  `markup-line`:: `Metaschema::MarkupLineDatatype`
140
140
  `markup-multiline`:: `Metaschema::MarkupMultilineDatatype`
141
141
 
142
+ === Markup prose in JSON and YAML
143
+
144
+ Generated models do not yet represent markup prose the way the NIST Metaschema
145
+ specification defines it. The specification says `markup-line` and
146
+ `markup-multiline` serialize to a *Markdown string* in JSON and YAML — see
147
+ `spec/fixtures/metaschema/website/content/specification/datatypes.md`.
148
+
149
+ What the generated models do instead:
150
+
151
+ * A global markup field carries only its text content. Inline markup elements
152
+ (`em`, `a`, `code`, and the rest) are not represented at all — the JSON
153
+ mapping maps `content` and the flags, nothing else.
154
+ * An inline markup field keeps those elements, as nested objects.
155
+
156
+ Neither form is a Markdown string, so markup does not survive an
157
+ XML -> JSON -> XML round trip intact. Prose that carries inline markup also
158
+ keeps object form rather than collapsing to a bare scalar, because the object
159
+ has more than its value key.
160
+
161
+ Mapping markup to and from Markdown is follow-up work.
162
+
142
163
  === Dependencies
143
164
 
144
165
  * `lutaml-model ~> 0.8.0` — serialization framework
@@ -351,13 +351,10 @@ module Metaschema
351
351
 
352
352
  field_klass = mapping[:field_klass]
353
353
  attr_sym = mapping[:attr_name]
354
- has_flags = mapping[:has_flags]
355
354
 
356
355
  klass.define_method(mapping[:from_method]) do |instance, value|
357
356
  if value.is_a?(Array)
358
- parsed = value.map do |v|
359
- has_flags ? field_klass.of_json(v) : field_klass.new(content: v)
360
- end
357
+ parsed = value.map { |v| field_klass.of_json(v) }
361
358
  instance.instance_variable_set("@#{attr_sym}", parsed)
362
359
  elsif value.is_a?(Hash)
363
360
  if value.empty?
@@ -370,7 +367,7 @@ module Metaschema
370
367
  end
371
368
  elsif value
372
369
  instance.instance_variable_set("@#{attr_sym}",
373
- has_flags ? field_klass.of_json(value) : field_klass.new(content: value))
370
+ field_klass.of_json(value))
374
371
  end
375
372
  end
376
373
 
@@ -378,21 +375,20 @@ module Metaschema
378
375
  current = instance.instance_variable_get("@#{attr_sym}")
379
376
  if current.is_a?(Array)
380
377
  result = current.map do |item|
381
- if has_flags && item.is_a?(Lutaml::Model::Serializable)
378
+ if item.is_a?(Lutaml::Model::Serializable)
382
379
  field_klass.as_json(item)
383
380
  else
384
- item.respond_to?(:content) ? item.content : item
381
+ item
385
382
  end
386
383
  end
387
384
  doc[mapping[:json_name]] = result
388
385
  elsif current
389
386
  if current.instance_variable_get(:@_was_empty_hash)
390
387
  doc[mapping[:json_name]] = {}
391
- elsif has_flags && current.is_a?(Lutaml::Model::Serializable)
388
+ elsif current.is_a?(Lutaml::Model::Serializable)
392
389
  doc[mapping[:json_name]] = field_klass.as_json(current)
393
390
  else
394
- val = current.respond_to?(:content) ? current.content : current
395
- doc[mapping[:json_name]] = val
391
+ doc[mapping[:json_name]] = current
396
392
  end
397
393
  end
398
394
  end
@@ -1187,6 +1183,7 @@ attr_sym, json_key_flag, grouped: false, child_attr: nil)
1187
1183
  end
1188
1184
  end
1189
1185
 
1186
+ FieldFactory.install_scalar_methods(inline_klass)
1190
1187
  klass.attribute attr_name, inline_klass, collection: collection
1191
1188
  elsif has_flags
1192
1189
  inline_klass = Class.new(Lutaml::Model::Serializable)
@@ -1231,6 +1228,7 @@ attr_sym, json_key_flag, grouped: false, child_attr: nil)
1231
1228
  klass_name = @g.scoped_field_name(field_def.name)
1232
1229
  @g.classes[klass_name] = inline_klass
1233
1230
 
1231
+ FieldFactory.install_scalar_methods(inline_klass)
1234
1232
  klass.attribute attr_name, inline_klass, collection: collection
1235
1233
  else
1236
1234
  klass.attribute attr_name, content_type, collection: collection
@@ -40,61 +40,66 @@ module Metaschema
40
40
  fd, is_multiline)
41
41
  build_field_json(klass, fd)
42
42
 
43
- has_flags = fd.define_flag&.any? || fd.flag&.any?
44
- has_json_vk = fd.json_value_key || fd.json_value_key_flag
45
- is_collapsible = fd.collapsible == "yes"
46
- value_key = fd.json_value_key || TypeMapper.json_value_key(fd.as_type)
47
-
48
- klass.define_singleton_method(:of_json) do |data|
49
- if data.is_a?(String)
50
- new(content: data)
51
- else
52
- super(data)
53
- end
54
- end
43
+ self.class.install_scalar_methods(klass)
55
44
 
56
- klass.define_singleton_method(:from_json) do |data|
57
- if data.is_a?(String)
58
- new(content: data)
59
- else
60
- super(data)
61
- end
62
- end
45
+ @g.apply_constraint_validation(klass, fd.constraint)
46
+ end
63
47
 
64
- if has_flags || has_json_vk || is_collapsible
65
- flag_attr_names = (fd.define_flag || []).filter_map do |f|
66
- Utils.safe_attr(f.name) if f.name
67
- end +
68
- (fd.flag || []).filter_map do |f|
69
- Utils.safe_attr(f.ref) if f.ref
48
+ class << self
49
+ # Field classes carry a scalar value in JSON/YAML, not an object: a
50
+ # scalar coming in is wrapped as content, and a field whose serialized
51
+ # form has nothing but its value key collapses back to a bare scalar.
52
+ #
53
+ # Mirrors the `scalar_field` contract the Ruby source emitter writes onto
54
+ # the generated Base class. The two are deliberately separate
55
+ # implementations — the emitter mirrors templates, it does not import
56
+ # runtime behaviour — and the emitted parity spec pins them together.
57
+ def install_scalar_methods(klass)
58
+ collection = klass.attributes[:content].collection
59
+ key = scalar_key(klass)
60
+ # Marks this class as a metaschema field. An assembly can also carry a
61
+ # member named `content`, so shape alone cannot identify a field; the
62
+ # emitter reads this marker rather than guessing.
63
+ klass.instance_variable_set(:@metaschema_scalar_field, true)
64
+
65
+ %i[of_json of_yaml].each do |method|
66
+ klass.define_singleton_method(method) do |data, options = {}|
67
+ next super(data, options) if data.is_a?(Hash) || data.is_a?(Array)
68
+
69
+ new(content: collection ? [data] : data)
70
70
  end
71
+ end
71
72
 
72
- orig_as_json = klass.method(:as_json)
73
- klass.define_singleton_method(:as_json) do |instance, options = {}|
74
- result = orig_as_json.call(instance, options)
73
+ # A scalar nested in a parent reaches the field class through .cast.
74
+ klass.define_singleton_method(:cast) do |data|
75
+ next super(data) if data.nil? || data.is_a?(Hash) ||
76
+ data.is_a?(Array) || data.is_a?(self)
75
77
 
76
- if is_collapsible && result.is_a?(Hash) && result[value_key].is_a?(Array) && result[value_key].length == 1
77
- result[value_key] = result[value_key].first
78
- end
78
+ new(content: collection ? [data] : data)
79
+ end
79
80
 
80
- if (has_flags || has_json_vk) && result.is_a?(Hash) && result.key?(value_key)
81
- flags_present = flag_attr_names.any? do |attr|
82
- val = instance.send(attr)
83
- val && !(val.respond_to?(:using_default?) && val.using_default?)
84
- end
85
- unless flags_present
86
- return result[value_key]
87
- end
81
+ %i[as_json as_yaml].each do |method|
82
+ klass.define_singleton_method(method) do |instance, options = {}|
83
+ FieldFactory.collapse_scalar(key, super(instance, options))
88
84
  end
89
-
90
- result
91
85
  end
92
86
  end
93
87
 
94
- @g.apply_constraint_validation(klass, fd.constraint)
95
- end
88
+ def collapse_scalar(key, result)
89
+ return result unless key && result.is_a?(Hash) && result.keys == [key]
90
+
91
+ value = result[key]
92
+ value = value.first if value.is_a?(Array) && value.length == 1
93
+ value.is_a?(Array) ? result : value
94
+ end
95
+
96
+ # The key_value mapping key that carries :content. Derived from the
97
+ # mapping actually built, not from TypeMapper.json_value_key, which
98
+ # disagrees with it for fields that have neither flags nor a value key.
99
+ def scalar_key(klass)
100
+ klass.mappings_for(:json).find_by_to(:content)&.name
101
+ end
96
102
 
97
- class << self
98
103
  # Add inline markup attributes (a, code, em, etc.) for markup-line fields.
99
104
  def apply_markup_attributes(klass)
100
105
  klass.attribute :content, :string, collection: true
@@ -6,7 +6,8 @@ module Metaschema
6
6
  # Deserializes a field value from the source format into a model instance.
7
7
  # Handles SINGLETON_OR_ARRAY normalization and collapsible field expansion.
8
8
  #
9
- # Pipeline: normalize -> separate -> cast -> validate_collection -> transform
9
+ # Pipeline: normalize -> separate -> cast -> transform ->
10
+ # unwrap_singleton -> validate_collection
10
11
  class FieldDeserializer
11
12
  def initialize(model, attr, format, data, group_as:, collapsible:)
12
13
  @model = model
@@ -27,9 +28,9 @@ module Metaschema
27
28
  data = normalize(@data)
28
29
  data = separate(data) if @collapsible
29
30
  data = cast(data)
30
- validate_collection!(data)
31
31
  data = transform(data)
32
32
  data = unwrap_singleton(data)
33
+ validate_collection!(data)
33
34
 
34
35
  @model.public_send(:"#{@attribute.name}=", data)
35
36
  end
@@ -25,6 +25,11 @@ module Metaschema
25
25
  symbol].freeze
26
26
  RESERVED_CLASS_NAMES = %w[Base Hash Method Object Class Module].freeze
27
27
 
28
+ # Emitted callback names are json_<direction>_<subject>, optionally with a
29
+ # soa prefix. Anchors the direction token so a field named `valid-from`
30
+ # cannot be mistaken for the `from` direction.
31
+ CALLBACK_DIRECTION = /\A(json_(?:assembly_soa_|soa_)?)(from|to)_(.+)\z/
32
+
28
33
  def initialize(classes, module_name, generator)
29
34
  @classes = classes
30
35
  @module_name = module_name
@@ -262,15 +267,78 @@ module Metaschema
262
267
  <<~RUBY
263
268
  # frozen_string_literal: true
264
269
 
270
+ # Generated by metaschema #{generator_stamp}
271
+
265
272
  module #{@module_name}
266
273
  class Base < Lutaml::Model::Serializable
267
274
  def self.lutaml_default_register
268
275
  :#{register_id}
269
276
  end
277
+
278
+ class << self
279
+ # Declares a metaschema field class: in JSON and YAML it carries a
280
+ # bare scalar, not an object, unless one of its flags is set.
281
+ # `key` is the mapping key that carries :content.
282
+ def scalar_field(key, collection: false)
283
+ @scalar_key = key
284
+ @scalar_collection = collection
285
+
286
+ # A scalar nested in a parent reaches the field class through
287
+ # .cast, not of_json; lutaml-model only honours a .cast defined
288
+ # on the class itself, so it is defined here, not on Base.
289
+ define_singleton_method(:cast) do |value|
290
+ if scalar_content?(value) && !value.nil? && !value.is_a?(self)
291
+ wrap_scalar(value)
292
+ else
293
+ super(value)
294
+ end
295
+ end
296
+ end
297
+
298
+ def of_json(doc, options = {})
299
+ scalar_content?(doc) ? wrap_scalar(doc) : super
300
+ end
301
+
302
+ def of_yaml(doc, options = {})
303
+ scalar_content?(doc) ? wrap_scalar(doc) : super
304
+ end
305
+
306
+ def as_json(instance, options = {})
307
+ collapse_scalar(super)
308
+ end
309
+
310
+ def as_yaml(instance, options = {})
311
+ collapse_scalar(super)
312
+ end
313
+
314
+ private
315
+
316
+ def scalar_content?(doc)
317
+ !@scalar_key.nil? && !doc.is_a?(::Hash) && !doc.is_a?(::Array)
318
+ end
319
+
320
+ def wrap_scalar(doc)
321
+ new(content: @scalar_collection ? [doc] : doc)
322
+ end
323
+
324
+ def collapse_scalar(result)
325
+ return result unless @scalar_key && result.is_a?(::Hash) &&
326
+ result.keys == [@scalar_key]
327
+
328
+ value = result[@scalar_key]
329
+ value = value.first if value.is_a?(::Array) && value.length == 1
330
+ value.is_a?(::Array) ? result : value
331
+ end
332
+ end
270
333
  end
271
334
  RUBY
272
335
  end
273
336
 
337
+ def generator_stamp
338
+ revision = Metaschema.generator_revision
339
+ revision ? "#{Metaschema::VERSION} (#{revision})" : Metaschema::VERSION
340
+ end
341
+
274
342
  def derive_register_id
275
343
  if @module_name.include?("::")
276
344
  parts = @module_name.split("::")
@@ -319,6 +387,8 @@ module Metaschema
319
387
  kv_source = emit_key_value_mapping(klass)
320
388
  lines.concat(kv_source) if kv_source
321
389
 
390
+ lines.concat(emit_scalar_field_declaration(klass))
391
+
322
392
  # Custom methods for with: callbacks
323
393
  custom_methods = emit_custom_methods(klass)
324
394
  lines.concat(custom_methods) if custom_methods.any?
@@ -441,6 +511,7 @@ module Metaschema
441
511
  methods = []
442
512
  custom_method_names = (klass.instance_methods(false) - Lutaml::Model::Serializable.instance_methods)
443
513
  .select { |m| m.to_s.start_with?("json_") }
514
+ .sort_by { |m| custom_method_sort_key(m) }
444
515
 
445
516
  return methods if custom_method_names.empty?
446
517
 
@@ -477,6 +548,43 @@ module Metaschema
477
548
  methods
478
549
  end
479
550
 
551
+ # Stable, generator-version-independent ordering for emitted custom
552
+ # callbacks. Groups a field's from/to together (from first) and orders by
553
+ # the attribute subject, so regenerated source diffs reflect only real
554
+ # changes rather than incidental instance_methods ordering.
555
+ def custom_method_sort_key(method_name)
556
+ name = method_name.to_s
557
+ match = CALLBACK_DIRECTION.match(name)
558
+ return [name, 0] unless match
559
+
560
+ prefix, direction, subject = match.captures
561
+ ["#{prefix}#{subject}", direction == "from" ? 0 : 1]
562
+ end
563
+
564
+ # Field classes carry a scalar value in JSON/YAML, not an object. The
565
+ # behaviour lives on the emitted Base class; a field class only declares its
566
+ # mapping key and whether content is a collection.
567
+ #
568
+ # Reads the marker FieldFactory sets rather than looking for a :content
569
+ # attribute: an assembly can carry a member named `content` too, and
570
+ # collapsing one to a bare scalar would lose the rest of the object.
571
+ def emit_scalar_field_declaration(klass)
572
+ return [] unless klass.instance_variable_get(:@metaschema_scalar_field)
573
+
574
+ key = scalar_key(klass)
575
+ return [] unless key
576
+
577
+ collection = klass.attributes[:content].collection ? "true" : "false"
578
+ ["", " scalar_field #{key.inspect}, collection: #{collection}"]
579
+ end
580
+
581
+ # The key_value mapping key that carries :content. Nil for a field whose key
582
+ # is chosen at runtime by a json-value-key-flag; such a field declares
583
+ # nothing and keeps object form, matching the runtime.
584
+ def scalar_key(klass)
585
+ klass.mappings_for(:json).find_by_to(:content)&.name
586
+ end
587
+
480
588
  def emit_scalar_from_method(klass, method_name)
481
589
  attr_name = find_attr_for_method(klass, method_name)
482
590
  return nil unless attr_name
@@ -536,7 +644,13 @@ module Metaschema
536
644
 
537
645
  lines << " current = instance.instance_variable_get(:@#{attr_name})"
538
646
  lines << " if current.is_a?(Array)"
539
- lines << " doc[\"#{json_name}\"] = current.map { |item| item.respond_to?(:content) ? item.content : item }"
647
+ if has_flags && tc
648
+ lines << " doc[\"#{json_name}\"] = current.map do |item|"
649
+ lines << " item.is_a?(Lutaml::Model::Serializable) ? #{tc}.as_json(item) : item"
650
+ lines << " end"
651
+ else
652
+ lines << " doc[\"#{json_name}\"] = current.map { |item| item.respond_to?(:content) ? item.content : item }"
653
+ end
540
654
  lines << " elsif current"
541
655
  if has_flags && tc
542
656
  lines << " if current.is_a?(Lutaml::Model::Serializable)"
@@ -649,7 +763,14 @@ module Metaschema
649
763
  lines << " parsed = items"
650
764
  end
651
765
 
652
- lines << " instance.instance_variable_set(:@#{attr_name}, parsed)"
766
+ if asm_attr.collection
767
+ lines << " instance.instance_variable_set(:@#{attr_name}, parsed)"
768
+ else
769
+ lines << " unless parsed.length == 1"
770
+ lines << " raise Lutaml::Model::CollectionTrueMissingError.new(:#{attr_name}, instance.class)"
771
+ lines << " end"
772
+ lines << " instance.instance_variable_set(:@#{attr_name}, parsed.first)"
773
+ end
653
774
  lines << " end"
654
775
  lines
655
776
  end
@@ -668,22 +789,22 @@ module Metaschema
668
789
  lines << ""
669
790
  lines << " def #{method_name}(instance, doc)"
670
791
  lines << " current = instance.instance_variable_get(:@#{attr_name})"
671
- lines << " if current.is_a?(Array)"
672
- lines << " result = current.map do |item|"
792
+ lines << " return if current.nil?"
793
+ lines << " items = current.is_a?(Array) ? current : [current]"
794
+ lines << " result = items.map do |item|"
673
795
 
674
796
  if tc
675
- lines << " if item.is_a?(Lutaml::Model::Serializable)"
676
- lines << " #{tc}.as_json(item)"
677
- lines << " else"
678
- lines << " item"
679
- lines << " end"
797
+ lines << " if item.is_a?(Lutaml::Model::Serializable)"
798
+ lines << " #{tc}.as_json(item)"
799
+ lines << " else"
800
+ lines << " item"
801
+ lines << " end"
680
802
  else
681
- lines << " item.respond_to?(:to_h) ? item.to_h : item"
803
+ lines << " item.respond_to?(:to_h) ? item.to_h : item"
682
804
  end
683
805
 
684
- lines << " end"
685
- lines << " doc[\"#{json_name}\"] = result.length == 1 ? result.first : result"
686
806
  lines << " end"
807
+ lines << " doc[\"#{json_name}\"] = result.length == 1 ? result.first : result"
687
808
  lines << " end"
688
809
  lines
689
810
  end
@@ -1,5 +1,35 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Metaschema
4
- VERSION = "0.2.3"
4
+ VERSION = "0.2.4"
5
+
6
+ class << self
7
+ # Git revision of this checkout, for stamping generated source so a
8
+ # downstream repo can trace which generator produced a file. Nil when the
9
+ # gem runs from an installed copy with no git metadata.
10
+ #
11
+ # Shells out rather than reading .git by hand: a worktree's .git is a file,
12
+ # refs may be packed, and HEAD may be detached. git already knows all that.
13
+ def generator_revision
14
+ return @generator_revision if defined?(@generator_revision)
15
+
16
+ @generator_revision = read_git_revision
17
+ end
18
+
19
+ private
20
+
21
+ def read_git_revision
22
+ root = File.expand_path("../..", __dir__)
23
+ return nil unless File.exist?(File.join(root, ".git"))
24
+
25
+ revision = IO.popen(
26
+ ["git", "rev-parse", "--short=12", "HEAD"],
27
+ chdir: root, err: File::NULL, &:read
28
+ ).to_s.strip
29
+
30
+ revision.empty? ? nil : revision
31
+ rescue StandardError
32
+ nil
33
+ end
34
+ end
5
35
  end
data/lib/metaschema.rb CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  require "nokogiri"
4
4
  require "lutaml/model"
5
+ require_relative "metaschema/version"
5
6
 
6
7
  module Metaschema
7
8
  class Error < StandardError; end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: metaschema
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.3
4
+ version: 0.2.4
5
5
  platform: ruby
6
6
  authors:
7
7
  - Ribose Inc.
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-10-19 00:00:00.000000000 Z
11
+ date: 2026-11-02 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: lutaml-model
@@ -16,14 +16,14 @@ dependencies:
16
16
  requirements:
17
17
  - - "~>"
18
18
  - !ruby/object:Gem::Version
19
- version: 0.8.114
19
+ version: 0.8.156
20
20
  type: :runtime
21
21
  prerelease: false
22
22
  version_requirements: !ruby/object:Gem::Requirement
23
23
  requirements:
24
24
  - - "~>"
25
25
  - !ruby/object:Gem::Version
26
- version: 0.8.114
26
+ version: 0.8.156
27
27
  - !ruby/object:Gem::Dependency
28
28
  name: nokogiri
29
29
  requirement: !ruby/object:Gem::Requirement